Power Apps 中的 App 物件

適用於： 畫布應用程式 模型導向應用程式

提供目前正在執行之應用程式和對應用程式行為控制的相關資訊。

描述

與控制項一樣，應用程式 物件提供屬性，可標識正在顯示的畫面以及提示使用者儲存變更，以免遺失。 每個應用程式都有一個應用程式物件。

您可以為應用程式物件的某些屬性編寫公式。 在樹狀檢視窗格的頂端，選取您要為任何其他控制項或畫面做的應用程式物件。 在公式列左側的下拉式清單中選取物件，即可查看並編輯其中一個物件的屬性。

ActiveScreen 屬性

ActiveScreen 屬性標示正在顯示的畫面。

此屬性會傳回畫面物件。 使用它來參考目前顯示畫面的屬性，例如帶有公式 App.ActiveScreen.Name 的名稱。 您還可以將此屬性與另一個畫面物件進行比較，例如使用比較公式 App.ActiveScreen = Screen2 來測試 Screen2 是否為目前顯示的畫面。

使用 Back 或 Navigate 函式來變更顯示畫面。

BackEnabled 屬性

BackEnabled 屬性可變更應用程式在 Power Apps 行動裝置中執行時回應裝置返回手勢 (在 Android 裝置上滑動或使用硬體返回按鈕、在 iOS 裝置上從左側滑動) 的方式。 啟用後，裝置返回手勢會瀏覽回最近顯示的畫面，這類似於 Back 公式。 停用後，裝置返回手勢會將使用者返回應用程式清單。

ConfirmExit 屬性

沒人想要遺失未儲存的變更。 在使用者關閉應用程式之前，會使用 ConfirmExit 及 ConfirmExitMessage 屬性來警告使用者。

注意

• ConfirmExit 無法在 Power BI 和 SharePoint 等嵌入的應用程式中運作。
• 現在，如果已啟用延遲載入預覽功能 (新的應用程式預設會啟用此功能)，這些屬性就只能參考第一個畫面上的控制項。 如果是參照，則 Power Apps Studio 不會顯示錯誤，但是所產生並已發佈的應用程式將無法在行動版 Power Apps 或瀏覽器中開啟。 我們正積極改善這項限制。 同時，您可以在設定>即將推出的功能中 (在預覽下) 關閉延遲載入。

ConfirmExit

ConfirmExit是一種布林值屬性，當設定為 true 時，會在應用程式關閉之前，開啟確認對話方塊。 根據預設，此屬性設定為 false，且不會顯示任何對話方塊。

如果使用者在應用程式中可能有未儲存的變更，請使用此屬性在退出應用程式之前顯示確認對話方塊。 請使用可檢查變數和控制項屬性 (例如，Edit form 控制項的 Unsaved 屬性) 的公式。

確認對話方塊會出現在所有可能會遺失資料的情形中，如下列範例所示：

• 執行 Exit 函式。
• 如果應用程式是在瀏覽器中執行：
  • 關閉正在執行應用程式的瀏覽器或瀏覽器索引標籤。
  • 選取瀏覽器上的「上一頁」按鈕。
  • 以 Self 的 LaunchTarget 執行 Launch 函數。
• 如果應用程式是在 Power Apps Mobile (iOS 或 Android) 上執行：
  • 輕掃即可切換至行動版 Power Apps 中的不同應用程式。
  • 在 Android 裝置上選取返回鍵。
  • 執行 Launch 函數以啟動另一個畫布應用程式。

確認對話方塊的實際外觀可能會因裝置與 Power Apps 版本的不同而有所不同。

確認對話方塊未出現在 Power Apps Studio 中。

ConfirmExitMessage

根據預設，確認對話方塊會顯示一般訊息，例如，以使用者語言表示您可能有未儲存的變更。

使用 ConfirmExitMessage，在確認對話方塊中提供自訂訊息。 如果此屬性為空白，則會使用預設值。 自訂訊息會視需要在確認對話方塊中被截斷以符合空間，因此請將訊息保持在最多幾行就好。

在瀏覽器中，確認對話方塊可能會顯示來自瀏覽器的一般訊息。

注意

應用程式物件還有兩個實驗性屬性，OnMessage 和 BackEnabled。 這些屬性最終會從應用程式物件中移除。 建議您不要在生產環境中使用這些屬性。

範例

1. 建立包含兩個表單控制項，AccountForm 和 ContactForm 的應用程式。

2. 將應用程式物件的 ConfirmExit 屬性設為此運算式：

   AccountForm.Unsaved Or ContactForm.Unsaved
   

   如果使用者變更其中一個表單的資料，然後嘗試關閉應用程式但未儲存這些變更的話，就會顯示此對話方塊。

   

