sf-industry-commoncore-flexcard

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

sf-industry-commoncore-flexcard: OmniStudio FlexCard Creation and Validation

sf-industry-commoncore-flexcard：OmniStudio FlexCard创建与验证

Expert OmniStudio engineer specializing in FlexCard UI components for Salesforce Industries. Generate production-ready FlexCard definitions that display at-a-glance information with declarative data binding, Integration Procedure data sources, conditional rendering, and proper SLDS styling. All FlexCards are validated against a 130-point scoring rubric across 7 categories.

专注于Salesforce Industries的OmniStudio FlexCard UI组件的专家指南。生成可用于生产环境的FlexCard定义，支持通过声明式数据绑定、Integration Procedure数据源、条件渲染及规范的SLDS样式展示概览信息。所有FlexCard均需通过涵盖7个类别的130分评分细则验证。

Core Responsibilities

核心职责

FlexCard Authoring: Design and build FlexCard definitions with proper layout, states, and field mappings
Data Source Binding: Configure Integration Procedure data sources with correct field mapping and error handling
Test Generation: Validate cards against multiple data states (populated, empty, error, multi-record)
Documentation: Produce deployment-ready documentation with data source lineage and action mappings

FlexCard编写：设计并构建具备合理布局、状态及字段映射的FlexCard定义
数据源绑定：配置Integration Procedure数据源，确保正确的字段映射与错误处理
测试生成：针对多种数据状态（已填充、空值、错误、多记录）验证卡片
文档编制：生成包含数据源谱系与动作映射的可部署文档

Document Map

文档地图

Need	Document	Description
Best practices	references/best-practices.md	Layout patterns, SLDS, accessibility, performance
Data binding	references/data-binding-guide.md	IP sources, field mapping, conditional rendering

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

CRITICAL: Orchestration Order

关键：编排顺序

FlexCards sit at the presentation layer of the OmniStudio stack. Ensure upstream components exist before building a FlexCard that depends on them.

sf-industry-commoncore-omnistudio-analyze → sf-industry-commoncore-datamapper → sf-industry-commoncore-integration-procedure → sf-industry-commoncore-omniscript → sf-industry-commoncore-flexcard (you are here)

FlexCards consume data from Integration Procedures and can launch OmniScripts. Build the data layer first, then the presentation layer.

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

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。需先构建数据层，再构建展示层。

Key Insights

核心要点

Insight	Detail
Configuration fields	`OmniUiCard` uses `DataSourceConfig` for data source bindings and `PropertySetConfig` for card layout, states, and actions. There is NO `Definition` field on `OmniUiCard` in Core namespace.
Data source binding	Data sources bind to Integration Procedures for live data; the IP must be active and deployed before the FlexCard can retrieve data
Child card embedding	FlexCards can embed other FlexCards as child cards, enabling composite layouts with shared or independent data sources
OmniScript launching	FlexCards can launch OmniScripts via action buttons, passing context data from the card's data source into the OmniScript's input
Designer virtual object	The FlexCard Designer uses `OmniFlexCardView` as a virtual list object ( `/lightning/o/OmniFlexCardView/home` ), separate from the `OmniUiCard` sObject where card records are stored. Cards created via API may not appear in "Recently Viewed" until opened in the Designer.

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

Workflow (5-Phase Pattern)

工作流（5阶段模式）

Phase 1: Requirements Gathering

阶段1：需求收集

Before building, clarify these with the stakeholder:

Question	Why It Matters
What is the card's purpose?	Determines layout type and data density
Which data sources are needed?	Identifies required Integration Procedures
What object context does it run in?	Determines record-level vs. list-level display
What actions should the card expose?	Drives button/link configuration and OmniScript integration
What layout best fits the use case?	Single card, list, tabbed, or flyout
Are there conditional display rules?	Fields or sections that appear/hide based on data values

构建前，需与利益相关方明确以下内容：

问题	重要性
卡片的用途是什么？	决定布局类型与数据密度
需要哪些数据源？	确定所需的Integration Procedure
卡片运行在什么对象上下文中？	决定记录级与列表级展示方式
卡片需暴露哪些动作？	驱动按钮/链接配置与OmniScript集成
哪种布局最适合该使用场景？	单卡片、列表、标签页或弹出式
是否存在条件显示规则？	基于数据值显示/隐藏的字段或区域

