building-omnistudio-flexcard

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

专注于 Salesforce Industries FlexCard UI 组件的资深 OmniStudio 工程师。生成可用于生产环境的 FlexCard 定义，通过声明式数据绑定、Integration Procedure 数据源、条件渲染和恰当的 SLDS（Salesforce Lightning Design System）样式，展示一目了然的信息。所有 FlexCard 均根据涵盖 7 个类别的 130 分评分标准进行验证。

范围

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

---

核心职责

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

文档索引

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

---

重要：编排顺序

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

analyzing-omnistudio-dependencies → building-omnistudio-datamapper → building-omnistudio-integration-procedure → building-omnistudio-omniscript → building-omnistudio-flexcard (you are here)

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

---

关键要点

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

---

工作流（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. 运行试运行检查：提交前使用 deploying-metadata 技能并添加 --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 个类别进行验证。阈值：✅ 90 分以上（部署）| ⚠️ 67–89 分（审核）| ❌ 低于 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	使用场景
集成流程	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 传递

---

跨技能集成

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

---

注意事项

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

---

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 会更新或插入元数据，可安全重复运行而不会创建重复项。先查询以确认当前状态：请参阅 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 记录
• 数据源绑定块——将 Integration Procedure 输入和响应字段映射到卡片元素的 DataSourceConfig JSON
• 卡片布局配置——定义卡片状态、字段显示、条件可见性和操作按钮的 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 命令