3. 將應用程式物件的 ConfirmExitMessage 屬性設為此公式：

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

   如果使用者變更帳戶表單的資料，然後嘗試關閉應用程式但未儲存這些變更的話，就會顯示此對話方塊。

   

設定 Application Insights 的檢測金鑰

若要將系統產生的應用程式記錄匯出到 Application Insights，您需要為畫布應用程式設定偵測金鑰。

1. 在 Power Apps Studio 中開啟您的應用程式以進行編輯。
2. 在左側導覽樹狀結構檢視中選取 App 物件。
3. 在屬性窗格中輸入偵測金鑰。

如果資料未傳送到 App 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 中的 Users 資料表進行這些呼叫。 包含未使用的公式定義不會造成任何損失。

命名公式的一些限制：

• 它們無法在應用程式中使用行為函數，不然可能造成副作用。
• 他們無法建立循環參考。 不允許在同一個應用程式中使用 a = b; 和 b = a;。

使用者定義的函式

重要

• 使用者定義的函數是實驗性。
• 實驗性功能並非供生產使用，也可能不完整。 這些功能是在正式發行前先行推出，讓您能夠搶先體驗並提供意見反應。 其他資訊：了解畫布應用程式中的實驗性、預覽及已淘汰功能
• 只有在使用者定義函數實驗性功能已於設定 > 即將推出的功能 > 實驗性中開啟 (預設為關閉狀態) 時，才能使用本文所述的行為。
• 您的意見反應對我們很有價值。 在 Power Apps 實驗性功能社群論壇中告訴我們您的想法。

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 = Formula;

• FunctionName – 必要。 使用者定義函數的名稱。
• ParameterName(s) – 選用。 函數參數的名稱。
• ParameterType(s) – 選用。 類型的名稱，可以是内建資料類型名稱、資料來源名稱，也可以是透過 Type 函數定義的類型。
• ReturnType – 必要。 函數傳回值的類型。
• Formula – 必要。 根據參數計算函數值的公式。

必須鍵入使用者定義函數的每個參數和輸出。 在此範例中，SelectedGenre: 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 ) 來檢查 Savings 中是否有 12，如果有，則將其借記為 12 並將 12 加到 Spent 變數中。 此函數沒有傳回值，因此其傳回類型為 Void。

行為使用者定義函數的語法如下：

FunctionName( [ ParameterName1: ParameterType1 [ , ParameterName2: ParameterType2 ... ] ] ) : ReturnType = { Formula1 [ ; Formula2 ... ] };

• FunctionName – 必要。 使用者定義函數的名稱。
• ParameterName(s) – 選用。 函數參數的名稱。
• ParameterType(s) – 選用。 類型的名稱，可以是内建資料類型名稱、資料來源名稱，也可以是透過 Type 函數定義的類型。
• ReturnType – 必要。 函數傳回值的類型。 如果函數沒有傳回值，請使用 Void。
• Formula(s) – 必要。 根據參數計算函數值的公式。

與所有 Power Fx 公式一樣，發生錯誤時不會結束執行。 呼叫 Error 函數之後，If 函數會讓 Savings 和 Spent 無法發生變更。 IfError 函數也可以用來防止在發生錯誤後進一步執行。 即使其傳回 Void，如果有問題，公式仍然可以傳回錯誤。

使用者定義型別

重要

• 使用者定義型別是實驗性功能。
• 實驗性功能並非供生產使用，也可能不完整。 這些功能是在正式發行前先行推出，讓您能夠搶先體驗並提供意見反應。 其他資訊：了解畫布應用程式中的實驗性、預覽及已淘汰功能
• 只有在使用者定義型別實驗性功能已於設定 > 即將推出的功能 > 實驗性中開啟 (預設為關閉狀態) 時，才能使用本文所述的行為。
• 您的意見反應對我們很有價值。 在 Power Apps 實驗性功能社群論壇中告訴我們您的想法。

可以將具名公式與 Type 函數搭配用來建立使用者定義型別。 使用 := 而不使用 = 來定義使用者定義型別，例如 Book := Type( { Title: Text, Author: Text } )。 如需詳細資訊和範例，請參閱 Type 函數。

OnError 屬性

使用 OnError 以在應用程式中的任何位置發生錯誤時採取動作。 這會讓您有機會在向使用者顯示錯誤橫幅之前，全域攔截該橫幅。 它還可以用於使用 Trace 函數記錄錯誤或寫入資料庫或 web 服務。

在畫布應用程式中，檢查每個公式評估的結果是否有錯誤。 如果發生錯誤，則使用與整個公式包裝在 IfError 函數中時所用相同的 FirstError 和 AllErrors 範圍變數來評估 OnError。

如果 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 處理常式，這在步驟 5 之前沒有影響，但可能會影響報告錯誤的方式：

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

