Collapse

Collapse 用于把相关内容组织成可展开、可收起的区域。它既可以在页面中手工维护固定面板，也可以从模型或后端接口读取记录，再通过同一个项目模板重复生成面板。

常见场景包括 FAQ、设置分组、详情分区、检查清单，以及由后端维护的知识条目。

1. 选择内容模式

选择 Collapse 后，先设置 Content Mode：

模式	适用场景	内容来源
Static	数量固定、每个面板结构不同	手工添加 CollapsePanel，并在各面板中编排内容
Data Source	面板来自同一类业务记录	配置 Data Source 和一个 Item Template，运行时按记录重复渲染

已有页面 JSON 没有 Content Mode 时，属性面板会自动显示 Static，运行态也按 Static 处理，不需要迁移。

本手册使用三个互补样例，截图和下面的配置步骤已经包含复现所需信息，不要求读者访问 Spark Sample 应用：

• Onboarding Checklist：显式设置 Content Mode = Static，四个面板分别承载不同的只读表单，用于说明静态结构、默认展开和组件函数。
• Frequently Asked Questions：设置 Content Mode = Data Source，从 /spark/api/sample/collapse/faqs 读取记录，并通过 FAQ Item Template 动态生成面板，用于说明 Test、字段映射、分页、Current Record 和开发态预览数据。
• Support Answers with Custom Content：复用同一数据源，通过页面 Content 在每个动态面板中重复渲染自定义只读 Form，用于说明共享内容与 record.* 数据绑定。

Tab 用于在并列内容间切换，Step 用于有明确顺序的任务。Collapse 适合按需展开相关内容；它不是表格，也不适合替代复杂的数据管理列表。

2. 静态 Collapse

1. 从 Containers 将 Collapse 拖入页面。
2. 保持 Content Mode = Static。
3. 在 Collapse Panels 中添加 CollapsePanel，并拖动调整顺序。
4. 选择每个 CollapsePanel，填写 Title，可选填写 Description、Icon，并配置默认展开和禁用状态。
5. 把 Form、Panel 等内容放入对应面板。

外层常用属性：

属性	说明
Single Panel Mode	开启后同时最多展开一个面板
Show Border	显示外框和面板分隔线
Transparent Style	使用轻量透明样式，适合已位于 Card 或 Drawer 分区中的 Collapse
Size	Small、Medium、Large
Arrow Position	展开箭头位于左侧或右侧

CollapsePanel 的 Trigger Area 推荐使用 Header。此时整行标题区域（包括标题右侧空白处）都可点击展开或收起；选择 Icon 时则只有箭头可触发。Disabled 只限制最终用户；在 Design Mode 中仍可从标题或页面结构进入面板编辑。

3. 数据驱动 Collapse

3.1 配置数据源

1. 把 Content Mode 改为 Data Source。
2. 配置 Row Unique Key。该字段在每条记录中都必须存在且唯一，例如 id 或 code。
3. 设置 Items Per Request 和 Empty State Text。
4. 在 Data Source 中选择模型数据源或 Custom URL。
5. 对 Custom URL 填写 URL、Method、Rows Path 和 Total Path，并维护 Record Fields。
6. 点击 Test。Test 与设计画布、运行态使用相同的请求构造和响应解析逻辑，还会检查 Row Unique Key 缺失或重复。

推荐响应结构：

{
  "success": true,
  "data": {
    "total": 6,
    "current": 1,
    "pageSize": 4,
    "records": [
      {
        "id": "invite-team",
        "category": "Getting started",
        "question": "When should I invite the wider team?",
        "answer": "Invite the wider team after access rules are ready.",
        "disabled": false,
        "defaultExpanded": true
      }
    ]
  }
}

Rows Path 使用 data.records，Total Path 使用 data.total。

3.2 选择 Item Template

Item Template 的配置方式与 CardSet 一致：点击属性面板中 Item Template 右侧的编辑按钮，会打开模板对话框。先查看并选择模板，再在同一个对话框中设置字段参数。

在 Content 中配置标题、说明、正文、分类或徽标；在 Behavior 中按需映射 Icon、Visible、Disabled 和 Default Expanded。三种模板共用同一套行为映射。

模板	适用场景	主要参数
FAQ	常见问题和帮助中心	Title Field、Answer Field、Category Field、Answer Format
Record Summary	业务记录摘要	Title Field、Description Field、Content Field、Badge Field
Custom Content	内置模板无法表达的布局	标题及行为字段；选择页面级 Content 编排正文