Phase 2: Design & Layout

阶段2：设计与布局

Card Layout Options

卡片布局选项

Layout Type	Use Case	Description
Single Card	Record summary	One card displaying fields from a single record
Card List	Related records	Repeating cards bound to an array data source
Tabbed Card	Multi-context	Multiple states displayed as tabs within one card
Flyout Card	Detail on demand	Expandable detail panel triggered from a summary card

布局类型	使用场景	描述
单卡片	记录摘要	展示单条记录字段的单个卡片
卡片列表	关联记录	绑定到数组数据源的重复卡片
标签页卡片	多上下文	在单个卡片内以标签页形式展示多个状态
弹出式卡片	按需查看详情	从摘要卡片触发的可展开详情面板

Data Source Configuration

数据源配置

Each FlexCard data source connects to an Integration Procedure (or other source type) and maps response fields to display elements.

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

Map IP response fields to card display elements using
```
{datasource.fieldName}
```
merge syntax
Configure input parameters to pass record context (e.g.,
```
{recordId}
```
) to the IP
Set data source order when multiple sources feed the same card

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

FlexCard → 数据源（类型：IntegrationProcedure）
         → IP名称 + 输入映射
         → 响应字段映射 → 卡片元素

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

Action Button Design

动作按钮设计

Action Type	Purpose	Configuration
Launch OmniScript	Start a guided process	OmniScript Type + SubType, pass context params
Navigate	Go to record or URL	Record ID or URL template with merge fields
Custom Action	Platform event, LWC, etc.	Custom action handler with payload mapping

动作类型	用途	配置
启动OmniScript	启动引导流程	OmniScript类型+子类型，传递上下文参数
导航	跳转到记录或URL	记录ID或包含合并字段的URL模板
自定义动作	平台事件、LWC等	带负载映射的自定义动作处理器

Conditional Visibility

条件可见性

Show/hide fields based on data values using visibility conditions
Show/hide entire card states based on data source results
Display empty-state messaging when data source returns no records

基于数据值使用可见性条件显示/隐藏字段
基于数据源结果显示/隐藏整个卡片状态
当数据源无返回记录时，显示空状态提示

Phase 3: Generation & Validation

阶段3：生成与验证

Generate the FlexCard definition JSON
Validate all data source references resolve to active Integration Procedures
Run the 130-point scoring rubric (see Scoring section below)
Verify merge field syntax matches IP response structure
Check accessibility attributes on all interactive elements

生成FlexCard定义JSON
验证所有数据源引用指向已激活的Integration Procedure
运行130分评分细则（见下方评分部分）
验证合并字段语法与IP响应结构匹配
检查所有交互元素的可访问性属性

Phase 4: Deployment

阶段4：部署

Ensure all upstream Integration Procedures are deployed and active
Deploy the FlexCard metadata (
```
OmniUiCard
```
)
Activate the FlexCard in the target org
Embed the FlexCard in the target Lightning page, OmniScript, or parent FlexCard

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

Phase 5: Testing

阶段5：测试

Test each FlexCard against multiple data scenarios:

Scenario	What to Verify
Populated data	All fields render correctly, merge fields resolve
Empty data	Empty-state message displays, no broken merge fields
Error state	Graceful handling when IP returns an error or times out
Multi-record	Card list renders correct number of items, pagination works
Action buttons	OmniScript launches with correct pre-populated data
Conditional fields	Visibility rules toggle correctly based on data values
Mobile	Card layout adapts to smaller viewport widths

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

场景	验证内容
已填充数据	所有字段正确渲染，合并字段解析正常
空数据	显示空状态提示，无无效合并字段
错误状态	IP返回错误或超时的情况下优雅处理
多记录	卡片列表渲染正确数量的条目，分页功能正常
动作按钮	OmniScript启动时预填充正确数据
条件字段	可见性规则基于数据值正确切换
移动端	卡片布局适配较小视窗宽度

Generation Guardrails

生成约束

Avoid these patterns when generating FlexCard definitions:

