omnistudio-flexcard-generate

omnistudio-flexcard-generate：OmniStudio FlexCard 创建与验证

专精于 Salesforce Industries FlexCard UI 组件的 OmniStudio 工程师。生成可用于生产环境的 FlexCard 定义，以醒目直观的方式展示信息，并使用声明式数据绑定、Integration Procedure 数据源、条件渲染和恰当的 SLDS（Salesforce Lightning Design System）样式。所有 FlexCard 均依据涵盖 7 个类别、总分 130 分的评分标准进行验证。

范围

• 范围内：创建和验证 OmniStudio FlexCard 定义（OmniUiCard）；配置 Integration Procedure 数据源；设计卡片布局、状态和操作按钮；依据 130 分评分标准评分；部署和激活
• 范围外：构建 OmniScript（使用 omnistudio-omniscript-generate）、创建 Integration Procedure（使用 omnistudio-integration-procedure-generate）、映射完整依赖树（使用 omnistudio-dependencies-analyze）、将元数据部署到组织（使用 platform-metadata-deploy）

---

核心职责

1. FlexCard 编写：设计并构建 FlexCard 定义，确保布局、状态和字段映射正确
2. 数据源绑定：配置 Integration Procedure 数据源，确保字段映射正确并妥善处理错误
3. 测试生成：针对多种数据状态（已填充、空、错误、多记录）验证卡片
4. 文档编写：生成可用于部署的文档，说明数据源沿袭关系和操作映射

文档索引

需求	文档	描述
最佳实践	references/best-practices.md	布局模式、SLDS、无障碍性、性能
数据绑定	references/data-binding-guide.md	IP 数据源、字段映射、条件渲染

---

重要：编排顺序

FlexCard 位于 OmniStudio 技术栈的展示层。构建依赖上游组件的 FlexCard 之前，请确保这些组件已存在。

omnistudio-dependencies-analyze → omnistudio-datamapper-generate → omnistudio-integration-procedure-generate → omnistudio-omniscript-generate → omnistudio-flexcard-generate (you are here)

FlexCard 从 Integration Procedure 获取数据，也可以启动 OmniScript。请先构建数据层，再构建展示层。

---

关键要点

要点	详情
配置字段	OmniUiCard 使用 DataSourceConfig 绑定数据源，并使用 PropertySetConfig 配置卡片布局、状态和操作。在 Core 命名空间中，OmniUiCard 没有 Definition 字段。
数据源绑定	实时数据源通过 Integration Procedure 绑定；FlexCard 获取数据之前，IP 必须处于激活状态并已部署
嵌入子卡片	FlexCard 可以嵌入其他 FlexCard 作为子卡片，从而创建使用共享或独立数据源的复合布局
启动 OmniScript	FlexCard 可以通过操作按钮启动 OmniScript，并将卡片数据源中的上下文数据传递到 OmniScript 的输入中
设计器虚拟对象	FlexCard Designer 使用 OmniFlexCardView 作为虚拟列表对象（/lightning/o/OmniFlexCardView/home），与存储卡片记录的 OmniUiCard sObject 分开。通过 API 创建的卡片在设计器中打开之前，可能不会显示在“最近查看”中。

---

工作流（5 阶段模式）

阶段 1：需求收集

开始构建之前，请与相关方确认以下事项：

问题	重要性
此卡片的用途是什么？	决定布局类型和数据密度
需要哪些数据源？	确定所需的 Integration Procedure
它在哪种对象上下文中运行？	决定按记录级还是列表级显示
此卡片应提供哪些操作？	决定按钮／链接配置和 OmniScript 集成方式
哪种布局最适合此用例？	单卡片、列表、选项卡式布局或弹出面板
是否有条件显示规则？	根据数据值显示／隐藏字段或区域

阶段 2：设计与布局

设计前请阅读 references/best-practices.md，了解布局模式、SLDS 合规性、无障碍要求和性能指南。

卡片布局选项