右侧 Live Preview 可以切换 Preview Record，也可以重新请求真实预览记录。只有点击 Save 才会写回页面配置；Cancel、关闭和 Escape 都不会污染当前模板。

3.3 使用 Content 编排自定义内容

Content 是页面级、可复用的内容资源，不是 Form，也不是隐藏在 Collapse 内部的临时子画布。页面设计器底部的 Page Resources 分为 Popups 和 Contents；选择 Content 后会从画布右侧打开宽版设计抽屉，左侧控件库和右侧属性面板仍可使用。可以点击标题栏关闭按钮、抽屉外区域、底部 Back to page，或按 Esc 返回主页面。

选择 Custom Content 后，可以：

1. 从 Content 下拉框选择已有 Content。
2. 点击 Create Content 创建并立即编辑新的 Content。
3. 点击 Edit Content 在宽版设计抽屉中编辑已关联的 Content。
4. 点击 Unlink Content 只解除当前 Collapse 的引用，不删除 Content。

同一个 Content 可以被多个 Collapse 引用；修改一次会同步影响所有引用处。仍在使用的 Content 不能删除，设计器会先提示引用数量。Content 内的控件会对每条记录重复渲染，并可在表达式和交互中直接读取：

record.id
record.question
record.answer

不要为每条记录复制一个静态 CollapsePanel。动态模式始终只维护一个 Item Template，并通过 contentId 引用一个 Content。

Spark Sample 的第三个示例在 Support answer content 中放置了一个两列只读 Form，并这样绑定字段：

Category     [[record.category]]
Environment  [[record.environment]]
Render mode  [[record.renderMode]]
Answer       [[record.answer]]

只包含一个表达式的属性会保留原始数据类型，例如 [[record.disabled]] 仍是布尔值；表达式嵌入文字时则会转换为文本，例如 Support: [[record.question]]。模板在每条记录的独立 record 作用域中解析，因此不应把 Test 返回的某一条具体值写死在默认值里。

旧页面中保存在 Item Template panels 下的自定义内容，会在设计器首次加载或保存时自动提升为页面 Content 并建立引用，不需要手工迁移。

3.4 设计预览与运行态

• Design Preview 和 Runtime 使用同一个动态渲染器。
• 设计预览只请求一页；没有可用数据或请求失败时，会显示带有 Sample Record 标识的样例，不会伪装成真实数据。
• 初次请求显示骨架屏；空数据显示 Empty State Text；失败时提供 Retry。
• 运行态记录数超过一页时显示 Load more。同一时间只发送一个加载请求。
• 重新加载后保留仍然存在的展开键，并移除已经不存在的键。
• 运行态遇到缺失或重复的 Row Unique Key 时跳过无效记录；Test 会直接提示配置错误。

4. 交互与记录上下文

静态模式支持外层 Collapse onChange 和单个 CollapsePanel onClick。动态模式则使用外层 Collapse onChange 和 Item Template onClick。

用户切换动态面板时，Spark 会先写入 Current Record，再执行 Item Template onClick，最后执行 Collapse onChange。后续动作可以读取 record.*，也可以读取：

collapse.activeKeys
collapse.expandedCount
collapse.changedKey
collapse.changedIndex
collapse.changedNumber
collapse.changedRecord
collapse.expanded
collapse.accordion
collapse.contentMode

动态 FAQ 的 Toast 可以直接填写：

FAQ: [[record.question]]

5. 组件函数

函数	说明
expandAll	展开全部可用项；Single Panel Mode 下只保留第一项
collapseAll	收起全部项
resetPanels	静态模式恢复 Expanded by Default；动态模式恢复记录映射的默认展开状态
reloadCollapse	重新请求动态数据，并协调仍然有效的展开键
setCollapseData(data)	直接用记录数组替换动态数据，适合前置动作已经取得数据的场景

静态模式不显示动态数据源和模板配置；调用动态专用函数也不会改变静态面板结构。

6. 页面请求上下文

Test、Design Preview 和 Runtime 都会自动携带：

X-Spark-Page-Environment: DEV | TEST | PROD
X-Spark-Page-Render-Mode: DESIGN_PREVIEW | RUNTIME

Data Source 中不要手工增加这两个 Header。后端可以据此返回适合开发调试的确定性数据；正式运行态再查询真实业务数据。整体协议见页面请求上下文与后端调试。

Spark Sample 使用 /spark/api/sample/collapse/faqs。核心 Controller 写法如下：

