Launch 和 Param 函数

项目
03/22/2024

适用于：画布应用

启动网页或画布应用，并提供对启动参数的访问。

Launch

启动网页或画布应用。此函数支持：

地址（必填），画布应用程序的网页或应用程序 URI 的 URL（以 /providers/Microsoft.PowerApps/apps/ 为前缀的应用程序 ID）。
参数（可选），要传递到网页或画布应用的命名值。在画布应用中，可以使用 Param 函数读取参数。
目标（可选），要在其中启动网页或画布应用的浏览器选项卡。

Launch 只能在行为公式中使用。

地址

网页通过 URL 地址启动。例如:

Launch( "https://bing.com" )

您可以使用网络链接或应用程序 URI（以 /providers/Microsoft.PowerApps/apps/ 为前缀的应用程序 ID）启动画布应用程序。若要查找应用的这些值，请执行以下操作：

转到 Power Apps。
从左侧导航窗格中选择应用。
选择您的应用。
从顶部菜单中选择详细信息。
您还可以选择 ...（更多命令），然后从下拉菜单中选择详细信息。
复制 Web 链接或应用 ID。

Web 链接可以在任何网页中使用，将启动画布应用。它也可以与 Launch 函数一起使用。

应用 ID 可以与 Launch 函数一起使用，但必须以 /providers/Microsoft.PowerApps/apps/ 作为前缀。例如：

Launch( "/providers/Microsoft.PowerApps/apps/f342faaf-5f82-4ace-a64b-7c1b01499231" )

设备上的本机应用无法直接启动。在某些平台上可能有间接选项可用，例如安装自定义 URL 架构或在 Web 浏览器中注册以为特定网站提供选项的本机应用。

参数

Launch 可以将参数传递到网页或画布应用。可以通过两种方式提供参数：

名称/值对的参数列表。例如：

Launch( "https://bing.com/search", "q", "Power Apps", "count", 1 )

字段值的记录。例如：
```
Launch( "https://bing.com/search", { q: "Power Apps", count: 1 } )
```
这种形式可以使名称和值之间的关联更加清晰，因此更易于使用。这是唯一支持可选 LaunchTarget 参数的形式。

地址和参数在传递前经过 URL 编码，来将某些非字母数字字符替换为 % 和十六进制数字，就像 EncodeUrl 函数对每个地址和参数所使用的。

启动网页时，可以在 URL 地址的末尾包含参数的查询字符串。提供给 Launch 的所有其他参数都将添加到查询字符串的末尾。启动画布应用时，查询字符串不起作用。

当在已经运行应用程序的移动设备上启动该应用程序时，不会在运行的应用程序中刷新参数。需要重新加载应用程序才能刷新参数。

Target

使用 LaunchTarget 参数指定在其中打开网页或应用的目标浏览器窗口。使用以下 LaunchTarget 枚举值之一或提供自定义窗口名称。

LaunchTarget 枚举	描述
New	网页或应用会在新窗口或标签页中打开。
Replace	网页或应用将替换当前的窗口或标签页。
name	代替枚举值，使用您自己的文本字符串命名窗口或标签页。Self 是仅在内部使用的名称，仅由 Launch 函数使用。它对用户看到的窗口的标题没有影响，也不会与之匹配。如果具有给定名称的窗口或标签页已经存在，其内容将被替换。否则，将创建新窗口或标签页。名称不能以下划线字符“_”开头。

在将 Replace 和 name 作为可用选项的 Web 浏览器中运行时，New 是默认枚举。在移动播放器中，New 是将指定作为可用选项的网页的默认设置；而当前的画布应用将始终被另一个画布应用替换。

备注

不支持在嵌入式场景中（例如，Power BI 或 SharePoint）将 LaunchTarget 与 New 以外的其他值一起使用，这可能会导致意外行为。以后，此行为可能会变更，或可能导致错误。

Param

当应用启动时，Param 函数可用于检索传递给应用的参数。如果没有传递指定的参数，Param 会返回 blank。

从另一个画布应用启动画布应用时，请对 Launch 函数使用 Parameter 参数。参数名称和值将自动进行 URL 编码。
从网页启动画布应用时，将参数添加到画布应用 Web 链接的查询字符串中。假设已经为 tenantId 启动了查询字符串，则需要添加 &parametername=parametervalue。例如，添加 &First%20Name=Vicki&category=3 会传递两个参数：值为 "Vicki" 的 First Name 和值为 "3" 的 category（值类型为文本）。如果参数名称和值包含空格或特殊字符，则必须进行 URL 编码，类似于使用 EncodeURL 函数。
参数名称区分大小写。
参数名称和值将自动进行 URL 解码，以在您的应用中使用。
除非重新加载应用程序，否则参数值不会改变。在已经运行应用程序的移动设备上使用启动不会刷新参数。
即使参数包含数字，Param 返回的类型也始终是文本字符串。会自动进行其他类型的转换，或使用显式转换（例如 Value 函数）显式转换为数字。

备注

对于自定义页面，该页面接受的唯一参数是：recordId 和 entityName。

语法

Launch( Address [, ParameterName1, ParameterValue1, ... ] )

Address – 必需。要启动的网页的网址或应用的 ID。
ParameterName(s) – 可选。参数名称。
ParameterValue(s) – 可选。要传递给应用或网页的相应参数的值。

Launch( Address, { [ ParameterName1: ParameterValue1, ... ] } [, LaunchTarget ] )

Address – 必需。要启动的网页的网址或应用的 ID。
ParameterName(s) – 可选。参数名称。
ParameterValue(s) – 可选。要传递给应用或网页的相应参数的值。
LaunchTarget – 可选。 LaunchTarget 枚举值或自定义名称。

