代碼可讀性

命名慣例

一般命名慣例

本節介紹「駝峰式命名法」和「帕斯卡命名法」命名慣例。 如果您已經熟悉這些術語，則可以跳過。

駝峰式案例

您應該對控制項和變數使用駝峰式命名法。 駝峰式命名法以小寫前綴開頭，刪除物件或變數名稱中的所有空格，並將第一個單字後的每個單字的第一個字母大寫。 例如，文本輸入控制項可能名為 txtUserEmailAddress。

帕斯卡命名法

您應該對資料來源使用帕斯卡命名法。 帕斯卡命名法有時被稱為「大駝峰命名法」。和駝峰式大小寫一樣，它會刪除所有空格並將單詞的第一個字母大寫。 但是，與駝峰式大小寫不同，帕斯卡命名法也將第一個單詞大寫。 例如，PowerApps 中的常見資料來源是 Microsoft Office 365 使用者連接器，在程式碼中名為 Office365Users。

畫面名稱

螢幕名稱應反映螢幕的用途，以便更輕鬆地瀏覽複雜的應用 Power Apps Studio。

不太明顯的是，螢幕閱讀器會大聲朗讀螢幕名稱，這對於有視覺可訪問性需求的用戶來說是必需的。 因此， 您必須使用簡明語言來命名您的畫面，且名稱必須包含空格且不是縮寫。 此外，我們建議您以單詞「螢幕」結束名稱，以便在讀出名稱時理解上下文。

以下列出一些良好的範例：

• [Home_Screen] 或 [Home Screen]
• [Search_Screen] 或 [Search Screen]

這些範例畫面名稱不太容易理解：

• Home
• LoaderScreen
• EmpProfDetails
• Thrive Help

控制項名稱

畫布上的所有控制項名稱都應使用駝峰大小寫。 它們應該以三字元類型描述符開始，後面是控制的目的。 此方法有助於識別控制項的類型，並使生成公式和搜尋變得更加容易。 例如，lblUserName 表示控制項是一個標籤。

下表顯示了常用控制項的縮寫。

控制項名稱	縮寫
徽章	bdg
Button	btn
相機控制項	cam
畫布	can
Card	crd
圖表​​	chr
CheckBox	chk
集合	col
組合方塊	cmb
組件	cmp
容器	con
日期	dte
下拉式清單	drp
表單​​	frm
資源庫	gal
群組	grp
標題	hdr
Html 文字	htm
Icon	ico
影像	img
資訊按鈕	資訊
Label	lbl
連結	lnk
清單方塊	lst
麥克風	麥克風
Microsoft Stream	str
頁面區段形狀	秒
畫筆輸入	畫筆
Power BI 圖標	pbi
進度列	pbar
Rating	rtg
富文本編輯器	rte
形狀（矩形、圓形等）	shp
滑桿	sld
索引標籤清單	tbl
資料表	tbl
文字輸入	txt
計時器	tmr
切換開關	tgl
視訊	vid

控制項及其屬性的詳細清單在控制項參考。

注意

控制項名稱在應用程式中必須是唯一的。 如果在多個螢幕上重複使用控制項，則簡短的螢幕名稱應具有後綴。 例如， galBottomNavMenuHS中的「HS」”表示「首頁畫面」。此方法可以更輕鬆地跨多個畫面在公式中參考控制項。

以下列出一些不好的範例：

• zipcode
• Next

當你一致地命名控制項時，你的應用在導航檢視中更簡潔，你的代碼也更乾淨。

資料來源名稱

當您將資料來源新增至應用程式時，無法在 Power Apps 應用程式中變更名稱。 該名稱繼承自源連接器或從連接派生的數據實體。

以下列出一些範例：

• 從來源連接器繼承的名稱：Office 365 使用者連接器在程式碼中名為　Office365Users。
• 從連線衍生的資料實體：從 SharePoint 連接器傳回名為 Employees 的 Microsoft SharePoint 清單。 因此，代碼中資料來源的名稱是“員工。 相同 Power Apps 應用程式也可以使用相同的 SharePoint 連接器來存取名為 Contractors 的 SharePoint 清單。 在這種情況下，代碼中資料來源的名稱是 Contractors。

關於連接器和連接的詳細資訊，請參閱Power Apps 的畫布應用程式連接器概述。

標準動作連接器

在公開函數（如 LinkedIn）的標準操作連接器中，資料來源名稱及其操作使用 Pascal 大小寫。 例如，LinkedIn 資料來源名為 LinkedIn 並具有一個名為 ListCompanies的操作。

ClearCollect(
    colCompanies,
    LinkedIn.ListCompanies()
)

自訂連接器