有了這個 OnError 處理常式，從應用程式使用者的角度來看，不會發生任何錯誤。 但此錯誤會新增至監視器的追蹤，並包含 FirstError 的錯誤資訊來源：

如果我們還想在追蹤之外顯示相同的預設錯誤橫幅，我們可以在追蹤呼叫之後使用 Error 函數重新擲回錯誤，就像追蹤不存在：

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

OnStart 屬性

注意

在載入應用程式時，使用 OnStart 屬性會造成效能問題。 我們正在為使用屬性的兩大原因 (快取資料和設定全域變數) 建立替代方案。 我們已建立一個替代方案來定義要顯示的第一個 Navigate 畫面。 根據您的內容，預設可能會停用此屬性。 如果您沒看到但又需要使用此屬性，請檢查應用程式的 [進階] 設定以找到開關來啟用它。 也可以使用畫面的 OnVisible 屬性。 預設情況下，啟用非封鎖 OnStart 規則時，它允許 OnStart 功能與其他應用程式規則同時運作。 因此，如果其他應用程式規則中所參考的變數是在 OnStart 函數中初始化，則這些變數可能尚未完全初始化。 此外，在 Screen.OnVisible 或 App.OnStart 函數完成執行之前，畫面有可能呈現並變為互動式，尤其是在它們需要很長時間才能完成的情況下。

當使用者開始應用程式時，OnStart 屬性即會執行。 此屬性通常是用於執行以下工作：

• 使用 Collect 函式，檢索並緩存資料至集合。
• 使用 Set 函式建立全域變數。

在第一個畫面出現之前，會先計算此公式。 未載入任何畫面，因此您不能使用 UpdateContext 函式來設定內容變數。 不過，您可以使用 Navigate 函式來傳遞內容變數。

變更 OnStart 屬性之後，請將滑鼠懸停在樹狀結構檢視窗格中的應用程式物件上，選取省略符號 (...)，然後選取執行 OnStart 以測試該屬性。 與應用程式第一次載入時不同，現有的集合和變數將會是已經設定好的。 若要從空的集合開始，請使用 ClearCollect 函式，而不是 Collect 函式。

注意

• 在 OnStart 屬性中使用 Navigate 函數已淘汰。 現有的應用程式將繼續運作。 在有限的時間內，您仍可以在應用程式設定中啟用它 (在已淘汰下)。 不過，以這種方式使用 Navigate 可能會造成應用程式載入延遲，因為這會強制系統在顯示第一個畫面之前完成 OnStart 的評估。 請改為使用 StartScreen 屬性來計算顯示的第一個畫面。
• 對於在 2021 年 3 月之前建立的應用程式，如果您已在 2021 年 3 月至今的期間將 Navigate 新增至 OnStart，則 retired 參數為關閉狀態。 當您在 Power Apps Studio 中編輯此類應用程式時，可能會看到錯誤。 開啟 retired 參數以清除此錯誤。

StartScreen 屬性

StartScreen 屬性決定要先顯示的畫面。 其會在應用程式載入時評估一次，並返回要顯示的畫面物件。 此屬性預設為空白，而且最先顯示是是工作室樹狀檢視中的第一個畫面。

StartScreen 是資料流程屬性，不能包含行為函數。 所有資料流程函數都可使用，尤其是使用這些函數和訊號來判斷要先顯示哪個畫面：

• Param 函數可讀取用於啟動應用程式的參數。
• User函數可讀取目前使用者的資訊。
• LookUp、Filter、CountRows、Max 和其他從資料來源讀取的函數。
• 透過連接器呼叫任何 API，但要注意其會快速傳回。
• 訊號，例如連線、羅盤和應用程式。

注意

全域變數和集合 (包括在 OnStart 中建立的變數和集合) 在 StartScreen 中無法使用。 可以使用具名公式，這通常是在整個應用程式中重複使用公式的更好選擇。

如果 StartScreen 傳回錯誤，則 [工作室樹狀結構] 檢視的第一個畫面會顯示為好像 StartScreen 尚未設定一樣。 使用 IfError 函數來擷取任何錯誤，並重定導向至適當的錯誤畫面。

在工作室中變更 StartScreen 後，請將滑鼠懸停在樹狀結構檢視窗格中的應用程式物件上，選取省略符號 (...)，然後選取瀏覽至 StartScreen 以測試該屬性。 畫面會變更，就像應用程式剛載入一樣。

範例

Screen9

表示每當應用程式啟動時，應先顯示 Screen9。

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

檢查使用者是否已設定了 Param「管理員模式」，並使用它來決定是要先顯示 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 會以文字形式傳回。 文字的格式可能會隨著時間的推移而改變，應作為一個整體來對待; 避免擷取單獨的部分。