platform-list-view-generate

何時使用此技能

當您需要以下情況時，請使用此技能：

• 為物件建立清單檢視
• 產生篩選、欄位式的記錄清單
• 設定清單檢視的可見性與共用
• 疑難排解與清單檢視相關的部署錯誤

規格

Salesforce 清單檢視中繼資料知識

概述

Salesforce 清單檢視定義了物件頁籤上篩選、欄位式的記錄清單。

目的

• 提供精選、依角色或任務特定的記錄子集
• 在團隊間標準化常用的篩選條件與可見欄位

設定

除非特別要求內嵌產生，否則清單檢視儲存於：

• force-app/main/default/objects/<ObjectName>/listViews/<fullName>.listView-meta.xml
  僅當使用者要求時，才將其包含在物件的中繼資料檔案中：
• force-app/main/default/objects/<ObjectName>/<ObjectName>.object-meta.xml

關鍵元素：

• label：使用者介面中顯示的易讀名稱（長度必須小於 40 個字元）
• fullName：用於中繼資料與檔案名稱的 API 識別碼
• filterScope：Everything | Mine | Queue
• filters：欄位/運算子/值的三元組
• booleanFilterLogic：使用 AND/OR 邏輯組合多個篩選條件（例如 "1 AND (2 OR 3)"）
• columns：要顯示的欄位 API 名稱的有序清單

參考：

• listViews 出現在實體的頁籤上
• listViews 可被 flexipages 使用 "filterListCard" 元件引用

關鍵決策：可見性策略

選擇檢視在組織中出現的範圍。

在以下情況選擇「對所有使用者可見」：

• 檢視對多個設定檔/角色有用
• 這是一個受治理、共用的成品，需透過原始碼控制管理
• 包含的資料適合廣泛可見

在以下情況選擇「僅限擁有者/限制」：

• 在迭代期間是實驗性或特定用途
• 明確要求限制給使用者、群組或角色
• 有治理/安全審查待進行

不確定時： 預設為「對所有使用者可見」。

關鍵決策：欄位密度

在以下情況選擇最少、高訊號的欄位：

• 使用者需要快速掃視
• 行動裝置/響應式效能重要

在以下情況選擇較豐富的欄位集：

• 桌面重度工作流程需要更多上下文而不需開啟記錄
• 作為工作佇列，額外欄位可減少點擊次數

不確定時： 從 4–6 個直接支援主要任務的欄位開始。

關鍵規則（請先閱讀）

規則 1：自訂欄位 API 名稱

對於自訂欄位，請使用確切的 API 名稱（例如 Status__c），而非標籤。

錯誤：

• Status（標籤）

正確：

• Status__c（API 名稱）

規則 2：標準欄位名稱

對於自訂物件上的標準欄位，請使用已定義的名稱：

錯誤：

• Name（API 名稱）

正確：

• NAME

自訂物件上的標準欄位為：

• NAME
• RECORDTYPE
• OWNER.ALIAS
• OWNER.FIRST_NAME
• OWNER.LAST_NAME
• CREATEDBY_USER.ALIAS
• CREATEDBY_USER
• CREATED_DATE
• UPDATEDBY_USER.ALIAS
• UPDATEDBY_USER
• LAST_UPDATE
• LAST_ACTIVITY

規則 3：運算子必須符合欄位類型

選擇清單需要 equals/notEqual；日期欄位需要日期運算子；布林值為 0 和 1；不要將僅限文字的運算子用於非文字欄位。

錯誤：

• 在選擇清單上使用 operation="contains"
• 在布林值上使用 value=True

正確：

• 在選擇清單上使用 operation="equals" 搭配有效的選擇清單值
• 在布林值上使用 value=1

規則 4：名稱與路徑對齊

檔案名稱、fullName（有時也稱為 DeveloperName）和唯一性必須對齊。

錯誤：

• 檔案：My_List.listView-meta.xml
• fullName：MyList

正確：

• 檔案：MyList.listView-meta.xml
• fullName：MyList

規則 5：資料夾位置

