Back to Details

generating-list-view

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

When to Use This Skill

何时使用此技能

Use this skill when you need to:
  • Create list views for objects
  • Generate filtered, column-based record listings
  • Configure list view visibility and sharing
  • Troubleshoot deployment errors related to List Views
当你需要以下操作时使用此技能：
  • 为对象创建列表视图
  • 生成基于列的过滤记录列表
  • 配置列表视图的可见性与共享设置
  • 排查与列表视图相关的部署错误

Specification

规范

Salesforce List View Metadata Knowledge

Salesforce List View元数据知识

📋 Overview

📋 概述

Salesforce List Views define filtered, column-based record listings on an object's tab.
Salesforce List View用于在对象标签页上定义基于列的过滤记录列表。

🎯 Purpose

🎯 用途

  • Provide curated, role- or task-specific subsets of records
  • Standardize commonly used filters and visible fields across teams
  • 提供针对特定角色或任务的精选记录子集
  • 在团队间标准化常用的筛选条件和可见字段

🔧 Configuration

🔧 配置

Unless specifically requested to be generated inline, List Views are stored at:
  • force-app/main/default/objects/<ObjectName>/listViews/<fullName>.listView-meta.xml Only if the user requests are they to be included in the object's metadata file:
  • fore-app/main/default/objects/<ObjectName>/<ObjectName>.object-meta.xml
Key elements:
  • label: Human-friendly name shown in UI (must be under 40 characters in length)
  • fullName (fullName): API identifier used in metadata and file name
  • filterScope: Everything | Mine | Queue
  • filters: field/operation/value triples
  • booleanFilterLogic: Combine multiple filters logically with AND/OR (e.g., "1 AND (2 OR 3)")
  • columns: Ordered list of field API names to display
References:
  • listViews appear on the entity's tab
  • listViews can be referenced by flexipages using the "filterListCard" component
除非明确要求内联生成，否则列表视图存储在以下路径：
  • force-app/main/default/objects/<ObjectName>/listViews/<fullName>.listView-meta.xml 仅当用户要求时，才将其包含在对象的元数据文件中：
  • force-app/main/default/objects/<ObjectName>/<ObjectName>.object-meta.xml
关键元素：
  • label：UI中显示的友好名称（长度必须少于40个字符）
  • fullName：元数据和文件名中使用的API标识符
  • filterScope：Everything | Mine | Queue
  • filters：字段/操作/值三元组
  • booleanFilterLogic：使用AND/OR逻辑组合多个筛选条件（例如："1 AND (2 OR 3)")
  • columns：要显示的字段API名称的有序列表
参考信息：
  • listViews显示在实体的标签页上
  • listViews可通过flexipages中的"filterListCard"组件引用

Critical Decision: Visibility Strategy

关键决策：可见性策略

Choose how broadly the view should appear in the org.
Choose "Visible to all users" when:
  • The view is useful across profiles/roles
  • It's a governed, shared artifact to be managed via source control
  • Data contained is appropriate for broad visibility
Choose "Owner-only/Restricted" when:
  • It is experimental or niche during iteration
  • It is specifically requested to be limited to Users, Groups or Roles
  • There are governance/security reviews pending
When in doubt: Default to "Visible to all users".
选择视图在组织中的显示范围。
选择“对所有用户可见”的场景：
  • 该视图对所有配置文件/角色都有用
  • 它是受管控的共享工件，需通过版本控制管理
  • 包含的数据适合广泛可见
选择“仅所有者/受限”的场景：
  • 处于迭代阶段的实验性或小众视图
  • 明确要求限制为特定用户、组或角色
  • 有待进行治理/安全审查
不确定时： 默认选择“对所有用户可见”。

Critical Decision: Columns Density

关键决策：列密度

Choose minimal, high-signal columns when:
  • Users need at-a-glance scanning
  • Mobile/responsive performance matters
Choose richer column sets when:
  • Desktop heavy workflows need more context without opening records
  • It serves as a work queue and extra fields reduce clicks