布局类型	使用场景	说明
单卡片	记录摘要	显示单条记录字段的一张卡片
卡片列表	相关记录	绑定到数组数据源的重复卡片
选项卡式卡片	多种上下文	在一张卡片内以选项卡形式显示多个状态
弹出卡片	按需查看详情	从摘要卡片触发展开的详情面板

数据源配置

每个 FlexCard 数据源都连接到一个 Integration Procedure（或其他源类型），并将响应字段映射到显示元素。

FlexCard → Data Source (type: IntegrationProcedure)
         → IP Name + Input Mapping
         → Response Field Mapping → Card Elements

• 使用 {datasource.fieldName} 合并语法，将 IP 响应字段映射到卡片显示元素
• 配置输入参数，将记录上下文（例如 {recordId}）传递给 IP
• 多个数据源为同一张卡片提供数据时，设置数据源顺序

操作按钮设计

操作类型	用途	配置
启动 OmniScript	开始引导流程	OmniScript Type + SubType，并传递上下文参数
导航	前往记录或 URL	记录 ID 或带合并字段的 URL 模板
自定义操作	平台事件、LWC 等	带有负载映射的自定义操作处理程序

条件可见性

• 使用可见性条件，根据数据值显示／隐藏字段
• 根据数据源结果显示／隐藏整个卡片状态
• 数据源未返回记录时显示空状态提示

阶段 3：生成与验证

生成前请阅读 references/data-binding-guide.md，了解合并字段语法、数据源类型和多源协调方式。 运行 130 分验证时，请阅读 references/scoring-rubric.md，了解完整的逐项评分细则。

1. 生成 FlexCard 定义 JSON
2. 验证所有数据源引用均解析到处于活动状态的 Integration Procedure
3. 运行 130 分评分标准（见下文的评分部分）
4. 确认合并字段语法与 IP 响应结构匹配
5. 检查所有交互元素上的无障碍属性

阶段 4：部署

1. 确保所有上游 Integration Procedure 均已部署并处于活动状态
2. 执行试运行检查：提交前使用 platform-metadata-deploy 技能并添加 --dry-run
3. 部署 FlexCard 元数据（OmniUiCard）——可安全地重复运行 sf project deploy start；该命令会更新现有记录
4. 在目标 org 中激活 FlexCard
5. 将 FlexCard 嵌入目标 Lightning 页面、OmniScript 或父级 FlexCard
6. 如果部署失败：检查错误输出以确定具体原因——常见问题包括：上游 IP 尚未部署（Cannot find OmniIntegrationProcedure）、缺少命名空间前缀（Entity not found），或 FlexCard 仍处于 Draft 状态（检索前先激活）

第 5 阶段：测试

针对多种数据场景测试每张 FlexCard：

场景	验证内容
数据已填充	所有字段均正确呈现，合并字段已解析
数据为空	显示空状态消息，且没有损坏的合并字段
错误状态	IP 返回错误或超时时能妥善处理
多条记录	卡片列表呈现正确的项目数，分页正常工作
操作按钮	OmniScript 使用正确的预填充数据启动
条件字段	可见性规则根据数据值正确切换
移动设备	卡片布局适应较窄的视口宽度

---

生成防护措施

生成 FlexCard 定义时，请避免以下模式：

反模式	错误原因	正确做法
引用不存在的 IP 数据源	卡片在运行时无法加载数据	绑定前确认 IP 存在且处于活动状态
在样式中硬编码颜色	破坏 SLDS 主题和深色模式	使用 SLDS 设计令牌和 CSS 自定义属性
缺少无障碍属性	不符合 WCAG 要求	添加 aria-label、role 和键盘事件处理程序
过度嵌套子卡片	深层嵌套会降低性能	嵌套层级限制为 2 层；尽可能扁平化
忽略空状态	数据源未返回记录时 UI 会出错	配置明确的空状态消息
硬编码记录 ID	卡片无法跨环境使用	使用合并字段和由上下文驱动的参数

---

评分标准（130 分）

所有 FlexCard 均按 7 个类别进行验证。阈值：[PASS] 90+（部署）| [VERIFY] 67-89（审核）| [BLOCK] <67（阻止——需要修复）

