CardSet 控件介绍

CardSet 用于将同一数据源中的多条记录渲染为响应式卡片集合。它适合商品目录、应用列表、资产目录和知识条目等需要快速浏览实体摘要的页面。

阅读本手册后，你可以完成以下配置：

使用 Business Object 或 Custom URL 加载数据
为 Custom URL 定义或导入可复用的 Response Fields
从可视模板库选择 Standard、Cover 或 Compact 卡片
将返回记录字段映射到标题、描述、图片、状态和元数据
配置 Fixed Filters、Query Fields 和 Query Form
设置桌面、平板和移动端列数
在 Pagination 与 Load More 之间选择翻页方式
使用 Current Record 配置整卡点击和卡片操作

CardSet 是数据驱动的重复集合，不用于手工逐条维护静态卡片。表格型数据请使用 DataList 或 ProTable。

1. 使用前准备

1.1 选择数据来源

CardSet 支持以下数据源：

数据源	适用场景
Model Data Source	数据来自 Spark Business Object，并需要 DQL、模型字段或 Query Form
Custom URL	数据来自应用 API、外部服务或自定义聚合接口

使用 Model Data Source 前，应先在 Objects Designer 中完成 Business Object、字段、查询和 QUERY 场景 Data Form。

Custom URL 应提供可分页的记录集合。推荐响应格式：

{
  "success": true,
  "data": {
    "current": 1,
    "pageSize": 12,
    "records": [],
    "total": 0
  }
}

1.2 本文示例

本文使用 Spark Sample 商品目录接口：

POST https://spark.hiforce.ai/spark/api/sample/cardset/products

接口返回 23 条英文商品数据，包含：

字段	用途
`id`	记录唯一键
`code`	卡片辅助标题
`name`	卡片标题
`description`	卡片描述
`imageUrl`	封面图片
`status`	状态标签
`category`	商品分类
`price`	商品价格
`stock`	当前库存
`updatedAt`	更新时间

2. 添加 CardSet

打开目标页面并进入 Page Designer。
在左侧组件面板展开 Containers。
将 CardSet 拖入页面容器。
选中 CardSet，在右侧属性面板先配置 Data Source，再配置 Card Template。
为控件设置稳定名称，例如 productCardSet。

CardSet 不会再要求先猜测一个 Java CardTemplate 类名。模板外观和字段映射统一在可视配置对话框中完成。

3. 配置 Data Source

3.1 Custom URL 示例

在 Data Source 中选择 Custom URL，配置：

属性	值
URL	`/spark/api/sample/cardset/products`
Request Method	`POST`
Rows Path	`data.records`
Total Path	`data.total`
Current Page Path	`data.current`
Page Size Path	`data.pageSize`

Custom URL 本身不能像 Business Object 一样提供模型元数据，因此还需要在同一个 Data Source 对话框中配置 Response Fields。本文示例配置如下：

Field Path	Label	Data Type
`id`	ID	`NUMBER`
`code`	Code	`TEXT`
`name`	Name	`TEXT`
`description`	Description	`TEXT`
`imageUrl`	Image URL	`URL`
`status`	Status	`TEXT`
`category`	Category	`TEXT`
`price`	Price	`NUMBER`
`stock`	Stock	`NUMBER`
`updatedAt`	Updated At	`DATETIME`

Response Fields 有两种配置方式：

点击加号手工添加 Field Path、Label 和 Data Type。
填写 URL、请求方式和响应路径后，点击 Test & Import 从真实响应中导入。

Test & Import 最多读取 20 条记录，并合并其中出现的字段。嵌套对象会生成 owner.name 形式的点路径；数组只登记为 ARRAY，不会生成带数组下标的不稳定路径。导入会保留已经手工修改的 Label、Data Type 和顺序，只追加新字段，不会自动删除旧字段。接口返回空数组或请求失败时，现有配置不会变化。

Response Fields 是保存到页面配置中的字段契约，不保存接口返回的样例值。打开 Data Source 对话框也不会自动调用后台。

CardSet 会发送当前页、每页数量、固定筛选、快捷查询和 Query Form 值。POST 请求示例：

{
  "current": 1,
  "pageSize": 12,
  "conditions": [
    {"field": "status", "operator": "EQ", "value": "ACTIVE"}
  ],
  "queryFormValues": {}
}

Custom URL 请求还会自动携带统一的页面上下文 Header：