When in doubt: Start with 4–6 columns that directly support the primary task.
选择精简、高信息密度列的场景：
  • 用户需要快速浏览记录
  • 移动端/响应式性能至关重要
选择丰富列集的场景：
  • 桌面端重度工作流需要更多上下文，无需打开记录
  • 它作为工作队列存在，额外字段可减少点击操作
不确定时： 从直接支持主要任务的4–6列开始。

Critical Rules (Read First)

关键规则（请先阅读）

Rule 1: Custom Field API Names

规则1：自定义字段API名称

For custom fields, use exact API names (e.g., Status__c), not labels.
Wrong:
  • Status (label)
Right:
  • Status__c (API name)
对于自定义字段，请使用精确的API名称（例如：Status__c），而非标签。
错误示例：
  • Status（标签）
正确示例：
  • Status__c（API名称）

Rule 2: Standard Field Names

规则2：标准字段名称

For standard fields on Custom Objects, use already defined names:
Wrong:
  • Name (API Name)
Right:
  • NAME
The standard fields on Custom Objects are:
  • 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
对于自定义对象上的标准字段，请使用已定义的名称：
错误示例：
  • 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

Rule 3: Operations Must Match Field Types

规则3：操作必须匹配字段类型

Picklists require equals/notEqual; date fields require date operators; boolean values are 0 and 1; do not mix text-only operators with non-text fields.
Wrong:
  • operation="contains" on a picklist
  • value=True on a boolean
Right:
  • operation="equals" with a valid picklist value
  • value=1 on a boolean
选择列表需要使用equals/notEqual；日期字段需要使用日期操作符；布尔值为0和1；请勿将仅文本操作符与非文本字段混用。
错误示例：
  • 对选择列表使用operation="contains"
  • 对布尔值使用value=True
正确示例：
  • 对有效的选择列表值使用operation="equals"
  • 对布尔值使用value=1

Rule 4: Name and Path Alignment

规则4：名称与路径对齐

File name, fullName (also sometimes referred to as DeveloperName), and uniqueness must align.
Wrong:
  • File: My_List.listView-meta.xml
  • fullName: MyList
Right:
  • File: MyList.listView-meta.xml
  • fullName: MyList
文件名、fullName（有时也称为DeveloperName）必须保持一致且唯一。
错误示例：
  • 文件：My_List.listView-meta.xml
  • fullName: MyList
正确示例：
  • 文件：MyList.listView-meta.xml
  • fullName: MyList

Rule 5: Folder Placement

规则5：文件夹放置

Place files under the object's listViews directory or deployments will fail to resolve components. Only if a user requests it, may the listView may be included inline in force-app/main/default/objects/<ObjectName>/<ObjectName>.object-meta.xml
Path:
  • force-app/main/default/objects/<ObjectName>/listViews/<fullName>.listView-meta.xml
将文件放在对象的listViews目录下，否则部署将无法解析组件。仅当用户要求时，才可将listView内联包含在force-app/main/default/objects/<ObjectName>/<ObjectName>.object-meta.xml中
路径：
  • force-app/main/default/objects/<ObjectName>/listViews/<fullName>.listView-meta.xml

Generation Workflow

生成工作流

Step 1: Get Metadata Information

步骤1：获取元数据信息

  • Identify the target object API name (e.g., Object__c).
  • Gather business requirements: purpose, audience, fields, filters.
  • Validate values and operator compatibility with field types.
  • 确定目标对象的API名称（例如：Object__c）。
  • 收集业务需求：用途、受众、字段、筛选条件。
  • 验证值和操作符与字段类型的兼容性。

Step 2: Examine Existing Examples

步骤2：查看现有示例

  • Repo: force-app/main/default/objects/<Object>/listViews/ (unless otherwise required by end user)
  • Org: retrieve existing list views for proven patterns (filters, logic, columns).
  • Note what passed review/deployment and delivered expected UX.
  • 代码库：force-app/main/default/objects/<Object>/listViews/（除非用户另有要求）
  • 组织：检索现有列表视图以获取经过验证的模式（筛选条件、逻辑、列）。
  • 记录哪些内容通过了审核/部署并提供了预期的用户体验。