用來連接到自訂應用程式介面 (API)，例如您公司建立的服務或業務線 API 的自訂連接器。 它們可以由環境中的任何製作者建立。 我們建議資料來源名稱及其作業採用 Pascal 大小寫。 請注意，自訂連接器名稱及其在 PowerApps 的顯示方式可能會有所不同。

請考慮名為 MS Auction Item Bid API 的自訂連接器範例。

但是，當您從此連接器建立連接並將其作為資料來源新增至 PowerApps 應用程式時，它會顯示為 AuctionItemBidAPI。

若要找出原因，您可以在 OpenAPI 檔案中尋找包含文字 Auction Item Bid API 的標題屬性。

"info": {
    "version": "v1",
    "title": "Auction Item Bid API"
},

Power Apps 會移除此屬性值中的所有空格，並將其用作資料來源的名稱。

提示

我們建議您將此屬性的值更改為 Pascal 大小寫的名稱，例如， AuctionItemBidAPI 並將其用作自訂連接的名稱。 這樣，就不會有混淆。 在匯入 OpenAPI 檔案以建立自訂連接器之前變更此值。

注意

如果使用從空白建立選項而不是匯入現有 OpenAPI 檔，PowerApps 則會提示您輸入自訂連接器名稱。 該名稱將用作自訂連接器的名稱以及 OpenAPI 檔案內的標題屬性的值。 請務必使用帕斯卡命名法的名稱，例如 AuctionItemBidAPI 以保持一致和簡單。

Excel 數據表

PowerApps 使用 Microsoft Excel 中的資料表連線到 Excel 工作表中的資料。 將 Excel 文件建立為資料來源時，請記住以下幾點：

• 為數據表提供描述性名稱。 當你編寫代碼以連接到它時，該名稱位於 Power Apps 應用中。
• 每個工作表使用一個數據表。
• 為資料表和工作表指定相同的名稱。
• 在數據表中使用描述性列名。
• 使用帕斯卡命名法。 數據表名稱的每個單詞都應以大寫字母開頭，例如 EmployeeLeaveRequests。

變數名稱

畫布應用程式中變數的命名約定對於保持 Power Apps 專案的可讀性、一致性和清晰度非常重要。 雖然沒有強制執行嚴格的標準，但在畫布應用程式中採用一致的命名規範可以讓您和其他共同作業者更容易理解、使用和管理變數。

• 使用駝峰大小寫，其中除第一個單詞外，每個單詞的第一個字母都大寫。
• 選擇有意義的描述性名稱，清楚地描述變數的用途或內容。 避免使用過於通用的名稱，如 temp 或 var1。 請改用描述性名稱，如 userEmail 或 totalAmount。
• 請考慮使用前綴或後綴來指示變數的類型。 例如：
  • 文字/字串變數的 strUserName
  • numTotalAmount 對於數值變數
  • boolIsEnabled 對於布爾變數
  • locVarName 對於局部變數/上下文變數
  • 全域變數的 gblVarLoginUser
• 決定變數應該以單數形式還是複數形式命名，並堅持該約定。 例如，始終如一地使用 userCount 或 users。
• 避免使用可能與 Power Apps 函式或關鍵字衝突的保留字或名稱。 檢查 Power Apps 文件以取得保留字清單。
• 請考慮使用前綴來提供有關變數用法或範圍的上下文。 例如:
  • 表單變數的 frm
  • 集合的 col
  • var 對於通用變數
• 避免特殊字元。 保留名稱字母數字並避免特殊字元或空格。 堅持使用字母和數字。

Power Apps 允許內容變數和全域變數共用相同的名稱。 這可能會導致混亂，因為您的公式預設使用內容變數，除非使用消歧義運算子。

通過遵循以下約定來避免這種情況：

• 在上下文變數前面加上 loc前綴。
• 在全域變數前面加上 gbl。
• 前綴後面的名稱應指示變數的意圖/用途。 如果每個單詞的第一個字母大寫，則可以使用多個單詞，並且不必由任何特殊字元（如空格或下劃線）分隔。
• 使用駝峰式命名法。 以小寫字母的前綴開始變數名稱，然後將名稱中每個單詞的首字母大寫。

這些範例遵循標準和約定：

• 全域變數：gblFocusedBorderColor

• 內容變數：locSuccessMessage

• 範圍變數：scpRadius

這些範例不符合標準，且更難理解：

• dSub
• rstFlds
• hideNxtBtn
• ttlOppCt
• cFV
• cQId

避免使用簡短而晦澀的變數名稱，例如 EID。 Use EmployeeId 反而。

當應用程式中有許多變數時，您只需在編輯欄中輸入前綴即可查看可用變數的清單。 如果按照這些準則命名變數，則可以在開發應用時在公式欄中輕鬆找到它們。 最終，這種方法可以加快應用開發速度。