Header	枚举值	说明
`X-Spark-Page-Environment`	`DEV`、`TEST`、`PROD`	当前页面环境；设计器内预览固定使用 `DEV`
`X-Spark-Page-Render-Mode`	`DESIGN_PREVIEW`、`RUNTIME`	Page Designer、设计器打开的 Preview 和真实记录预览为 `DESIGN_PREVIEW`；普通运行页为 `RUNTIME`

例如，开发环境运行页发送 DEV + RUNTIME，Card Template 对话框中的真实记录预览发送 DEV + DESIGN_PREVIEW。这是所有 Page Designer 和 Page Runtime 后端请求的统一规范，不局限于 CardSet。后端应按稳定枚举处理，不要通过 Referer 推断场景；跨域 Custom URL 还需要在 CORS 的 Access-Control-Allow-Headers 中允许这两个 Header。

3.2 Model Data Source

选择 Model Data Source 后：

选择 Business Object。
按需选择 DQL Query。
在 Request Parameters 中绑定 DQL 参数。
Card Template 的字段下拉列表会直接使用当前 Business Object 的字段元数据。

Model Data Source 的分页、DQL 参数和查询条件由 Spark 运行时统一处理。

4. 选择 Card Template

点击 Card Template 右侧的编辑图标，打开宽版配置对话框。顶部模板库会直接显示三个缩略预览：

模板	适用场景
Standard	通用业务实体，标题、描述、状态和元数据结构均衡
Cover	商品、媒体和资产目录，突出 16:9 封面图片
Compact	运维或管理工作台，减少描述区域并提高信息密度

选择模板后，右侧预览会立即变化，不需要保存或进入运行页才能判断模板外观。模板库下方按主题分为 Content、Query 和 Layout & paging 三个 Tab；右侧预览始终保留，Desktop、Tablet、Mobile 用于切换预览宽度。

配置区域和预览区域可以独立滚动。Content 中的 Card fields、Metadata 和 Status tones 都使用独立分组；Query fields 与 Fixed filters 也使用带列标题的配置表。配置较多时，应在当前 Tab 内继续向下滚动，底部配置不会被对话框截断。

5. 配置字段映射

进入 Content Tab 配置 Card fields、Metadata 和 Status Tones。每个 Card field 右侧都会标记它所在的卡片区域，例如 Heading、Corner、Above title 或 Body；Title 带红色必填标记。

本文 Cover 示例使用以下映射：

卡片区域	字段
Eyebrow Field	`code`
Title Field	`name`
Description Field	`description`
Image Field	`imageUrl`
Status Field	`status`

Title Field 是最重要的识别字段，应始终配置。其他字段为空时，对应区域不会保留空白占位。

5.1 字段来源与自定义路径

字段下拉列表由 Data Source 提供：

Model Data Source 使用 Business Object 字段元数据。
Custom URL 使用已经保存的 Response Fields。

选择字段时会显示 Label (path)，可以按标签或路径搜索。确实需要绑定未登记的动态字段时，选择 Add custom path 后手工填写。常规字段应优先加入 Response Fields，避免不同 CardSet 或 ProTable 重复维护字符串路径。

嵌套对象使用点路径，例如：

owner.name
pricing.amount

Title Field 是保存 CardSet 的必填项。其他可选映射为空时，对应卡片区域不会渲染。

5.2 刷新真实预览

数据源和字段映射保存后，点击右侧 Live Preview 标题旁的刷新图标。设计器会以 pageSize=1 读取一条记录，并发送 X-Spark-Page-Environment: DEV 与 X-Spark-Page-Render-Mode: DESIGN_PREVIEW。

刷新只更新右侧卡片展示值，不会新增、删除或修改 Response Fields。请求失败时继续保留当前预览和字段配置。

5.3 配置 Metadata

Metadata 用于展示价格、库存、负责人或更新时间等短信息。点击 Add row 新增一行。配置表会固定显示 Label、Field 和 Format 列标题：

属性	说明
Label	卡片中显示的短标签，例如 `Price`
Field Path	数据字段，例如 `price`
Format	`TEXT`、`NUMBER`、`CURRENCY`、`DATE` 或 `DATETIME`

商品示例建议添加：

Label	Field	Format
Category	`category`	`TEXT`
Price	`price`	`CURRENCY`
Stock	`stock`	`NUMBER`