Step 3: Create Specification

步骤3：创建规范

Document before implementation:
  • Name: fullName and Label
  • Audience: Visibility scope ("all users" vs. shared)
  • Filter scope: Everything | Mine | Queue
  • Filter items: filter, operator, value; plus booleanFilterLogic if multiple
  • Columns: Ordered list of field API names
  • Acceptance criteria: Which records appear, paging behavior, key scenarios
在实施前记录以下内容：
  • 名称：fullName和Label
  • 受众：可见范围（"所有用户" vs 共享）
  • 筛选范围：Everything | Mine | Queue
  • 筛选项：筛选条件、操作符、值；如果有多个筛选条件，需添加booleanFilterLogic
  • 列：字段API名称的有序列表
  • 验收标准：显示哪些记录、分页行为、关键场景

Step 4: Author Metadata File

步骤4：编写元数据文件

Use a Lightning-compatible template and ensure valid XML:
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>
Notes:
  • For "My" views, use filterScope="Mine".
  • Keep columns tight and purposeful.
  • If intended for all users, omit the "sharedTo" section.
使用兼容Lightning的模板并确保XML有效：
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"部分。

Step 5: Validate Locally

步骤5：本地验证

  • Well-formed XML; correct namespace
  • Field names exist on the object; operators and values match field types
  • Path and fullName alignment
  • If multiple filters: set booleanFilterLogic correctly (e.g., "1 AND (2 OR 3)")
  • XML格式良好；命名空间正确
  • 字段名称在对象上存在；操作符和值与字段类型匹配
  • 路径与fullName对齐
  • 如果有多个筛选条件：正确设置booleanFilterLogic（例如："1 AND (2 OR 3)")

Step 6: Deploy and Verify in Org

步骤6：部署并在组织中验证

  • Deploy the component path or the whole object.
  • In the UI, open the object tab and:
    • Confirm records match filters
    • Confirm columns render correctly
    • Confirm visibility matches audience
  • 部署组件路径或整个对象。
  • 在UI中打开对象标签页并：
    • 确认记录与筛选条件匹配
    • 确认列正确渲染
    • 确认可见性与受众匹配

Common Deployment Errors

常见部署错误

ErrorCauseFix
"Invalid field Status"Used label instead of API name, or used API Name instead of defined name for Standard FieldUse Status__c (or correct API name), or NAME instead of Name (for Standard Fields)
"Invalid filter operator"Operator not valid for field typeChoose operation compatible with field type (e.g., equals for picklist)
"Component not found at path"Wrong folder or file namePlace in objects/<Object>/listViews and align file name with fullName
"Malformed booleanFilterLogic"Syntax or index mismatchUse "1 AND 2" style, ensure filters index order matches
错误原因修复方案
"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"格式，确保筛选条件的索引顺序匹配

Verification Checklist

验证清单

  • All required fields populated (fullName, label, filterScope, columns)
  • Property values are XML-encoded where needed
  • Custom Field references use API names (e.g., Status__c)
  • Standard Field references use defined names (e.g., NAME)
  • Operations match field types; picklist values are valid
  • booleanFilterLogic (if used) matches filters ordering and count
  • File path and fullName/developerName are aligned
  • No deprecated or Classic-only properties included
  • Deployed successfully and visible as intended
  • Records, columns, and filtering behave as specified
  • 所有必填字段已填充（fullName、label、filterScope、columns）
  • 必要时对属性值进行XML编码
  • 自定义字段引用使用API名称（例如：Status__c）
  • 标准字段引用使用已定义名称（例如：NAME）
  • 操作符与字段类型匹配；选择列表值有效
  • booleanFilterLogic（如果使用）与筛选条件的顺序和数量匹配
  • 文件路径与fullName/developerName对齐
  • 未包含已弃用或仅Classic版本的属性
  • 部署成功并按预期可见
  • 记录、列和筛选行为符合规范