Param( ParameterName )

ParameterName - 必需。传递给应用的参数的名称。

保留参数

以下关键字将保留（无论哪种情况）供内部使用，不应用作 Param() 函数中的自定义参数：

amp%3Bauthmode
amp%3Benableonbehalfof
amp%3Bhidenavbar
amp%3Blocale
appmetadataversion
authmode
channeltype
cordovapath
correlationid
调试
delegatelaunchurl
delegatelaunchurl
disablepreviewredirect
embedderorigin
enableonbehalfof
groupid
hideappsplash
hidenavbar
hint
hostclienttype
hostmode
iframecontainerid
isfullscreen
ispreviewmode
loader
loaderType
locale
位置
packagekind
packageproperties
playerresourcespath
playersessionid
powerappslanguage
screencolor
sdkversion
站点
skipappmetadata
skipiframecreation
skiplaunchappcache
source
sourcetime
standaloneconsent
teamid
teamtype
tenantId
theme
uselocalpackagehostresources
userteamrole

示例

简单启动

从画布应用到网页：

公式	Description
Launch( "http://bing.com/search", "q", "Power Apps", "count", 1 )	打开网页 https://bing.com/search?q=Power%20Apps&count=1。将打开一个新窗口或标签页。
Launch( "http://bing.com/search", { q: "Power Apps", count: 1 } )	与前面的示例相同，使用等效的记录表示法。将打开一个新窗口或标签页。
Launch( "http://bing.com/search", { q: "Power Apps", count: 1 }, LaunchTarget.Replace )	与前面的示例相同，如果在 Web 浏览器中运行，则将当前窗口或标签页替换为结果。
Launch( "http://bing.com/search", { q: "Power Apps", count: 1 }, "Search Results" )	与前面的示例相同，创建或替换名为搜索结果的窗口或标签页的内容。

从画布应用到画布应用

相应地更新应用 ID、屏幕名称和记录编号。

Launch( "/providers/Microsoft.PowerApps/apps/YOUR-APP-ID",
        { Navigate: "Second Screen", Record: 34 }
)

从网页到画布应用

相应地更新应用 ID、租户 ID、屏幕名称和记录编号。

<html>
  <body>
    <a
      href="https://apps.powerapps.com/play/e/YOUR-APP-ENVIRONMENT-ID/a/YOUR-APP-ID?tenantId=YOUR-TENANT-ID&Navigate=Second%20Screen&Record=34"
    >
      Launch canvas app
    </a>
  </body>
</html>

简单参数

上面的简单启动示例从网页或从另一个画布应用启动画布应用，显示了 Param 函数的简单示例：

公式	描述	结果
Param( "Navigate" )	应用启动并返回时，将提供 Navigate 参数。	“第二个屏幕”
Param( "Record" )	应用启动时，将提供 Record 参数。即使已将其作为数字传递给 Launch 函数，Param 的结果仍将是可以隐式或显式转换为其他类型的文本字符串。	“34”
Param( "User" )	未提供 User 参数。返回一个空白值，可以使用 IsBlank 函数进行测试。	blank

Launch 和 Param 的分步示例

以下示例使用了产品展示平板电脑布局模板。要使用此模板创建应用，请按照创建应用文章中的步骤操作，选择产品展示模板。您也可以使用自己的应用。

示例 - Launch

转到 Power Apps。
从左侧导航窗格中选择应用。
选择您的应用，然后选择编辑。
从菜单中选择插入，然后选择标签。
将标签移到屏幕右下角。
在右侧的属性窗格中，颜色选择白色，将边框宽度设置为 1。
从右侧选择 Text 属性，然后输入文本 Surface tablets in news。
从左上方的属性列表中，选择 OnSelect。
输入公式 Launch("https://www.bing.com/news/search","q","Microsoft Surface tablets")。您还可以使用您选择的任何其他 URL、参数和关键字。
保存并发布应用。
播放应用。
选择标签 Surface tablets in news 使用关键字 Microsoft Surface tablets 启动新闻搜索。

提示

为了实现可扩展性，您可以将 Launch 函数中手动输入的关键字替换为变量。

示例 - Param

转到 Power Apps。
从左侧导航窗格中选择应用。
选择您的应用，然后选择编辑。
从菜单中选择插入，然后选择标签。
将标签移到屏幕右下角。
从左上角为标签选择 Text 属性。
输入公式 Param("browser")。您也可以使用您选择的其他参数。
保存并发布应用。
从 Power Apps 中复制您的应用的 Web 链接。
打开一个新浏览器。
将应用 Web 链接粘贴到浏览器中，并在末尾附加 &browser=Microsoft%20Edge。
应用启动时，标签会显示传递的参数值。
关闭应用播放器并编辑应用。
从左侧导航的树视图中选择应用。
选择左上方的 StartScreen 属性。
输入公式 If( Param("screen") = "techspecs", TechSpecs )。

StartScreen 属性中的 If 函数检查参数是否等于某个值，在此例中值为 techspecs。如果匹配，将把 TechSpecs 屏幕控件返回给 StartScreen 属性。

备注

如果您使用的不是产品展示应用模板，则将 If 函数中的 TechSpecs 控件名称替换为您自己的应用中的屏幕控件的名称。
保存并发布应用。
打开一个新浏览器。
将应用 Web 链接粘贴到浏览器中，并在末尾附加 &screen=techspecs。
应用将直接启动，并且将 TechSpecs 用作启动屏幕。