在 Salesforce Industries…

适用于构建、配置或审查 OmniStudio FlexCard（含数据源绑定、布局、动作与可访问性）的场景。

适用场景

解决思路

1. 按编排顺序先构建上游组件：sf-industry-commoncore-omnistudio-analyze → sf-industry-commoncore-datamapper → sf-industry-commoncore-integration-procedure → sf-industry-commoncore-omniscript → sf-industry-commoncore-flexcard，先做数据层再做展示层。
2. 需求收集阶段向干系人确认：卡片用途、所需数据源、运行的对象上下文、需暴露的动作、最合适的布局（单卡/列表/选项卡/弹出）、以及条件显示规则。
3. 根据用例选择布局类型：Single Card 用于记录摘要，Card List 用于相关记录（绑定数组数据源），Tabbed Card 用于多上下文，Flyout Card 用于按需展开详情。
4. 配置数据源：将 FlexCard 数据源连接到 Integration Procedure，映射 IP 名称与输入参数，并用 {datasource.fieldName} 合并语法把 IP 响应字段映射到卡片元素。
5. 配置输入参数以传递记录上下文（如 {recordId}）给 IP；当多个数据源供给同一卡片时，设置数据源加载顺序。
6. 设计动作按钮：Launch OmniScript（指定 Type + SubType 并传上下文参数）、Navigate（记录 ID 或带合并字段的 URL 模板）、Custom Action（平台事件、LWC 等，映射 payload）。
7. 配置条件可见性：基于数据值显示/隐藏字段，基于数据源结果显示/隐藏整个卡片状态，并在数据源返回空记录时显示空状态提示。
8. 生成 FlexCard 定义 JSON，验证所有数据源引用都解析到已激活的 Integration Procedure，运行 130 分评分标准，核对合并字段语法与 IP 响应结构一致，并检查所有交互元素的可访问性属性。
9. 部署阶段：确保所有上游 Integration Procedure 已部署并激活，部署 OmniUiCard 元数据，在目标 org 中激活 FlexCard，再将其嵌入目标 Lightning 页面、OmniScript 或父 FlexCard。
10. 测试多种数据场景：有数据（字段正确渲染、合并字段解析）、空数据（显示空状态、无破损合并字段）、错误状态（IP 报错或超时时优雅处理）、多记录（列表项数量正确、分页可用）、动作按钮（OmniScript 以正确预填数据启动）、条件字段（可见性规则随数据值正确切换）、移动端（布局适配小视口）。
11. 避免生成反模式：不引用不存在的 IP 数据源、不在样式中硬编码颜色、不遗漏可访问性属性、不过度嵌套子卡片、不忽略空状态、不硬编码记录 ID。
12. 按 130 分评分标准自检（阈值：≥90 可部署，67-89 需复核，<67 阻止部署）：Design & Layout 25 分（布局类型匹配用例、字段分组合理、响应式、间距一致、视觉层级清晰）、Data Binding 20 分（IP 引用有效、合并字段语法正确、输入参数已映射、多源协调）、Actions & Navigation 20 分（按钮可用、OmniScript 参数已映射、导航目标有效、标签具描述性）、Styling 20 分（使用 SLDS token、排版一致、符合卡片模式、兼容暗色模式）、Accessibility 15 分（交互元素有 aria-label、键盘可导航、对比度达标）、Testing 15 分（有数据/空状态/错误状态/多记录/移动端均已验证）、Performance 15 分（数据源调用最小化、子卡片嵌套最多 2 层、隐藏状态懒加载）。
13. 使用 CLI 命令操作：sf data query -q "SELECT Id,Name,DataSourceConfig,PropertySetConfig,IsActive FROM OmniUiCard WHERE IsActive=true" -o <org>；sf project retrieve start -m OmniUiCard:<Name> -o <org>；sf project deploy start -m OmniUiCard:<Name> -o <org>；sf project retrieve start -m OmniUiCard -o <org>；sf project deploy start -m OmniUiCard -m OmniIntegrationProcedure -m OmniScript -o <org>。
14. 注意 OmniUiCard 在 Core 命名空间中没有 Definition 字段：用 DataSourceConfig 存数据源绑定 JSON，用 PropertySetConfig 存卡片布局、状态与字段定义。
15. 按数据源类型选择 dataSource.type：IntegrationProcedures（复数、大写 P，主推模式）、SOQL（少用，优先 IP 抽象）、ApexRemote、REST（经 Named Credential）、Custom（直接传 JSON body）。
16. 按 IP 响应结构映射字段：{Name}、{Account.Name}、{records[0].Name}（单条）或对数组用 Card List 布局迭代。
17. 按上下文变量映射输入参数：{recordId}（当前记录页）、{userId}（运行用户）、{param.customKey}（URL 参数或父卡片）。
18. 处理边界情况：空数据配置明确空状态提示；错误状态显示有意义错误并记录日志；移动端用单列布局、避免横向滚动、在 320px 视口测试；长文本用省略号截断并提供 flyout 或 tooltip；大记录集用带分页的卡片列表、初始加载限制 10-25 条；空字段用条件可见性隐藏而非显示空标签；多数据源刷新率不同时显示“最后更新”指示。
19. 按 FlexCard vs LWC 决策指南选择：标准卡片布局配 IP 数据用 FlexCard（声明式、合并字段绑定、可嵌入子卡片）；需要自定义行为、动画、复杂状态时用 LWC。
20. 以编程方式创建 FlexCard 时使用 REST API（sf api request rest --method POST --body @file.json），必填字段 Name、VersionNumber、OmniUiCardType（如 Child），设置 DataSourceConfig 与 PropertySetConfig 为 JSON 字符串；sf data create record --values 无法处理 textarea 字段中的 JSON；创建后通过更新 IsActive=true 激活。
21. 注意 FlexCard Designer 使用 OmniFlexCardView 虚拟列表对象（/lightning/o/OmniFlexCardView/home），与存储卡片记录的 OmniUiCard sObject 分离；通过 API 创建的卡片在 Designer 中打开前可能不出现在“Recently Viewed”中。

适用边界 · 注意事项

• 构建 OmniScript 时应# 使用 sf-industry-commoncore-omniscript，而非本技能。
• 创建 Integration Procedure 时应使用 sf-industry-commoncore-integration-procedure，而非本技能。
• 分析依赖关系时应使用 sf-industry-commoncore-omnistudio-analyze，而非本技能。