Power Apps 中的 App 对象

适用于： 画布应用

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

Description

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

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

在“树视图”窗格中选择的应用对象的屏幕截图。“属性”窗格可见。

本文介绍以下 App 对象属性：

ActiveScreen – 当前显示的屏幕。
BackEnabled – 应用如何响应设备后退手势。
ConfirmExit 和 ConfirmExitMessage – 在关闭应用之前警告用户。
连接字符串 - 设置 Application Insights 日志记录。
公式 – 定义命名公式、用户定义的函数和用户定义的类型。
OnError – 全局处理错误。
OnStart - 在应用启动时运行逻辑。
StartScreen – 设置应用加载时第一个显示的屏幕。
StudioVersion – 返回发布应用的 Power Apps Studio 版本。

ActiveScreen 属性

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

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

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

BackEnabled 属性

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

ConfirmExit 属性

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

Note

ConfirmExit 在嵌入的应用（例如 Power BI 和 SharePoint）中不起作用。
自定义页面中不支持 ConfirmExit。
现在，如果启用了 延迟加载 预览功能（默认为新应用），这些属性才能引用第一个屏幕上的控件。如果引用其他屏幕，Power Apps Studio 不会显示错误，但已发布的应用未在 Power Apps Mobile 或浏览器中打开。 Microsoft正在努力解除此限制。同时，在“设置即将推出的功能”>中关闭延迟加载（预览版下）。

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

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

Example

将 App 对象的 ConfirmExit 属性设置为以下表达式：
```
AccountForm.Unsaved Or ContactForm.Unsaved
```
如果用户在任一窗体中更改数据，然后尝试关闭应用而不保存这些更改，将显示该对话框。
将 App 对象的 ConfirmExitMessage 属性设置为以下公式：
```
If( AccountForm.Unsaved,
    "Accounts form has unsaved changes.",
    "Contacts form has unsaved changes."
)
```
当用户在任一窗体中更改数据，然后尝试关闭应用而不保存这些更改时，对话框会显示特定于窗体的消息。

连接字符串属性

使用 连接字符串 属性将系统生成的应用程序日志导出到 Application Insights。

设置连接字符串：

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

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

公式属性

使用 Formulas 属性定义应用中的可重用逻辑。 Formulas 属性支持三种构造：

命名公式 – 为公式分配名称，并在整个应用中重复使用该值。
用户定义的函数 – 采用参数并返回值的命名公式。
用户定义的类型 – 可以在公式和函数签名中重复使用的命名类型。

命名公式

使用 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 = 表达式一样，可以改为写入 名称 = 表达式 ，然后在应用中重复使用名称来替换 表达式。在 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 – 必需。用户定义的函数的名称。
ParameterNames —可选。函数参数的名称。
ParameterType(s) – 可选。类型的名称、内置数据类型名称、数据源名称或使用 Type 函数定义的类型。
ReturnType – 必需。函数的返回值的类型。
Formula（公式） –必需。根据参数计算函数值的公式。

必须键入每个参数和用户定义的函数的输出。在此示例中，SelectedGenre: Text定义函数的第一个参数类型为 Text，并且SelectedGenre是筛选器操作的正文中使用的参数的名称。有关支持的类型名称，请参阅数据类型。 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 ) 来检查储蓄中是否有 12 个，如果是这样，请将其借记 12，并将 12 添加到“已用”变量。此函数的返回类型为 Void，它不返回值。

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

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

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

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

用户定义的类型

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

OnError 属性

使用 OnError 在应用中的任何位置发生错误时采取措施。它提供在向最终用户显示错误横幅之前截获错误横幅的全局机会。还可以使用它通过跟踪函数或写入数据库或 Web 服务来记录错误。

在画布应用中，每个公式的计算结果都会接受检查，确认是否有错误。如果遇到错误， 则 OnError 将使用应用的相同 FirstError 和 AllErrors 范围变量进行评估，前提是整个公式包装在 IfError 函数中。

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

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

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

尽管 OnError 单独处理每个错误，但每个错误可能不会单独显示默认错误横幅。为了避免同时显示太多错误横幅，如果最近显示相同的错误横幅，则不会再次显示相同的错误横幅。

Example

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

Label1.Text = 1/Slider1.Value

通过公式 Label1.Text = 1/Slider1.Value 绑定的 Label 和 slider 控件。

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

Slider 控件移动到 0，导致除数为零错误和错误横幅。

我们来看看具体发生的情况：

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

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

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

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

设置为生成 Trace 的 App.OnError 公式。

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

Slider 控件移动到 0，导致除数为零错误，但没有错误横幅。

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

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

OnStart 属性

Note

使用 OnStart 属性可能会导致加载应用时出现性能问题。在将逻辑添加到 OnStart 之前，请考虑以下替代方法：

若要缓存数据或设置全局变量，请尽可能在 Formulas 属性中使用命名公式。
若要设置要显示的第一个屏幕，请使用 StartScreen 属性而不是 Navigate。
若要在特定屏幕显示时运行逻辑，请使用屏幕的 OnVisible 属性。

根据上下文，默认情况下可能会禁用 OnStart 属性。如果看不到它，并且需要使用它，请检查应用的“高级”设置，以获取开关以启用它。

启用非阻止 OnStart 规则（默认值）时， OnStart 会与其他应用规则同时运行。因此：

在其他应用规则读取变量时， 在 OnStart 中初始化的变量可能无法完全初始化。
在 App.OnStart 或 Screen.OnVisible 完成运行之前，屏幕可以呈现并变为交互式屏幕，尤其是在这些函数需要很长时间时。

OnStart 属性在用户启动应用时运行。使用此属性可以：

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

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

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

“运行 OnStart”的应用项快捷方式菜单

Note

OnStart 属性中的 Navigate 函数已停用。现有应用仍然有效。在有限的时间内，可以在应用设置（ 已停用）中启用它。但是，以这种方式使用 Navigate 可能会导致应用加载延迟，因为它强制系统在显示第一个屏幕之前完成运行 OnStart 。请改用 StartScreen 属性设置显示的第一个屏幕。
停用的开关适用于在 2021 年 3 月之前创建的应用，在 2021 年 3 月和现在之间，你已将 导航到OnStart 。在 Power Apps Studio 中编辑这些应用时，会看到错误。打开已停用切换以清除此错误。

StartScreen 属性

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

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

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

Note

全局变量和集合（包括 OnStart 中创建的变量和集合）在 StartScreen 中不可用。命名公式可用，并且通常是在整个应用程序中重复使用的公式的更好替代方法。

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

在 Studio 中更改 StartScreen 后，将鼠标悬停在“树视图”窗格中的应用对象上，选择省略号（...），然后选择“导航到 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 返回文本。此文本的格式可能会随时间而变化，因此将其视为整体，不提取各个部分。

反馈

此页面是否有帮助？

Last updated on 2026-06-12

Power Apps 中的 App 对象

Description

ActiveScreen 属性

BackEnabled 属性

ConfirmExit 属性

ConfirmExit

ConfirmExitMessage

Example

连接字符串属性

公式属性

命名公式

用户定义的函数

行为用户定义的函数

用户定义的类型

OnError 属性

Example

OnStart 属性

StartScreen 属性

示例

StudioVersion 属性

反馈

其他资源