@PostMapping
public ApiResult<ProTablePageResult<CollapseFaqDTO>> queryByPost(
        @RequestBody(required = false) CollapseFaqQueryRequest request,
        @RequestHeader(value = "Accept-Language", required = false) String language,
        @RequestHeader(value = SparkPageRequestHeaders.ENVIRONMENT, required = false) String environment,
        @RequestHeader(value = SparkPageRequestHeaders.RENDER_MODE, required = false) String renderMode) {
    Locale locale = SparkApiResultHelper.resolveLocale(language);
    SparkPageRequestContext context = SparkPageRequestHeaders.resolve(environment, renderMode);
    return SparkApiResultHelper.success(locale, faqService.query(request, context),
            "SPARK-SAMPLE-COLLAPSE-0001");
}

Service 可以明确区分设计预览：

boolean designPreview = context != null
        && context.getRenderMode() == SparkPageRenderMode.DESIGN_PREVIEW;
int available = designPreview ? Math.min(4, filtered.size()) : filtered.size();

7. 复现 Spark Sample

7.1 静态开通检查清单

1. 添加 Collapse，保持 Static，关闭 Single Panel Mode。
2. 添加四个 CollapsePanel，并分别放入只读 Form。
3. 第一项开启 Expanded by Default。
4. 添加三个按钮，分别调用 expandAll、collapseAll、resetPanels。

7.2 动态 FAQ

1. 添加第二个 Collapse，选择 Data Source，开启 Single Panel Mode 和 Transparent Style。
2. Row Unique Key 填 id，Items Per Request 设为 4。
3. Custom URL 使用 /spark/api/sample/collapse/faqs，Method 选 POST，Rows Path 填 data.records，Total Path 填 data.total。
4. 点击 Test，确认记录数量和稳定键校验通过。
5. 编辑 Item Template，选择 FAQ。
6. Title Field 选 question，Answer Field 选 answer，Category Field 选 category，Disabled Field 选 disabled，Default Expanded Field 选 defaultExpanded。
7. 在 Collapse onChange 中配置 Toast：FAQ: [[record.question]]。

7.3 Custom Content 记录详情

1. 添加第三个 Collapse，选择 Data Source，并复用 /spark/api/sample/collapse/faqs 的请求和响应路径。
2. 编辑 Item Template，选择 Custom Content；Title Field 选 question，Description Field 选 summary。
3. 点击 Create Content，将新资源命名为 Support answer content；设计器会从右侧打开 Content 宽版设计抽屉。
4. 在 Content 中添加一个只读 Form，设置 Controls Per Row 为 2、Label 为 4、Content 为 8。
5. 添加 Category、Environment、Render mode 三个只读 Field，默认值分别填写 [[record.category]]、[[record.environment]]、[[record.renderMode]]。
6. 添加一个独占整行的只读 TextArea，默认值填写 [[record.answer]]，用于展示长答案。
7. 返回 Collapse 后运行 Test 或查看 Design Preview；切换不同记录时，标题和 Form 内容都应同步变化。

8. 常见问题

Test 提示 Row Unique Key 重复

检查后端返回的每条记录。Row Unique Key 不是数组索引，分页、刷新后也必须稳定；不要使用会随排序改变的序号。

设计预览显示 Sample Record

这表示数据源尚未配置、接口不可访问或请求失败。先在 Data Source 对话框点击 Test，根据 URL、响应路径和稳定键提示修复问题。

修改模板后预览没有变化

确认已经点击模板对话框的 Save。字段参数必须对应 Record Fields 或真实响应中的字段路径。

Content 中如何读取当前记录

在 Content 子控件的值或 Interaction 表达式中直接使用 record.*。第一版不需要配置参数映射；不要把预览记录的具体值写死在控件默认值中。

加载更多后原来的展开项消失

首先检查 Row Unique Key 是否稳定。Spark 会保留仍然存在的展开键，但后端如果为同一业务记录返回了新键，就无法识别为同一项。

9. 设计建议

• 一组通常保持 3～8 个可见面板；更多条目应提供分类或搜索入口。
• FAQ 和长说明优先使用 Single Panel Mode；需要对照多个区块时允许多开。
• Title 要能独立说明展开后的内容，Description 不要重复标题。
• Disabled 必须配合可读说明，不能只依赖灰色。
• 后端数据必须提供稳定唯一键，并保持分页响应结构一致。
• 动态模板的字段映射应由 Record Fields 明确声明，方便选择、测试和维护。
• 不要嵌套多层 Collapse。两层以上通常应改用小标题、Tab 或独立页面。