类别	分数	标准
设计与布局	25	布局类型恰当、字段分组合理、响应式设计、间距一致、视觉层次清晰
数据绑定	20	IP 引用正确、合并字段语法正确、输入参数映射、多数据源协调
操作与导航	20	操作按钮配置正确、OmniScript 启动参数已映射、导航目标有效、操作标签描述清晰
样式	20	使用 SLDS 令牌（无硬编码颜色）、字体排版一致、正确使用卡片/磁贴模式、兼容深色模式
无障碍	15	交互元素包含 aria-label、操作可通过键盘导航、颜色对比度充足、屏幕阅读器友好的字段标签
测试	15	已通过数据已填充、空状态、错误状态、多条记录场景和移动设备视口进行验证
性能	15	数据源调用次数最少、子卡片嵌套受限（最多 2 层）、无冗余 IP 调用、对不可见状态采用延迟加载

阅读 references/scoring-rubric.md，了解全部 7 个类别中各项标准的完整细分。

---

CLI 命令

阅读 scripts/flexcard-commands.sh，查看所有 FlexCard CLI 命令（查询、检索、部署）。将 <org> 替换为你的组织别名，并将 <Name> 替换为 FlexCard API 名称。

---

数据源绑定

FlexCard 数据源配置

OmniUiCard 上的 DataSourceConfig 字段以 JSON 格式包含数据源绑定。PropertySetConfig 字段包含卡片布局、状态和字段定义。

IMPORTANT：Core 命名空间中的 OmniUiCard 没有 Definition 字段。数据源请使用 DataSourceConfig，布局请使用 PropertySetConfig。

阅读 assets/omni-ui-card.json，查看完整的 OmniUiCard 记录模板，其中包含 DataSourceConfig JSON 结构。

数据源类型

类型	dataSource.type	使用场景
Integration Procedure	IntegrationProcedures (复数形式，P 大写)	主要模式；调用 IP 获取实时数据
SOQL	SOQL	直接查询（谨慎使用；优先选择 IP 以实现抽象）
Apex Remote	ApexRemote	调用自定义 Apex 类
REST	REST	通过 Named Credential 调用外部 API
Custom	Custom	自定义数据提供程序（直接传入 JSON 正文）

映射 IP 响应中的字段

使用合并字段语法，将 IP 响应字段映射到卡片显示元素：

IP Response:                    FlexCard Merge Field:
─────────────                   ─────────────────────
{ "Name": "Acme Corp" }   →    {Name}
{ "Account": {            →    {Account.Name}
    "Name": "Acme Corp"
  }
}
{ "records": [             →    {records[0].Name}  (single)
    { "Name": "Acme" }          or iterate with Card List layout
  ]
}

输入参数映射

将托管页面的上下文传递到 IP 数据源：

上下文变量	来源	示例
{recordId}	当前记录页面	传递给 IP，以查询相关数据
{userId}	当前运行用户	根据当前用户筛选数据
{param.customKey}	URL 参数或父卡片	从父 FlexCard 或 URL 传递

---

跨技能集成

技能	与 omnistudio-flexcard-generate 的关系
omnistudio-integration-procedure-generate	构建 FlexCard 使用的 IP 数据源
omnistudio-omniscript-generate	构建 FlexCard 操作按钮启动的 OmniScript
omnistudio-datamapper-generate	构建 IP 在底层使用的 DataRaptor/DataMapper
omnistudio-dependencies-analyze	分析 FlexCard、IP 和 OmniScript 之间的依赖链
platform-metadata-deploy	与上游依赖项一同部署 FlexCard 元数据
experience-lwc-generate	构建嵌入 FlexCard 的自定义 LWC 组件

---

注意事项

场景	处理方式
无数据	配置明确的空状态，并显示对用户友好的消息；不要显示原始的“无数据”或空白卡片
错误状态	IP 数据源失败时显示有意义的错误消息；记录错误以便调试
移动端响应式布局	移动端使用单列布局；避免水平滚动；在 320px 视口宽度下测试
较长文本值	使用省略号截断，并提供浮出面板或工具提示以显示完整文本
大型记录集	使用带分页的卡片列表；将初始加载数量限制为 10-25 条记录
字段值为 null	使用条件可见性隐藏值为 null 的字段，而不是显示空标签
数据新鲜度不一致	多个数据源的刷新频率不同时，显示“上次更新时间”指示器

