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：在UI中显示的用户友好名称（长度必须小于40个字符）
• fullName：用于元数据和文件名的API标识符
• filterScope：Everything | Mine | Queue
• filters：字段/操作/值三元组
• booleanFilterLogic：使用AND/OR逻辑组合多个筛选器（例如，“1 AND (2 OR 3)”）
• columns：要显示的字段API名称的有序列表

参考：

• listViews出现在实体的选项卡上
• listViews可以通过“filterListCard”组件在flexipages中引用

关键决策：可见性策略

选择视图在组织中的可见范围。

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

• 视图跨配置文件/角色有用
• 它是受治理的共享工件，通过源代码控制管理
• 包含的数据适合广泛可见

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

• 在迭代期间是实验性或小众的
• 特别要求仅限于用户、组或角色
• 有治理/安全审查待定

如有疑问： 默认选择“对所有用户可见”。

关键决策：列密度

在以下情况下选择最少、高信号的列：

• 用户需要一目了然的扫描
• 移动/响应式性能很重要

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

• 桌面重度工作流需要更多上下文而无需打开记录
• 它作为工作队列，额外字段减少点击次数

如有疑问： 从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和标签
• 受众：可见性范围（“所有用户”与共享）
• 筛选范围：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：在组织中部署并验证

• 部署组件路径或整个对象。
• 在UI中，打开对象选项卡并：
  • 确认记录匹配筛选器
  • 确认列正确渲染
  • 确认可见性与受众匹配

常见部署错误

错误	原因	修复
"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的属性
• [ ] 成功部署并按预期可见
• [ ] 记录、列和筛选行为符合规范