5.4 配置 Status Tones

Status Tones 是可选的状态色映射。配置表使用 When status equals 和 Show tone 两列，例如将 ACTIVE 映射为 SUCCESS、DRAFT 映射为 WARNING。未配置映射时，CardSet 会对常见状态值使用内置语义色，并对未知值使用 MUTED。

6. 配置查询

进入 Query Tab 配置 Query Form、Show Filter Bar、Query Fields 和 Fixed Filters。Query Form 与 Show Filter Bar 位于顶部工具条，查询字段和固定条件分别位于下方分组。

6.1 Query Fields

Query Fields 显示在查询区域首行。配置表固定显示 Field、Label、Operator 和 Type 列标题。

选择字段后，设计器会用 Response Field 或 Business Object 字段的 Label 和 Data Type 预填查询配置；Label 和查询类型仍可继续调整。OBJECT 和 ARRAY 不会出现在快捷查询字段候选中。

推荐商品示例：

Field	Label	Operator	Type
`name`	Search products	`LIKE`	`TEXT`
`category`	Category	`EQ`	`TEXT`
`status`	Status	`EQ`	`TEXT`

日期和时间类型会自动渲染为 Range Picker。Search、More 和 Reset 始终位于查询栏右侧。

6.2 Fixed Filters

Fixed Filters 每次查询都生效，但不会显示给运行用户。例如，只展示有效商品：

Field	Operator	Value
`status`	`EQ`	`ACTIVE`

关闭 Show Filter Bar 只会隐藏用户查询区域，不会禁用 Fixed Filters。

6.3 Query Form

Query Form 是可选的高级查询表单。在下拉列表中选择 QUERY 场景的 Data Form 后，运行时点击 More 展开表单。CardSet 使用 Model Data Source 时，下拉列表会优先显示当前 Business Object 的查询表单；使用 Custom URL 时会显示应用中可用的 QUERY 表单。

Model Data Source 应选择当前 Business Object 的 QUERY Data Form。
Custom URL 会把 queryFormValues 原样发送给后端，由接口解释字段含义。

7. 配置布局和分页

进入 Layout & paging Tab 配置响应式列数、间距、分页和行唯一键。Responsive columns 分组会用 Desktop、Tablet 和 Mobile 三个设备示意图实时显示当前列数；Paging & data 分组集中维护 Paging Mode、Page Size 和 Row Unique Key。

推荐默认值：

属性	默认值
Desktop Columns	`4`
Tablet Columns	`2`
Mobile Columns	`1`
Spacing	`DEFAULT`
Page Size	`12`
Paging Mode	`PAGINATION`
Row Unique Key	`id`

Paging Mode 支持：

PAGINATION：显示总数和页码，适合管理页面。
LOAD_MORE：追加下一页记录，适合浏览型目录。
NONE：只展示接口当前返回的数据，不显示翻页控件。

使用右侧 Desktop、Tablet、Mobile 分段控件检查单卡宽度；实际运行时列数会按页面宽度自动切换。

8. 配置交互

CardSet 支持两层交互：

整卡 onClick。
卡片底部操作项的 onClick。

8.1 配置卡片操作项

Card Actions 不在 Card Template 配置对话框中。 先在画布中选中 CardSet，再到右侧属性面板的 Card Actions 子元素区域完成配置：

点击 Add child element，新增一个 CardAction。
在新增表单中填写 Title 并确认。设计器会自动选中刚创建的 CardAction。
在 CardAction 的属性面板中通过统一 Icon 选择器选用系统图标或上传自定义图片。
点击 Interaction，为 CardAction 添加 onClick 事件和后续动作。

需要修改已有操作项时，先在 Card Actions 列表中点击对应行。列表左侧的拖动手柄用于调整顺序；运行时按照该顺序在卡片底部展示前 3 个操作项。操作项点击会阻止事件冒泡，因此不会同时触发整卡点击。

8.2 配置整卡点击

重新选中 CardSet 本身，再点击 Interaction 并配置 CardSet 的 onClick。配置了整卡点击的卡片支持 Tab 聚焦，以及 Enter、Space 键触发。

8.3 读取当前记录

无论触发整卡点击还是操作项点击，CardSet 都会先把被点击卡片对应的记录写入运行时上下文中的 record。在 Interaction 编辑器中，该数据源显示为 Current Record；后续动作可以读取：

