Power Apps 中的 App 对象

适用于： 画布应用

获取有关当前正在运行的应用的信息并控制应用的行为。

描述

与控件一样， App 对象具有属性，用于标识显示哪个屏幕并提示你保存更改，以免丢失更改。 每个应用都有一个 App 对象。

为 App 对象的某些属性编写公式。 在树视图窗格的顶部，像选择任何其他控件或屏幕一样选择 App 对象。 若要查看或编辑某个对象的属性，请在编辑栏左侧的下拉列表中选择它。

ActiveScreen 属性

ActiveScreen 属性标识当前显示的屏幕。

该属性返回一个屏幕对象。 使用它来引用当前屏幕的属性，如公式 App.ActiveScreen.Name 的名称。 还可以将此属性与另一个屏幕对象进行比较，例如与比较公式 App.ActiveScreen = Screen2 来检查 Screen2 是否为当前屏幕。

使用 “后退 ”或 “导航” 函数切换显示的屏幕。

BackEnabled 属性

BackEnabled 属性更改了应用在 Power Apps 移动应用中运行时对设备后退手势（在 Android 设备上轻扫或使用硬件后退按钮）或从 iOS 设备上的左侧轻扫的方式。 启用后，设备后退手势会返回到最近显示的屏幕，这类似于 “后退 ”公式。 禁用后，设备后退手势会将用户转到应用列表。

ConfirmExit 属性

没有人希望丢失未保存的更改。 使用 ConfirmExit 和 ConfirmExitMessage 属性在关闭应用之前警告用户。

ConfirmExit

ConfirmExit 是一个布尔属性，如果 为 true，则会在应用关闭之前打开确认对话框。 默认情况下，此属性为 false，不会出现对话框。

当用户在应用中可能未保存的更改时，请使用此属性在退出应用之前显示确认对话框。 使用检查变量和控件属性的公式（例如，编辑窗体控件的未保存属性）。

在数据丢失的任何情况下，都会显示确认对话框，例如：

• 运行 Exit 函数。
• 如果应用在浏览器中运行：
  • 关闭运行应用的浏览器或浏览器选项卡。
  • 选择浏览器的后退按钮。
  • 使用 LaunchTarget of Self 运行 Launch 函数。
• 如果应用在 Power Apps Mobile 中运行（iOS 或 Android）：
  • 轻扫以切换到 Power Apps Mobile 中的其他应用。
  • 选择 Android 设备上的后退按钮。
  • 运行 Launch 函数以启动另一个画布应用。

确认对话框的确切外观可能因设备和 Power Apps 版本而异。

“确认”对话框不会显示在 Power Apps Studio 中。

ConfirmExitMessage

默认情况下，确认对话框会以用户语言显示一条常规消息，如“您可能有未保存的更改。”。

使用 ConfirmExitMessage 可以在确认对话框中提供自定义消息。 如果此属性为空白，将使用默认值。 根据需要截断自定义消息以适应确认对话框，因此将消息保留为几行。

在浏览器中，确认对话框可以从浏览器显示通用消息。

示例