---

FlexCard 与 LWC 选择指南

因素	FlexCard	LWC
构建方式	声明式（拖放）	代码（JS、HTML、CSS）
数据绑定	Integration Procedure 合并字段	Wire 服务、Apex、GraphQL
适用场景	一目了然的信息展示	复杂的交互式 UI
测试	手动测试 + 数据状态验证	Jest 单元测试 + 手动测试
自定义能力	受 OmniStudio 框架限制	完整的平台灵活性
复用方式	嵌入为子卡片	导入为子组件
选择时机	使用 IP 数据的标准卡片布局	自定义行为、动画、复杂状态

---

依赖项

必需：目标组织已获得 OmniStudio（Industries Cloud）许可证，并已通过身份验证的 sf CLI 数据源：已在目标组织中部署并处于活动状态的 Integration Procedure 操作：已部署并处于活动状态的 OmniScript（如果操作按钮会启动 OmniScript） 评分：得分低于 67 时阻止部署

幂等性：sf project deploy start 会对元数据执行 upsert，重复运行不会创建重复项。先查询以确认当前状态：请参阅 scripts/flexcard-commands.sh。

命名空间处理：在托管包组织中，元数据类型可能带有前缀（例如，omnistudio__OmniUiCard）。请检查 sfdx-project.json 中的命名空间。带命名空间的部署命令请参阅 scripts/flexcard-commands.sh。

以编程方式创建 FlexCard：使用 REST API（sf api request rest --method POST --body @file.json）。必需字段：Name、VersionNumber、OmniUiCardType（例如，Child）。设置 DataSourceConfig（JSON 字符串）以配置数据源绑定，并设置 PropertySetConfig（JSON 字符串）以配置卡片布局。sf data create record --values 标志无法处理 textarea 字段中的 JSON。创建后，将 IsActive=true 更新为活动状态。

---

预期输出

此技能生成的交付物：

• FlexCard JSON 定义（assets/omni-ui-card.json 模板）——可用于 REST API 创建或元数据部署的 OmniUiCard 记录
• 数据源绑定块——DataSourceConfig JSON，用于将 Integration Procedure 输入和响应字段映射到卡片元素
• 卡片布局配置——PropertySetConfig JSON，用于定义卡片状态、字段显示、条件可见性和操作按钮
• 验证报告——涵盖 7 个类别、总分 130 分的评分，以及部署／审核／阻止阈值结果
• 部署检查清单——确认上游 IP 处于活动状态、FlexCard 已激活，并已嵌入目标 Lightning 页面或父 FlexCard

---

外部参考资料

• OmniStudio FlexCards（Trailhead）——FlexCard 基础知识和引导式设置的官方学习模块
• OmniStudio Developer Guide——FlexCard 元数据、数据源配置和组件属性的技术参考
• Salesforce Industries Documentation——涵盖布局、状态和操作的 FlexCard 配置指南

---

参考文件索引

文件	阅读时机
assets/omni-ui-card.json	阶段 3——生成：包含 DataSourceConfig JSON 结构的 OmniUiCard 记录模板
references/best-practices.md	阶段 2——布局模式、SLDS 合规性、无障碍要求和性能指南
references/data-binding-guide.md	阶段 2-3——数据源类型、合并字段语法、输入参数映射和多数据源协调
references/scoring-rubric.md	阶段 3——全部 7 个评分类别的逐项标准明细（总分 130 分）
scripts/flexcard-commands.sh	阶段 4——用于查询、检索和部署 FlexCard 元数据的所有 CLI 命令

---

交付前检查清单

• 上游 Integration Procedure 已创建并处于活动状态，之后 FlexCard 才能依赖它们
• 已遵循编排顺序（FlexCard 位于流程链的末尾）