集合物件名稱

• 描述集合的內容。 考慮集合包含什麼和/或如何使用它，然後相應地命名它。
• 集合應以 col 為前綴。
• 前綴後面的名稱應指示集合的意圖或用途。 如果每個單字的第一個字母大寫，則可以使用多個單詞，並且不必用空格或底線分隔。
• 使用駝峰式命名法。 集合名稱以小寫 col 前綴開頭，然後將名稱中每個單字的第一個字母大寫。

這些範例遵循集合名稱約定：

• colMenuItems
• colThriveApps

這些範例不遵循集合名稱約定：

• orderscoll
• tempCollection

提示

當應用程式中有許多集合時，您只需在編輯欄中鍵入前綴即可查看可用集合的清單。 至於變數，如果您遵循這些準則來命名您的集合，您將能夠在開發應用程式時在資料編輯列中輕鬆找到它們。 最終，這種方法可以加快應用開發速度。

註解和文件

為應用程式編寫程式碼時，請注意新增清晰的註釋。 註釋可以幫助您稍後理解您的程式碼，並使下一個開發人員更輕鬆地處理該專案。

Power Apps 支援兩種註釋樣式，以使您的程式碼更清晰：行註釋，使用雙正斜杠 (//) 表示單行註釋，塊註釋，使用 /* 和 */ 表示多行註釋。

行註解

在 Power Apps 中的任何程式碼行中加入雙正斜線 (//)，使該行的其餘部分成為註解。

使用行註解來解釋下一行程式碼的作用。 您也可以使用它們暫時停用一行程式碼以進行測試。

以下是行註解的範例。

// ClearCollect function populates the Expenses2 collection with sample data
ClearCollect(
    Expenses2,
    // Entry 1: Client hosted meet and greet
    {
        Title: "Client hosted meet and greet:",
        ID: "4"
        // additional properties  
    }
)

區塊註解

/* 和 */ 之間的文字是區塊註解。 區塊註解可以覆寫多行，而行註解則只能覆寫一行。

使用區塊註釋進行更長的解釋，例如記錄程式碼模組標題。 您也可以使用它們在測試或偵錯期間暫時停用幾行程式碼。

為了更好地組織程式碼，請在使用「格式化文字」功能後新增註解。 如果您的註釋位於程式碼區塊之前，這會有所幫助。

/*
    Patch Operation to Insert Data:
    - Inserts a new employee record into the 'Employee' entity.
    - Adds corresponding department details to the 'Department' entity.
    Note: Ensure that foreign key relationships and dependencies are maintained for data integrity.
*/
Patch(
    Employee,
    Defaults(Employee),
    {
        FirstName: "John",
        LastName: "Doe",
        Position: "Software Developer"
    }
)

格式化文字功能遵循以下註解規則：

1. 如果屬性以區塊註解開頭，則會向其中新增下一行程式碼。
2. 如果屬性以行註解開頭，則不會新增下一行程式碼。 否則，代碼將被註釋掉。
3. 屬性中其他位置的行註解和區塊註解將會加入上一行程式碼。

不必擔心新增太多或太長的評論。 Power Apps 在建立用戶端應用程式套件時會刪除所有註釋，因此註釋不會影響套件大小或減慢應用程式的下載或載入時間。

帶有註釋的現代應用程式設計器

在 Power Apps 中，最好同時使用 Power Apps Studio 和 Modern 應用程式設計工具中的評論功能。

若要在 Power Apps Studio 中新增註釋，請使用下列方法：

1. 在樹狀檢視中，對任何項目的省略號 (「...」) 右鍵點擊。
2. 在畫布區域中的元件上按下滑鼠右鍵。
3. 選擇位於螢幕右上角命令列上的「註釋」按鈕。

當您在評論中提及同事時，請使用「@」符號後跟其名稱。 這會向您標記的人傳送一封通知電子郵件。 如果被標記的使用者無法存取該應用程式，Power Apps 會提示您與他們分享應用程式。

縮進和格式化

在 Power Apps 中，縮排和格式有助於保持應用程式清晰有序。 遵循最佳做法可以使您的公式和控制項更易於閱讀。

資料編輯列

縮排

Power Apps 不會強制執行嚴格的縮進，但您可以使用空格分隔公式的不同部分。 多次按下空白鍵來建立縮排。

換行符

將長公式分成多行，使其更易於閱讀。 按 Enter 鍵在資料編輯列中新增換行符。

使用文字格式命令

資料編輯列中的「格式化文字」指令會為您的 Power Apps 程式碼新增縮排、間距和換行符。 使用「格式化文字」命令可以在畫布應用程式中保持一致的編碼樣式並有助於防止錯誤。

下一步

代碼最佳化