1. 将 App 对象的 ConfirmExit 属性设置为以下表达式：

   AccountForm.Unsaved Or ContactForm.Unsaved
   

   该对话框显示用户是否在任一窗体中更改数据，然后尝试关闭应用而不保存这些更改。或者用户更改了任一窗体中的数据，然后尝试关闭应用而不保存这些更改。

   [！div clas1. 将 App 对象的 ConfirmExitMessage 属性设置为以下公式：

   If( AccountsForm.Unsaved,
       "Accounts form has unsaved changes.",
       "Contacts form has unsaved changes."
   )
   

   该对话框显示用户是否更改了帐户窗体中的数据，然后尝试关闭应用而不保存这些更改。

   

为 Application Insights 设置连接字符串

若要将系统生成的应用程序日志导出到 Application Insights，请为画布应用设置 连接字符串 。

1. 打开您的应用程序，在 Power Apps Studio 中进行编辑。
2. 在左侧导航树视图中选择应用对象。
3. 在属性窗格中输入 连接字符串 。

如果未将数据发送到 Application Insights，请联系 Power Platform 管理员，并在租户级别检查 App Insights 是否已禁用。

公式属性

在 Formulas 属性中使用命名公式来定义可在整个应用中重复使用的公式。

在 Power Apps 中，公式确定控件属性值。 例如，要在应用中设置一致的背景颜色，您可以将每个公式的 Fill 属性设置为一个通用公式：

Label1.Fill: ColorValue( Param( "BackgroundColor" ) )
Label2.Fill: ColorValue( Param( "BackgroundColor" ) )
Label3.Fill: ColorValue( Param( "BackgroundColor" ) )

由于此公式可能出现在很多地方，如果需要更改，更新过程会很枯燥且易于出错。 您可以在 OnStart 中创建一个全局变量来设置一次颜色，然后在整个应用中重复使用该值：

App.OnStart: Set( BGColor, ColorValue( Param( "BackgroundColor" ) ) )
Label1.Fill: BGColor
Label2.Fill: BGColor
Label3.Fill: BGColor

虽然这种方法更好，但它还依赖于在 BGColor 的值建立之前运行的 OnStart。 BGColor 也可能在应用的某个角落被操作，而制作者并不知道，被其他人进行了更改，难以追踪。

命名公式提供了另一种选择。 就像我们通常编写 control-property = expression 一样，我们可以改为编写 name = expression，然后在整个应用中重用 name 来替换 expression。 这些公式的定义在 Formulas 属性中完成：

App.Formulas: BGColor = ColorValue( Param( "BackgroundColor" ) );
Label1.Fill: BGColor
Label2.Fill: BGColor
Label3.Fill: BGColor

使用命名公式的优点包括：

• 公式的值始终可用。 没有时间依赖性，没有必须在设置值之前首先运行的 OnStart，也没有公式值不正确的时间。 命名公式可以以任何顺序相互引用，只要它们不创建循环引用。 它们可以并行计算。
• 公式的值始终是最新的。 公式可以执行依赖于控件属性或数据库记录的计算，随着它们的变化，公式的值会自动更新。 您不需要像使用变量时那样手动更新值。 公式仅在需要时重新计算。
• 公式的定义不可变。 Formulas 中的定义是唯一的真实来源，值不能在应用的其他地方更改。 对于变量，某些代码可能会意外更改值，但这种难以调试的情况在命名公式中是不可能的。
• 公式的计算可以推迟。 由于该值是不可变的，因此始终可根据需要进行计算，这意味着直到需要的时候才需要计算。 在应用的 screen2 显示之前不使用的公式值不需要在 screen2 可见之前计算。 推迟这项工作可以缩短应用程序的加载时间。 命名公式是声明性的，可以为系统提供优化公式计算方式和时间的机会。
• 命名公式是一个 Excel 概念。 Power Fx 会尽可能使用 Excel 概念，因为很多人都非常了解 Excel。 命名公式相当于 Excel 中的命名单元格和命名公式，由名称管理器管理。 它们会像电子表格和控件属性的单元格一样自动重新计算。

命名公式在 Formulas 属性中逐个定义，每个公式以分号结尾。 公式的类型是根据公式中的元素类型以及它们如何一起使用来推断的。 例如，这些命名公式从 Dataverse 检索有关当前用户的有用信息：

UserEmail = User().Email;
UserInfo = LookUp( Users, 'Primary Email' = User().Email );
UserTitle = UserInfo.Title;
UserPhone = Switch( UserInfo.'Preferred Phone', 
                    'Preferred Phone (Users)'.'Mobile Phone', UserInfo.'Mobile Phone',
                    UserInfo.'Main Phone' );

如果 UserTitle 的公式需要更新，可以在这一个位置轻松完成。 如果应用中不需要 UserPhone，不会对 Dataverse 中的用户表进行这些调用。 包含未使用的公式定义没有惩罚。

命名公式的一些限制：

• 不能在应用中使用行为函数，否则会造成负面影响。
• 不能创建循环引用。 不允许在同一个应用中使用 a = b; 和 b = a;。

用户定义函数

Power Fx 包括很多内置函数，如 If、Text 和 Set。 用户定义的函数使您能够编写自己的函数来获取参数并返回值，就像内置函数一样。 可以将用户定义的函数视为命名公式的扩展，用于添加参数并支持行为公式。

例如，您可以定义一个命名公式，用于从库中返回小说书籍：

Library = [ { Title: "The Hobbit", Author: "J. R. R. Tolkien", Genre: "Fiction" },
            { Title: "Oxford English Dictionary", Author: "Oxford University", Genre: "Reference" } ];

LibraryFiction = Filter( Library, Genre = "Fiction" );

如果没有参数，我们需要为每个流派定义单独的命名公式。 但是，让我们参数化我们的命名公式：

LibraryType := Type( [ { Title: Text, Author: Text, Genre: Text } ] );

LibraryGenre( SelectedGenre: Text ): LibraryType = Filter( Library, Genre = SelectedGenre );

现在，我们可以使用单个用户定义函数调用 LibraryGenre( "Fiction" )、LibraryGenre( "Reference" ) 或筛选其他类型。

语法为：

FunctionName（[ ParameterName1： ParameterType1 [ ， ParameterName2： ParameterType2 ... ] ] ] ] ： ReturnType = ;