將檔案放在物件的 listViews 目錄下，否則部署將無法解析元件。僅當使用者要求時，listView 才能內嵌在 force-app/main/default/objects/<ObjectName>/<ObjectName>.object-meta.xml 中。

路徑：

• force-app/main/default/objects/<ObjectName>/listViews/<fullName>.listView-meta.xml

產生工作流程

步驟 1：取得中繼資料資訊

• 識別目標物件的 API 名稱（例如 Object__c）。
• 收集業務需求：目的、對象、欄位、篩選條件。
• 驗證值與運算子是否與欄位類型相容。

步驟 2：檢查現有範例

• 儲存庫：force-app/main/default/objects/<Object>/listViews/（除非使用者另有要求）
• 組織：擷取現有的清單檢視以取得經過驗證的模式（篩選條件、邏輯、欄位）。
• 注意哪些通過了審查/部署並提供了預期的使用者體驗。

步驟 3：建立規格

在實作前記錄：

• 名稱：fullName 和 Label
• 對象：可見性範圍（"所有使用者" vs. 共用）
• 篩選範圍：Everything | Mine | Queue
• 篩選項目：篩選條件、運算子、值；若有多個則加上 booleanFilterLogic
• 欄位：欄位 API 名稱的有序清單
• 驗收標準：哪些記錄出現、分頁行為、關鍵情境

步驟 4：撰寫中繼資料檔案

使用 Lightning 相容的範本並確保 XML 有效：

<?xml version="1.0" encoding="UTF-8"?>
<ListView xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>OpenMine</fullName>
    <label>Open - My Records</label>
    <filterScope>Mine</filterScope>
    <columns>NAME</columns>
    <columns>Status__c</columns>
    <columns>OWNER.ALIAS</columns>
    <columns>LAST_UPDATE</columns>
    <filters>
        <field>Status__c</field>
        <operation>equals</operation>
        <value>Open</value>
    </filters>
    <sharedTo>
        <role>CEO</role>
        <roleAndSubordinatesInternal>COO</roleAndSubordinatesInternal>
    </sharedTo>
</ListView>

注意：

• 對於「我的」檢視，請使用 filterScope="Mine"。
• 保持欄位精簡且有目的。
• 如果打算給所有使用者，請省略 "sharedTo" 區段。

步驟 5：在本機驗證

• XML 格式正確；命名空間正確
• 欄位名稱存在於物件上；運算子與值符合欄位類型
• 路徑與 fullName 對齊
• 若有多個篩選條件：正確設定 booleanFilterLogic（例如 "1 AND (2 OR 3)"）

步驟 6：部署並在組織中驗證

• 部署元件路徑或整個物件。
• 在使用者介面中，開啟物件頁籤並：
  • 確認記錄符合篩選條件
  • 確認欄位正確呈現
  • 確認可見性符合對象

常見部署錯誤

錯誤	原因	修正
"Invalid field Status"	使用了標籤而非 API 名稱，或對標準欄位使用了 API 名稱而非定義名稱	使用 Status__c（或正確的 API 名稱），或對標準欄位使用 NAME 而非 Name
"Invalid filter operator"	運算子對欄位類型無效	選擇與欄位類型相容的運算子（例如選擇清單使用 equals）
"Component not found at path"	資料夾或檔案名稱錯誤	放置在 objects/<Object>/listViews 並確保檔案名稱與 fullName 對齊
"Malformed booleanFilterLogic"	語法或索引不符	使用 "1 AND 2" 樣式，確保篩選條件索引順序相符

驗證檢查清單

• [ ] 所有必要欄位已填寫（fullName、label、filterScope、columns）
• [ ] 屬性值在需要時已進行 XML 編碼
• [ ] 自訂欄位引用使用 API 名稱（例如 Status__c）
• [ ] 標準欄位引用使用定義名稱（例如 NAME）
• [ ] 運算子符合欄位類型；選擇清單值有效
• [ ] booleanFilterLogic（若使用）符合篩選條件的順序與數量
• [ ] 檔案路徑與 fullName/developerName 對齊
• [ ] 未包含已棄用或僅限 Classic 的屬性
• [ ] 成功部署並如預期顯示
• [ ] 記錄、欄位與篩選行為符合規格