generating-list-view

何时使用此技能

在需要以下操作时使用此技能：

• 为对象创建列表视图
• 生成按列显示并经过筛选的记录列表
• 配置列表视图的可见性和共享方式
• 排查与列表视图相关的部署错误

规范

Salesforce 列表视图元数据知识

📋 概述

Salesforce 列表视图用于在对象的选项卡上定义经过筛选、按列显示的记录列表。

🎯 用途

• 提供经过整理、针对特定角色或任务的记录子集
• 在团队之间统一常用筛选条件和可见字段

🔧 配置

除非明确要求内联生成，否则列表视图存储在：

• force-app/main/default/objects//listViews/.listView-meta.xml 只有用户提出要求时，才将其包含在对象的元数据文件中：
• fore-app/main/default/objects//.object-meta.xml

关键元素：

• label：在 UI 中显示的易读名称（长度必须少于 40 个字符）
• fullName（fullName）：元数据和文件名中使用的 API 标识符
• filterScope：Everything | Mine | Queue
• filters：字段／操作／值三元组
• booleanFilterLogic：使用 AND／OR 逻辑组合多个筛选条件（例如，"1 AND (2 OR 3)"）
• columns：要显示的字段 API 名称列表，按显示顺序排列

参考：

• listViews 显示在实体的选项卡上
• flexipages 可使用 "filterListCard" 组件引用 listViews

关键决策：可见性策略

选择视图在组织中显示的范围。

在以下情况下选择“对所有用户可见”：

• 此视图对不同配置文件／角色的用户都有用
• 这是一个受治理、共享并通过源代码管理的项目
• 其中的数据适合广泛展示

在以下情况下选择“仅所有者可见／受限”：

• 迭代期间仍处于试验阶段，或仅适用于少数用户
• 用户明确要求将其限制为特定用户、群组或角色
• 尚待完成治理／安全审查

**不确定时：**默认为“对所有用户可见”。

关键决策：列密度

在以下情况下选择精简且信息量高的列：

• 用户需要快速浏览
• 移动端／响应式性能很重要

在以下情况下选择更丰富的列集：

• 桌面端密集型工作流需要更多上下文，且无需打开记录
• 该视图用作工作队列，增加字段可以减少点击次数

**不确定时：**先从 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//.object-meta.xml 中。

路径：

• force-app/main/default/objects//listViews/.listView-meta.xml

生成工作流

步骤 1：获取元数据信息

• 确定目标对象的 API 名称（例如，Object__c）。
• 收集业务需求：用途、受众、字段、筛选条件。
• 验证值和运算符是否与字段类型兼容。

步骤 2：检查现有示例

• 仓库：force-app/main/default/objects//listViews/（除非最终用户另有要求）
• 组织：检索现有列表视图，参考已验证的模式（筛选条件、逻辑、列）。
• 记录通过审核／部署且实现预期用户体验的内容。

步骤 3：创建规范

实施前记录以下内容：

• 名称：fullName 和 Label
• 受众：可见范围（“所有用户”或共享）
• 筛选范围：全部 | 我的 | 队列
• 筛选项：筛选条件、运算符、值；多个筛选项时还需设置 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：部署并在组织中验证

• 部署组件路径或整个对象。
• 在 UI 中打开对象选项卡，并：
  • 确认记录符合筛选条件
  • 确认列正确显示
  • 确认可见范围符合受众设置

常见部署错误

错误	原因	修复
"Invalid field Status"	使用了标签而不是 API 名称，或使用了标准字段的 API 名称而不是其定义名称	使用 Status__c（或正确的 API 名称），标准字段则使用 NAME 而不是 Name
"Invalid filter operator"	运算符不适用于该字段类型	选择与字段类型兼容的运算符（例如，选项列表字段使用 equals）
"Component not found at path"	文件夹或文件名错误	将文件放在 objects//listViews 中，并确保文件名与 fullName 一致
"Malformed booleanFilterLogic"	语法错误或索引不匹配	使用 "1 AND 2" 这种格式，并确保筛选条件的索引顺序匹配

验证清单

• 已填写所有必填字段（fullName、label、filterScope、columns）
• 必要时已对属性值进行 XML 编码
• 自定义字段引用使用 API 名称（例如，Status__c）
• 标准字段引用使用定义名称（例如，NAME）
• 运算符与字段类型匹配；选项列表值有效
• booleanFilterLogic（如有）与筛选条件的顺序和数量匹配
• 文件路径与 fullName/developerName 一致
• 未包含已弃用或仅适用于 Classic 的属性
• 已成功部署，且可见范围符合预期
• 记录、列和筛选行为符合规范