• FunctionName – 必需。 用户定义函数的名称。
• ParameterName(s) – 可选。 函数参数的名称。
• ParameterType(s) – 可选。 类型的名称，内置数据类型名称、数据源名称或使用 Type 函数定义的类型。
• ReturnType – 必需。 函数的返回值的类型。
• Formula – 必需。 根据参数计算函数值的公式。

必须为每个参数和用户定义函数的输出指定类型。 在此示例中，SelectedGenre: Text 将函数的第一个参数定义为 Text 类型，SelectedGenre 是在 Filter 操作的主体中使用的参数的名称。 有关支持的类型名称，请参阅数据类型。 Type 函数用于为我们的图书馆创建聚合类型，以便我们可以从函数返回书籍表。

我们将 LibraryType 定义为复数的记录类型表。 如果我们想将一本书传递给一个函数，我们可以使用 RecordOf 函数提取此表的记录类型：

BookType := Type( RecordOf( LibraryType ) );

IsGenre( Book: BookType, SelectedGenre: Text ): Boolean = (Book.Genre = SelectedGenre);

函数参数的记录匹配比其他 Power Fx 部分更严格。 记录值的字段必须是类型定义的正确子集，并且不能包含其他字段。 例如，IsGenre( { Title: "My Book", Published: 2001 }, "Fiction" ) 将导致错误。

请注意，用户定义的函数尚不支持递归。

行为用户定义的函数

命名公式和大多数用户定义的函数不支持具有副作用的行为函数，如 Set 或 Notify。 通常，如果可以，最好避免更新状态，而是依赖于函数式编程模式，并允许 Power Fx 根据需要自动重新计算公式。 但是，在某些情况下，这是不可避免的。 要在用户定义的函数中包含行为逻辑，请用大括号将正文括起来：

Spend( Amount: Number ) : Void = {
    If( Amount > Savings, 
        Error( $"{Amount} is more than available savings" ),
        Set( Savings, Savings - Amount );
        Set( Spent, Spent + Amount) 
    );
}

现在我们可以调用 Spend( 12 ) 来检查我们的 Savings 中是否有 12，如果有，将其减去 12 并将 12 添加到 Spent 变量中。 此函数的返回类型为 Void，它不返回值。

行为用户定义函数的语法为：

FunctionName（[ ParameterName1： ParameterType1 [ ， ParameterName2： ParameterType2 ... ] ] ] ] ： ReturnType = { Formula1 [ ;Formula2 ... ]};

• FunctionName – 必需。 用户定义函数的名称。
• ParameterName(s) – 可选。 函数参数的名称。
• ParameterType(s) – 可选。 类型的名称，内置数据类型名称、数据源名称或使用 Type function 函数定义的类型。
• ReturnType – 必需。 函数的返回值的类型。 如果函数未返回值，使用 Void。
• Formula(s) – 必需。 根据参数计算函数值的公式。

与所有 Power Fx 公式一样，当遇到错误时，执行不会结束。 调用 Error 函数后，If 函数将阻止对 Savings 和 Spent 更改。 IfError 函数还可用于防止发生错误后进一步执行。 即使它返回 Void，如果出现问题，公式仍会返回错误。

用户定义类型

命名公式可以与 Type 函数一起使用，来创建用户定义类型。 使用 := 代替 = 来定义用户定义类型，例如，Book := Type( { Title: Text, Author: Text } )。 有关详细信息和示例，请参阅 Type 函数。

OnError 属性

使用 OnError 在应用中的任何位置发生错误时采取措施。 它提供了一个在错误横幅显示给最终用户之前拦截错误横幅的全局机会。 另外还可用于使用 Trace 函数记录错误或写入数据库或 Web 服务。

在画布应用中，每个公式的计算结果都会接受检查，确认是否有错误。 如果发生错误，将使用相同的 FirstError 和 AllErrors 范围变量对 OnError 进行计算，如果整个公式已包装在 IfError 函数中，将使用这些变量。

如果 OnError 为空，则默认错误横幅显示错误的 FirstError.Message 。 定义 OnError 公式会替代此行为，以便创建者可以根据需要处理错误报告。 可以通过重新引发 Error 函数的错误来请求 OnError 中的默认行为。 如果要筛选掉或以不同的方式处理某些错误，但让其他人通过，请使用重新引发方法。

OnError 不能像 IfError 那样替换计算中的错误。 如果调用了 OnError，说明错误已经发生，并且已经通过公式计算（如 IfError）进行了处理；OnError 仅控制错误报告。

OnError 公式同时计算，并且其计算可能与处理其他错误重叠。 例如，如果在 OnError 顶部设置全局变量，并在以后在同一公式中读取它，则该值可能已更改。 使用 With 函数创建公式在本地的命名值。