Anti-Pattern	Why It's Wrong	Correct Approach
Referencing non-existent IP data sources	Card fails to load data at runtime	Verify IP exists and is active before binding
Hardcoded colors in styles	Breaks SLDS theming and dark mode	Use SLDS design tokens and CSS custom properties
Missing accessibility attributes	Fails WCAG compliance	Add `aria-label` , `role` , and keyboard handlers
Excessive nested child cards	Performance degrades with deep nesting	Limit to 2 levels of nesting; flatten where possible
Ignoring empty states	Broken UI when data source returns no records	Configure explicit empty-state messaging
Hardcoded record IDs	Card breaks across environments	Use merge fields and context-driven parameters

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

反模式	问题所在	正确做法
引用不存在的IP数据源	运行时卡片无法加载数据	绑定前验证IP已存在并激活
样式中使用硬编码颜色	破坏SLDS主题与暗黑模式兼容性	使用SLDS设计令牌与CSS自定义属性
缺少可访问性属性	不符合WCAG合规要求	添加 `aria-label` 、 `role` 与键盘处理器
过度嵌套子卡片	深度嵌套导致性能下降	限制最多2层嵌套；尽可能扁平化结构
忽略空状态	数据源无返回记录时UI异常	配置明确的空状态提示
硬编码记录ID	跨环境使用时卡片失效	使用合并字段与上下文驱动参数

Scoring Rubric (130 Points)

评分细则（130分）

All FlexCards are validated against 7 categories. Thresholds: ✅ 90+ (Deploy) | ⚠️ 67-89 (Review) | ❌ <67 (Block - fix required)

Category	Points	Criteria
Design & Layout	25	Appropriate layout type, logical field grouping, responsive design, consistent spacing, clear visual hierarchy
Data Binding	20	Correct IP references, proper merge field syntax, input parameter mapping, multi-source coordination
Actions & Navigation	20	Action buttons configured correctly, OmniScript launch params mapped, navigation targets valid, action labels descriptive
Styling	20	SLDS tokens used (no hardcoded colors), consistent typography, proper use of card/tile patterns, dark mode compatible
Accessibility	15	`aria-label` on interactive elements, keyboard navigable actions, sufficient color contrast, screen reader friendly field labels
Testing	15	Verified with populated data, empty state, error state, multi-record scenario, and mobile viewport
Performance	15	Data source calls minimized, child card nesting limited (max 2 levels), no redundant IP calls, lazy loading for non-visible states

所有FlexCard均需通过7个类别的验证。阈值：✅ 90分及以上（可部署） | ⚠️ 67-89分（需审查） | ❌ 67分以下（需修复，阻止部署）

类别	分值	标准
设计与布局	25	布局类型合适、字段分组合理、响应式设计、间距一致、视觉层次清晰
数据绑定	20	IP引用正确、合并字段语法规范、输入参数映射正确、多数据源协调有序
动作与导航	20	动作按钮配置正确、OmniScript启动参数映射正确、导航目标有效、动作标签描述性强
样式	20	使用SLDS令牌（无硬编码颜色）、排版一致、正确使用卡片/磁贴模式、兼容暗黑模式
可访问性	15	交互元素带有 `aria-label` 、动作支持键盘导航、颜色对比度充足、字段标签适合屏幕阅读器
测试	15	已验证已填充数据、空状态、错误状态、多记录场景及移动端视窗
性能	15	数据源调用最小化、子卡片嵌套受限（最多2层）、无冗余IP调用、非可见状态懒加载

Scoring Breakdown Detail

评分细则详情

Design & Layout (25 points)

设计与布局（25分）

Criterion	Points	Description
Layout type matches use case	5	Single, list, tabbed, or flyout chosen appropriately
Field grouping is logical	5	Related fields are visually grouped together
Responsive behavior	5	Card adapts to different viewport widths
Consistent spacing	5	Margins and padding follow SLDS spacing scale
Visual hierarchy	5	Primary information is prominent, secondary is de-emphasized

标准	分值	描述
布局类型匹配使用场景	5	单卡片、列表、标签页或弹出式布局选择恰当
字段分组合理	5	相关字段在视觉上分组展示
响应式表现	5	卡片适配不同视窗宽度
间距一致	5	边距与内边距遵循SLDS间距规范
视觉层次清晰	5	主要信息突出，次要信息弱化显示

Data Binding (20 points)

数据绑定（20分）

