SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场sf-industry-commoncore-flexcard

sf-industry-commoncore-flexcard

前端与建站

查看项目

更新于 10-13 20:08

技能介绍

用途

该技能是一个专注于 Salesforce Industries 的 OmniStudio FlexCard UI 组件的工程师技能。它用于生成可直接部署的 FlexCard 定义，以卡片形式展示一眼可见的信息，并支持声明式数据绑定、Integration Procedure 数据源、条件渲染以及符合 SLDS 规范的样式。生成的每个 FlexCard 都会依据覆盖 7 个类别的 130 分评分标准进行验证。

主要能力

  • FlexCard 编写：设计并构建包含布局、状态和字段映射的 FlexCard 定义。
  • 数据源绑定：配置 Integration Procedure 数据源，并进行正确的字段映射与错误处理。
  • 测试生成：针对多种数据状态（有数据、空数据、错误、多记录）验证卡片。
  • 文档产出：生成可部署文档，包含数据源血缘和动作映射。

内置参考文档包括：最佳实践（布局模式、SLDS、可访问性、性能）与数据绑定指南（IP 数据源、字段映射、条件渲染）。

编排顺序

FlexCard 位于 OmniStudio 栈的展示层，构建依赖上游组件时需先确保其存在：

sf-industry-commoncore-omnistudio-analyze → sf-industry-commoncore-datamapper → sf-industry-commoncore-integration-procedure → sf-industry-commoncore-omniscript → sf-industry-commoncore-flexcard（本技能）

FlexCard 消费来自 Integration Procedure 的数据，并可启动 OmniScript。应先构建数据层，再构建展示层。

关键要点

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

使用方式（五阶段模式）

阶段 1：需求收集。需与相关方澄清：卡片用途（决定布局类型与数据密度）、所需数据源（确定需要的 Integration Procedure）、运行的对象上下文（决定记录级还是列表级展示）、卡片应暴露的动作（决定按钮/链接配置与 OmniScript 集成）、最适合的布局（单卡片、列表、标签页或弹出）、是否存在条件显示规则。

阶段 2：设计与布局。布局类型包括：单卡片（记录摘要）、卡片列表（绑定数组数据源的相关记录）、标签页卡片（多上下文，多个状态以标签页展示）、弹出卡片（从摘要卡片触发的可展开详情面板）。数据源配置中，每个 FlexCard 数据源连接到一个 Integration Procedure（或其他来源类型），并将响应字段映射到展示元素：使用 {datasource.fieldName} 合并语法映射 IP 响应字段；配置输入参数以将记录上下文（如 {recordId}）传给 IP；当多个数据源为同一卡片供数时设置数据源顺序。动作按钮类型包括：启动 OmniScript（配置 OmniScript Type + SubType，传递上下文参数）、导航（跳转到记录或 URL，使用记录 ID 或含合并字段的 URL 模板）、自定义动作（平台事件、LWC 等）。条件可见性：基于数据值显示/隐藏字段；基于数据源结果显示/隐藏整个卡片状态；当数据源返回无记录时显示空状态提示。

阶段 3：生成与验证。生成 FlexCard 定义 JSON；验证所有数据源引用解析到已激活的 Integration Procedure；执行 130 分评分标准；验证合并字段语法与 IP 响应结构匹配；检查所有交互元素的可访问性属性。

阶段 4：部署。确保所有上游 Integration Procedure 已部署并激活；部署 FlexCard 元数据（OmniUiCard）；在目标组织中激活 FlexCard；将 FlexCard 嵌入目标 Lightning 页面、OmniScript 或父 FlexCard。

阶段 5：测试。针对多种数据场景测试：有数据（字段正确渲染、合并字段解析）、空数据（显示空状态、无破损合并字段）、错误状态（IP 返回错误或超时的优雅处理）、多记录（列表渲染数量正确、分页正常）、动作按钮（OmniScript 以正确预填数据启动）、条件字段（可见性规则按数据值正确切换）、移动端（布局适配较小视口宽度）。

生成防护规则