虽然每个错误都由 OnError 单独处理，但每个错误都可能不会单独显示默认错误横幅。 为避免同时显示太多错误横幅，如果最近已显示了某个错误，则不会再次显示同一个错误横幅。

示例

考虑通过以下公式绑定在一起的 Label 控件和 Slider 控件：

Label1.Text = 1/Slider1.Value

滑块默认为 50。 如果滑块移动到 0，Label1 将不显示任何值，错误横幅将显示：

我们来详细地看一看发生了什么：

1. 用户将滑块向左移动，Slide1.Value 属性变为 0。
2. Label1.Text 将自动重新计算。 出现除数为零，发生错误。
3. 此公式中没有 IfError。 公式计算返回除数为零错误。
4. Label1.Text 无法为此错误显示任何内容，因此它显示空白状态。
5. OnError 被调用。 由于没有处理程序，标准错误横幅会显示并包含错误信息。

如果需要，还可以将公式更改为 Label1.Text = IfError( 1/Slider1.Value, 0 )。 使用 IfError 意味着没有错误或错误横幅。 无法更改 OnError 错误的值，因为错误已发生 — OnError 仅控制报告方式。

如果添加 OnError 处理程序，它不会影响步骤 5 之前的步骤，但会更改错误报告方式：

Trace( $"Error {FirstError.Message} in {FirstError.Source}" )

使用此 OnError 处理程序，应用用户不会看到任何错误。 但错误将添加到监视器的跟踪中，包括 FirstError 的错误信息的来源：

如果还想要显示默认错误横幅以及跟踪，在跟踪调用后重新引发 Error 函数的错误，就好像跟踪不存在一样：

Trace( $"Error {FirstError.Message} in {FirstError.Source}" );
Error( FirstError )

OnStart 属性

OnStart 属性在用户启动应用时运行。 此属性通常用于：

• 使用 Collect 函数检索和缓存集合中的数据。
• 使用 Set 函数设置全局变量。

此公式在显示第一个屏幕之前运行。 不加载屏幕，因此您无法使用 UpdateContext 函数设置上下文变量。 但可以使用 Navigate 函数传递上下文变量。

更改 OnStart 属性后，将鼠标悬停在树视图窗格中的应用对象上，选择省略号（...），然后选择“运行 OnStart”。 与首次加载应用时不同，已设置现有集合和变量。 要从空集合开始，请使用 ClearCollect 函数而不是 Collect 函数。

StartScreen 属性

StartScreen 属性设置第一个屏幕显示哪个屏幕。 当应用加载并返回要显示的屏幕对象时，会对其进行一次评估。 默认情况下，此属性为空，工作室树视图中的第一个屏幕首先显示。

StartScreen 是一个数据流属性，不能包含行为函数。 所有数据流函数都可用。 使用这些函数和信号来决定首先显示哪个屏幕：

• 读取用于启动应用的参数的 Param 函数。
• 读取有关当前用户的信息的 User 函数。
• LookUp、Filter、CountRows、Max 和从数据源读取的其他函数。
• 通过连接器调用 API。 确保调用快速返回。
• Connection、Compass 和 App 等信号。

如果 StartScreen 返回错误，则 Studio 树视图中的第一个屏幕显示为未设置 StartScreen 。 使用 IfError 函数捕获任何错误并重定向到错误屏幕。

在 Studio 中更改 StartScreen 后，将鼠标悬停在“树视图”窗格中的应用对象上，选择省略号（...），然后选择“导航到 StartScreen”。 屏幕会更改，就像刚刚加载应用一样。

示例

Screen9

Screen9 每当应用启动时显示第一个。

If( Param( "admin-mode" ) = 1, HomeScreen, AdminScreen )

检查参数“管理员模式”是否已设置，并使用它来确定 HomeScreen 或 AdminScreen 是否首先显示。

If( LookUp( Attendees, User = User().Email ).Staff, StaffPortal, HomeScreen )

检查与会者是否为教职员工，并将他们定向到启动时的正确屏幕。

IfError( If( CustomConnector.APICall() = "Forest", 
             ForestScreen, 
             OceanScreen 
         ), 
         ErrorScreen 
)

根据 API 调用将应用定向到 ForestScreen 或 OceanScreen。 如果 API 失败，应用将改用 ErrorScreen 。

StudioVersion 属性

使用 StudioVersion 属性显示或记录用于发布应用的 Power Apps Studio 版本。 在调试和检查应用是否已使用最新版本的 Power Apps Studio 重新发布时，此属性会有所帮助。

StudioVersion 返回文本。 此文本的格式可能会随时间而变化，因此将其视为整体，不提取各个部分。