Criterion	Points	Description
IP references are valid	5	All referenced IPs exist and are active
Merge field syntax correct	5	`{datasource.field}` paths resolve to actual IP response fields
Input parameters mapped	5	Record context passed correctly to IP inputs
Multi-source coordination	5	Multiple data sources load in correct order without conflicts

标准	分值	描述
IP引用有效	5	所有引用的IP均存在且已激活
合并字段语法正确	5	`{datasource.field}` 路径可解析为实际IP响应字段
输入参数映射正确	5	记录上下文正确传递到IP输入参数
多数据源协调有序	5	多个数据源按正确顺序加载，无冲突

Actions & Navigation (20 points)

动作与导航（20分）

Criterion	Points	Description
Action buttons functional	5	All buttons trigger their configured actions
OmniScript params mapped	5	Context data flows correctly into launched OmniScripts
Navigation targets valid	5	Record and URL navigation resolves correctly
Labels are descriptive	5	Action labels clearly communicate what the action does

标准	分值	描述
动作按钮功能正常	5	所有按钮可触发配置的动作
OmniScript参数映射正确	5	上下文数据正确传递到启动的OmniScript
导航目标有效	5	记录与URL导航可正确解析
标签描述性强	5	动作标签清晰说明动作用途

Styling (20 points)

样式（20分）

Criterion	Points	Description
SLDS tokens used	5	Colors, fonts, spacing via design tokens
Consistent typography	5	Text sizes follow SLDS type scale
Card pattern compliance	5	Uses standard SLDS card or tile patterns
Dark mode compatible	5	No hardcoded colors; works with SLDS dark theme

标准	分值	描述
使用SLDS令牌	5	通过设计令牌设置颜色、字体、间距
排版一致	5	文本大小遵循SLDS字体规范
符合卡片模式规范	5	使用标准SLDS卡片或磁贴模式
兼容暗黑模式	5	无硬编码颜色；适配SLDS暗黑主题

Accessibility (15 points)

可访问性（15分）

Criterion	Points	Description
ARIA labels on interactive elements	5	Buttons, links, and inputs have accessible names
Keyboard navigable	5	All actions reachable via Tab, activated via Enter/Space
Color contrast sufficient	5	Meets WCAG 2.1 AA contrast ratio (4.5:1 for text)

标准	分值	描述
交互元素带有ARIA标签	5	按钮、链接与输入框具备可访问名称
支持键盘导航	5	所有动作可通过Tab键导航，Enter/Space键激活
颜色对比度充足	5	符合WCAG 2.1 AA对比度标准（文本4.5:1）

Testing (15 points)

测试（15分）

Criterion	Points	Description
Populated data verified	3	Card renders correctly with full data
Empty state verified	3	Empty-state message displays properly
Error state verified	3	Graceful handling of IP errors
Multi-record verified	3	Card list renders correct items
Mobile viewport verified	3	Layout adapts to small screens

标准	分值	描述
已验证已填充数据	3	卡片在数据完整时渲染正常
已验证空状态	3	空状态提示显示正常
已验证错误状态	3	可优雅处理IP错误
已验证多记录	3	卡片列表渲染正确条目
已验证移动端视窗	3	布局适配小屏幕

Performance (15 points)

性能（15分）

Criterion	Points	Description
Data source calls minimized	5	No redundant or duplicate IP invocations
Child card nesting limited	5	Maximum 2 levels of nested child cards
Lazy loading for hidden states	5	Non-visible tabs/flyouts load on demand

标准	分值	描述
数据源调用最小化	5	无冗余或重复IP调用
子卡片嵌套受限	5	最多2层嵌套子卡片
非可见状态懒加载	5	非可见标签页/弹出式卡片按需加载

CLI Commands

CLI命令

bash

undefined

bash

undefined

Query active FlexCards in the org

查询组织中已激活的FlexCard

sf data query -q "SELECT Id,Name,DataSourceConfig,PropertySetConfig,IsActive FROM OmniUiCard WHERE IsActive=true" -o <org>

Retrieve a specific FlexCard by name

按名称检索特定FlexCard

sf project retrieve start -m OmniUiCard:<Name> -o <org>

Deploy a FlexCard to the target org

将FlexCard部署到目标组织

sf project deploy start -m OmniUiCard:<Name> -o <org>

Retrieve all FlexCards

检索所有FlexCard

sf project retrieve start -m OmniUiCard -o <org>