record.id
record.code
record.name

这里的字段值来自本次点击的卡片记录，不是设计时写死的固定值。Custom URL 应先配置 Response Fields，Model Data Source 应提供 Business Object 字段元数据，这样 Interaction 编辑器才能给出正确的 Current Record 字段候选。

8.4 示例：在抽屉中展示卡片详情

下面以 View product 操作项为例，在同一个 onClick 中依次配置两个动作：

添加 Set component value 动作，并命名为 Fill product details。将 record.id、record.code、record.name 等 Current Record 字段分别写入详情抽屉中的表单控件。
添加 Open/close dialog/drawer 动作，并命名为 Open product details。将 Target component 设为 Product details (Drawer)，同时打开 Open target。

务必先写入表单值，再打开抽屉。Interaction 会按照 Action tree 从上到下执行；如果顺序相反，抽屉打开时可能短暂显示上一条记录或空值。

配置完成后的运行效果如下：点击卡片底部的 View product，抽屉会展示当前卡片对应的商品详情。

9. Sample 后端实现

样例代码位于：

spark-sample/src/main/java/hiforce/spark/sample/cardset/

商品查询复用 ProTable 示例的分页和条件处理，CardSet 控制器负责公开专用 URL；封面图片由本地 PNG 端点生成，不依赖外部图片服务。

本地启动后可验证：

curl -X POST 'http://localhost:18080/spark/api/sample/cardset/products' \
  -H 'Content-Type: application/json' \
  -H 'Accept-Language: zh-CN' \
  -H 'X-Spark-Page-Environment: DEV' \
  -H 'X-Spark-Page-Render-Mode: DESIGN_PREVIEW' \
  -d '{"current":1,"pageSize":12,"conditions":[{"field":"status","operator":"EQ","value":"ACTIVE"}]}'

样例响应中的 data.requestContext 会回显规范化后的 environment 和 renderMode，便于验证后端确实接收并处理了页面上下文。生产业务接口可以使用该上下文选择数据或执行审计，不要求回显。

10. 常见问题

设计器只有模板名称，没有外观

确认使用的是新的 Card Template 编辑图标。模板应以三个缩略图展示；如果仍出现旧 ResourceInfoCard 等类名，请刷新设计器元数据并重新添加 CardSet。

运行时没有卡片

依次检查：

Data Source 是否已保存。
Rows Path 是否指向数组。
Title Field 是否存在于记录中。
浏览器 Network 中请求是否成功。
Fixed Filters 是否排除了所有记录。

Custom URL 的字段下拉列表为空

打开 Data Source，检查是否已经保存 Response Fields。可以手工添加，也可以确认 URL 和 Rows Path 正确后使用 Test & Import。刷新 Live Preview 不负责生成字段目录。

Test & Import 没有导入字段

依次检查 URL、请求方式、Rows Path 和浏览器 Network。接口必须在当前条件下至少返回一条记录；合法但为空的结果不会生成字段，此时应手工维护 Response Fields。

图片不显示

Image Field 必须返回浏览器可访问的图片 URL。相对 URL 应以当前 Spark 域名为基准，并确认接口没有返回 HTML 登录页。

查询后结果没有变化

Custom URL 后端必须处理 conditions 和 queryFormValues。CardSet 只负责发送查询语义，不会在浏览器中对完整数据集做二次过滤。

1. 使用前准备​

1.1 选择数据来源​

1.2 本文示例​

2. 添加 CardSet​

3. 配置 Data Source​

3.1 Custom URL 示例​

3.2 Model Data Source​

4. 选择 Card Template​

5. 配置字段映射​

5.1 字段来源与自定义路径​

5.2 刷新真实预览​

5.3 配置 Metadata​

5.4 配置 Status Tones​

6. 配置查询​

6.1 Query Fields​

6.2 Fixed Filters​

6.3 Query Form​

7. 配置布局和分页​

8. 配置交互​

8.1 配置卡片操作项​

8.2 配置整卡点击​

8.3 读取当前记录​

8.4 示例：在抽屉中展示卡片详情​

9. Sample 后端实现​

10. 常见问题​

设计器只有模板名称，没有外观​

运行时没有卡片​

Custom URL 的字段下拉列表为空​

Test & Import 没有导入字段​

图片不显示​

查询后结果没有变化​

11. 配置检查清单​