应避免的反模式：引用不存在的 IP 数据源（应在绑定前确认 IP 存在且已激活）；样式中的硬编码颜色（应使用 SLDS 设计令牌和 CSS 自定义属性）；缺少可访问性属性（应添加 aria-label、role 和键盘处理）；过度嵌套子卡片（限制为 2 层，尽量扁平化）；忽略空状态（应配置明确的空状态提示）；硬编码记录 ID（应使用合并字段和上下文驱动参数）。

评分标准（130 分）

阈值：✅ 90+（可部署）| ⚠️ 67-89（需审查）| ❌ <67（阻止，需修复）

七个类别及分值：设计与布局 25 分、数据绑定 20 分、动作与导航 20 分、样式 20 分、可访问性 15 分、测试 15 分、性能 15 分。评分低于 67 分将阻止部署。

数据源绑定细节

DataSourceConfig 字段包含数据源绑定 JSON；PropertySetConfig 字段包含卡片布局、状态和字段定义。数据源类型包括：Integration Procedure（IntegrationProcedures，主要模式）、SOQL（直接查询，慎用）、Apex Remote（自定义 Apex 类调用）、REST（通过命名凭据调用外部 API）、Custom（直接传入 JSON 体）。

跨技能集成与依赖

相关技能包括：sf-industry-commoncore-integration-procedure（构建 FlexCard 消费的 IP）、sf-industry-commoncore-omniscript（构建动作按钮启动的 OmniScript）、sf-industry-commoncore-datamapper（构建 IP 底层使用的 DataRaptor/DataMapper）、sf-industry-commoncore-omnistudio-analyze（分析 FlexCard、IP、OmniScript 之间的依赖链）、sf-deploy（部署 FlexCard 元数据及上游依赖）、sf-lwc（构建嵌入 FlexCard 的自定义 LWC 组件）。

依赖要求：需要具有 OmniStudio（Industries Cloud）许可的目标组织，并已通过 sf CLI 认证；数据源需要目标组织中已部署激活的 Integration Procedure；动作需要已部署激活的 OmniScript（如果动作按钮启动 OmniScript）；评分低于 67 分将阻止部署。

通过编程方式创建 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 来激活。

CLI 命令

# Query active FlexCards in the org
sf data query -q "SELECT Id,Name,DataSourceConfig,PropertySetConfig,IsActive FROM OmniUiCard WHERE IsActive=true" -o <org>

# Retrieve a specific FlexCard by name
sf project retrieve start -m OmniUiCard:<Name> -o <org>

# Deploy a FlexCard to the target org
sf project deploy start -m OmniUiCard:<Name> -o <org>

# Retrieve all FlexCards
sf project retrieve start -m OmniUiCard -o <org>

# Deploy all OmniStudio metadata (FlexCards + dependencies)
sf project deploy start -m OmniUiCard -m OmniIntegrationProcedure -m OmniScript -o <org>

限制与边界情况

空数据：配置明确的空状态和用户友好提示，不要显示原始“无数据”或空白卡片。错误状态：显示有意义的错误消息并记录错误用于调试。移动端响应：使用单列布局，避免横向滚动，在 320px 视口宽度下测试。长文本：以省略号截断，并通过弹出或提示提供全文。大数据集：使用带分页的卡片列表，初始加载限制为 10-25 条记录。空字段值：使用条件可见性隐藏空值字段而非显示空标签。混合数据新鲜度：当多个数据源刷新频率不同时，显示“最后更新”指示。

FlexCard 与 LWC 选择：FlexCard 为声明式（拖拽），适合一眼可见的信息展示，数据绑定用 Integration Procedure 合并字段，测试为手动加数据状态验证，定制受限于 OmniStudio 框架，可作为子卡片复用；LWC 为代码方式，适合复杂交互 UI，使用 wire service、Apex、GraphQL，测试为 Jest 单元测试加手动测试，具备完整平台灵活性，可作为子组件导入。

外部参考与许可

外部参考包括 OmniStudio FlexCards Trailhead 学习模块、OmniStudio Developer Guide 技术参考、Salesforce Industries 文档中的 FlexCard 配置指南。许可为 MIT License，Copyright (c) 2026 David Ryan (weytani)。

暂未提供

具体的收费与价格信息、各平台的兼容性范围、以及除上述内容外的更多功能细节，资料中暂未提供。