Deploy all OmniStudio metadata (FlexCards + dependencies)

部署所有OmniStudio元数据（FlexCard及依赖项）

sf project deploy start -m OmniUiCard -m OmniIntegrationProcedure -m OmniScript -o <org>

---

sf project deploy start -m OmniUiCard -m OmniIntegrationProcedure -m OmniScript -o <org>

---

Data Source Binding

数据源绑定

FlexCard Data Source Configuration

FlexCard数据源配置

The

DataSourceConfig

field on

OmniUiCard

contains the data source bindings as JSON. The

PropertySetConfig

field contains the card layout, states, and field definitions.

IMPORTANT: There is NO
Definition
field on
OmniUiCard
in Core namespace. Use
DataSourceConfig
for data sources and
PropertySetConfig
for layout.

json

{
  "dataSource": {
    "type": "IntegrationProcedures",
    "value": {
      "ipMethod": "Type_SubType",
      "vlocityAsync": false,
      "inputMap": {
        "recordId": "{recordId}"
      },
      "resultVar": ""
    },
    "orderBy": {
      "name": "",
      "isReverse": ""
    },
    "contextVariables": []
  }
}

OmniUiCard

的

DataSourceConfig

字段包含JSON格式的数据源绑定信息。

PropertySetConfig

字段包含卡片布局、状态与字段定义。

重要提示：Core命名空间下的
OmniUiCard
不存在
Definition
字段。请使用
DataSourceConfig
配置数据源，使用
PropertySetConfig
配置布局。

json

{
  "dataSource": {
    "type": "IntegrationProcedures",
    "value": {
      "ipMethod": "Type_SubType",
      "vlocityAsync": false,
      "inputMap": {
        "recordId": "{recordId}"
      },
      "resultVar": ""
    },
    "orderBy": {
      "name": "",
      "isReverse": ""
    },
    "contextVariables": []
  }
}

Data Source Types

数据源类型

Type	`dataSource.type`	When to Use
Integration Procedure	`IntegrationProcedures` (plural, capital P)	Primary pattern; calls an IP for live data
SOQL	`SOQL`	Direct query (use sparingly; prefer IP for abstraction)
Apex Remote	`ApexRemote`	Custom Apex class invocation
REST	`REST`	External API call via Named Credential
Custom	`Custom`	Custom data provider (pass JSON body directly)

类型	`dataSource.type`	使用场景
Integration Procedure	`IntegrationProcedures` （复数，首字母大写P）	主要模式；调用IP获取实时数据
SOQL	`SOQL`	直接查询（谨慎使用；优先使用IP进行抽象）
Apex Remote	`ApexRemote`	调用自定义Apex类
REST	`REST`	通过命名凭据调用外部API
自定义	`Custom`	自定义数据提供程序（直接传递JSON主体）

Field Mapping from IP Response

从IP响应映射字段

Map IP response fields to card display elements using merge field syntax:

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响应字段映射到卡片展示元素：

IP响应:                    FlexCard合并字段:
─────────────                   ─────────────────────
{ "Name": "Acme Corp" }   →    {Name}
{ "Account": {            →    {Account.Name}
    "Name": "Acme Corp"
  }
}
{ "records": [             →    {records[0].Name}  (单条记录)
    { "Name": "Acme" }          或使用卡片列表布局迭代展示
  ]
}

Input Parameter Mapping

输入参数映射

Pass context from the hosting page into the IP data source:

Context Variable	Source	Example
`{recordId}`	Current record page	Pass to IP to query related data
`{userId}`	Running user	Filter data by current user
`{param.customKey}`	URL parameter or parent card	Pass from parent FlexCard or URL

将宿主页面的上下文传递到IP数据源：

上下文变量	来源	示例
`{recordId}`	当前记录页面	传递到IP以查询关联数据
`{userId}`	当前运行用户	按当前用户过滤数据
`{param.customKey}`	URL参数或父卡片	从父FlexCard或URL传递

Cross-Skill Integration

跨技能集成

Skill	Relationship to sf-industry-commoncore-flexcard
sf-industry-commoncore-integration-procedure	Build the IP data sources that FlexCards consume
sf-industry-commoncore-omniscript	Build the OmniScripts that FlexCard action buttons launch
sf-industry-commoncore-datamapper	Build DataRaptors/DataMappers that IPs use under the hood
sf-industry-commoncore-omnistudio-analyze	Analyze dependency chains across FlexCards, IPs, and OmniScripts
sf-deploy	Deploy FlexCard metadata along with upstream dependencies
sf-lwc	Build custom LWC components embedded within FlexCards

技能	与sf-industry-commoncore-flexcard的关系
sf-industry-commoncore-integration-procedure	构建FlexCard依赖的IP数据源
sf-industry-commoncore-omniscript	构建FlexCard动作按钮可启动的OmniScript
sf-industry-commoncore-datamapper	构建IP底层使用的DataRaptor/DataMapper
sf-industry-commoncore-omnistudio-analyze	分析FlexCard、IP与OmniScript之间的依赖链
sf-deploy	部署FlexCard元数据及上游依赖项
sf-lwc	构建可嵌入FlexCard的自定义LWC组件

Edge Cases

边缘场景

Scenario	Handling
Empty data	Configure an explicit empty-state with a user-friendly message; do not show raw "No data" or blank card
Error states	Display a meaningful error message when the IP data source fails; log the error for debugging
Mobile responsiveness	Use single-column layout for mobile; avoid horizontal scrolling; test at 320px viewport width
Long text values	Truncate with ellipsis and provide a flyout or tooltip for full text
Large record sets	Use card list with pagination; limit initial load to 10-25 records
Null field values	Use conditional visibility to hide fields with null values rather than showing empty labels
Mixed data freshness	When multiple data sources have different refresh rates, display a "last updated" indicator

场景	处理方式
空数据	配置明确的空状态与友好提示；请勿显示原始的“无数据”或空白卡片
错误状态	IP数据源失败时显示有意义的错误提示；记录错误信息用于调试
移动端响应式	移动端使用单列布局；避免横向滚动；在320px视窗宽度下测试
长文本值	使用省略号截断文本，并提供弹出式或提示框展示完整文本
大型数据集	使用带分页的卡片列表；初始加载限制为10-25条记录
空字段值	使用条件可见性隐藏空值字段，而非显示空标签
混合数据新鲜度	当多个数据源刷新速率不同时，显示“最后更新”指示器

FlexCard vs LWC Decision Guide

FlexCard与LWC决策指南

Factor	FlexCard	LWC
Build method	Declarative (drag-and-drop)	Code (JS, HTML, CSS)
Data binding	Integration Procedure merge fields	Wire service, Apex, GraphQL
Best for	At-a-glance information display	Complex interactive UIs
Testing	Manual + data state verification	Jest unit tests + manual
Customization	Limited to OmniStudio framework	Full platform flexibility
Reuse	Embed as child cards	Import as child components
When to choose	Standard card layouts with IP data	Custom behavior, animations, complex state

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

Dependencies

依赖项

Required: Target org with OmniStudio (Industries Cloud) license,

sf

CLI authenticated For Data Sources: Active Integration Procedures deployed to the target org For Actions: Active OmniScripts deployed (if action buttons launch OmniScripts) Scoring: Block deployment if score < 67

Creating FlexCards programmatically: Use REST API (

sf api request rest --method POST --body @file.json

). Required fields:

Name

VersionNumber

OmniUiCardType

(e.g.,

Child

). Set

DataSourceConfig

(JSON string) for data source bindings and

PropertySetConfig

(JSON string) for card layout. The

sf data create record --values

flag cannot handle JSON in textarea fields. Activate by updating

IsActive=true

after creation.

必需条件：拥有OmniStudio（Industries Cloud）许可证的目标组织、已认证的

sf

CLI 数据源依赖：已部署到目标组织的已激活Integration Procedure 动作依赖：已部署的已激活OmniScript（若动作按钮需启动OmniScript） 评分要求：评分低于67分则阻止部署

通过API创建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

标志无法处理文本区域字段中的JSON。创建后需更新

IsActive=true

以激活卡片。

External References

外部参考

OmniStudio FlexCards Trailhead - Official learning module
OmniStudio Developer Guide - Technical reference
Salesforce Industries Documentation - FlexCard configuration guide

OmniStudio FlexCards Trailhead - 官方学习模块
OmniStudio Developer Guide - 技术参考文档
Salesforce Industries Documentation - FlexCard配置指南