본문으로 건너뛰기

DataList 控件介绍

번역 준비 중이 가이드는 현재 중국어 간체로만 제공됩니다. 번역본은 추후 추가됩니다.

DataList 用于在页面中展示和操作 Business Object 数据。它会读取业务对象的字段、查询定义和动作，因此适合订单、设备、客户等模型数据列表。

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

  • 绑定 Business Object 和 DQL Query
  • 使用 FX 将输入控件、页面上下文或 URL 参数传给 DQL
  • 配置列、列链接、分页和显示样式
  • 使用 Fixed Filters 限定不可移除的基础数据范围
  • 使用 Query Fields 配置首行快捷查询，并使用 Query Form 扩展高级查询
  • 在工具栏按钮中刷新 DataList 或替换本地表格数据
  • 将 Business Object Action 配置为行操作

DataList 是面向 Business Object 的模型列表，不提供 Custom URL 数据源。需要直接调用任意 HTTP API 时，请使用 ProTable控件介绍 中的 Custom URL 数据源。需要展示 Spark Tasks 时，请使用 TaskList 控件介绍。

1. 使用前准备​

1.1 准备 Business Object​

进入 Spark Designer → Objects Designer，确认目标业务对象已经完成以下配置：

  1. 已关联可用的数据源和物理表。
  2. 需要展示的字段允许用于列表展示。
  3. 需要作为筛选或查询条件的字段已配置为可搜索、可筛选、已索引或标识字段。
  4. 用作行唯一标识的字段稳定且不会重复，通常使用 id。
  5. 如需行操作，已在业务对象中定义对应的 Object Action。

如果 DataList 的 Fixed Filters 或 Query Fields 候选列表为空，请先检查 Business Object 字段是否已经设置为可搜索、可筛选、已索引或标识字段。

如需使用 Query Form 提供高级查询，还应为同一个 Business Object 创建 Data Form，并在 Usage Scenarios 中启用 Query。Query Form 是可选资产，不影响 Fixed Filters 和 Query Fields 的使用。

1.2 按需要创建 DQL​

DQL 用于保存可复用的 Business Object 查询条件。进入：

Objects Designer → Data → Filters

点击 Add DQL 创建查询。Query Key 由系统自动生成，不需要手工维护。

例如，按宠物编码进行可选的模糊查询：

code LIKE :code

在参数定义中将 code 设置为非必填。运行时：

  • 输入参数时，查询会按编码进行包含匹配。
  • 参数为空时，该条件不会参与查询。
  • LIKE 参数直接传入用户输入值，不需要手工添加 %。

如果一个 DQL 参数被设置为必填，DataList 执行查询时必须提供有效值，否则查询会失败。

1.3 确认数据隔离方式​

是否需要租户字段由数据模型和数据源的隔离方式决定：

  • 独占数据源或无需租户隔离的对象，可以使用数据源范围隔离，不必强制增加租户字段。
  • 多租户共享物理表时，应在 Business Object 映射中明确唯一的租户字段。
  • DQL 只负责业务查询条件，不能覆盖模型层已经强制执行的数据隔离条件。

1.4 区分模型请求与 Custom URL 请求​

DataList 只使用 Business Object 的 Model Data Source，不直接请求用户配置的 HTTP URL。和其他页面控件一样，它的模型查询、行操作及相关表单请求都会携带统一页面上下文 Header：X-Spark-Page-Environment（DEV/TEST/PROD）和 X-Spark-Page-Render-Mode（DESIGN_PREVIEW/RUNTIME）。Spark 模型运行时还会继续处理版本、权限和数据隔离。

统一 Header 并不会把 DataList 变成任意 HTTP 数据源。需要直接调用自定义后端接口时，仍应使用 ProTable 或 CardSet 的 Custom URL，或使用明确的页面 Interaction。不要为了调用任意 API 而把 DataList 的 DQL 或 Toolbar 交互当作 Custom URL 数据源。

2. 添加 DataList​

  1. 打开目标页面并进入 Page Designer。
  2. 在左侧组件面板展开 Data 分组。
  3. 将 DataList 拖入页面中的可接收容器。
  4. 选中 DataList，在右侧属性面板的 Basic 区域完成配置。
  5. 建议为 DataList 设置稳定且易识别的控件名称，例如 petList、orderList。

稳定的控件名称便于后续在 FX、按钮交互和 Component API 中识别目标控件。

3. 配置模型和 DQL​

3.1 选择 Model​

在 Model 属性中选择 Business Object。选择后，DataList 会自动获取：

  • 可展示字段
  • 可查询字段
  • Business Object Action
  • 可选的 DQL Query

切换 Model 时，应重新检查 Columns、Fixed Filters、Query Fields、Query Form、DQL Parameters 和 Row Operations。原模型中的字段、表单或动作可能不再适用于新模型。

3.2 选择 DQL Query​

在 DQL Query 中选择当前 Business Object 已发布的 DQL。DQL 是可选配置：

  • 未选择 DQL：DataList 使用模型基础查询，并叠加页面配置的筛选条件。
  • 选择 DQL：DataList 使用 DQL，并继续叠加 Fixed Filters、Query Fields 和 Query Form 条件。

DQL、Fixed Filters、Query Fields 和 Query Form 之间按 AND 关系组合。

3.3 配置 DQL Parameters​

选择包含参数的 DQL 后，DQL Parameters 会列出参数名称。参数名来自 DQL 定义，页面只需要配置参数值。

点击参数右侧的 FX，在 Value Resolver 中添加变量并选择数据来源。常用来源如下：

来源适用场景
Component Value读取 Input、Select、Radio、Date Picker、Uploader 等页面控件的当前值
Page Context读取页面上下文或业务参数
URL Parameter读取浏览器地址中的查询参数
Current Row在行上下文中读取当前记录字段
Static Value传入固定文本、数字或布尔值

添加变量后，在 Target Value 中引用变量：

[[petCode]]

Range 类型控件返回两个元素，可分别引用开始值和结束值：

[[queryRange.0]]
[[queryRange.1]]

如果一个参数值需要组合多个变量，也可以在同一个 Target Value 中引用多个变量。参数较多时，DQL Parameters 区域会在限定高度内滚动，不会持续把下方属性推到很远的位置。

在 FX 对话框中点击 Add Variable 只是增加一个变量绑定。完成变量来源和 Target Value 配置后，再保存对话框。

4. 配置 Columns​

展开 Columns，选择需要展示的业务字段。列顺序就是运行时表格的展示顺序。

配置建议：

  • 第一列放置最容易识别记录的名称或编码。
  • 数量、状态、时间等字段按业务阅读顺序排列。
  • 避免一次展示过多低频字段；详情信息可以通过列链接、行操作、Dialog 或 Drawer 展示。
  • 确保 Row Unique Key 对应的值在所有记录中唯一。

需要点击某一列进入详情页时，编辑该列的链接配置：

  1. 启用列链接。
  2. 在 Target Page 中选择目标页面。
  3. 在 Param Name 中填写目标页面接收的参数名，通常为 id。
  4. 在 Row Field 中选择当前行用于传参的字段。

例如，将当前行 id 以 id 参数传给详情页，运行时会形成类似以下导航参数：

?id=<当前行 id>

5. 配置 Pagination​

展开 Pagination 配置默认分页大小。运行时 DataList 会将当前页码和分页大小传给模型查询。

建议：

  • 普通管理列表使用 10 到 20 条/页。
  • 字段较少、页面高度充足时可以适当增加。
  • 数据量较大时不要通过超大分页一次加载全部记录。

点击查询按钮调用 reloadTable 时，DataList 会从第一页重新查询，避免保留在已经不存在的后续页码。

6. 配置固定筛选和查询区域​

DataList 将不可见的数据范围约束与用户可操作的查询条件分开配置：

配置运行时是否可见作用
Fixed Filters否每次查询都必须满足的固定条件
Query Fields是显示在筛选栏首行的快捷查询控件
Query Form是点击 More 后显示的高级查询表单
Show Filter Bar不适用控制 Query Fields、Query Form 和查询按钮是否显示

DataList 不会像 TaskList 那样自动提供默认查询字段。希望显示查询区域时，必须至少配置一个 Query Field 或选择一个 Query Form，并保持 Show Filter Bar 开启。

6.1 配置 Fixed Filters​

Fixed Filters 会自动附加到每一次查询中，运行时不展示给用户，也不能由用户移除。即使关闭 Show Filter Bar，Fixed Filters 仍然生效。

适合以下场景：

  • 页面只展示某一种业务类型的数据
  • 固定过滤已归档或已删除记录
  • 根据 Page Context 限定所属项目、组织或父记录
  • 根据 URL 参数将列表限定在当前详情记录下

在 Fixed Filters 中点击 Add，为每条条件配置 Field、Operator 和 Value。Value 既可以直接填写，也可以点击 FX，在统一的 Value Resolver 中引用 Page Context、URL Parameter、Component Value 或静态变量。

Fixed Filters 支持以下常用操作符：

操作符含义值示例
EQ等于OPEN
NEQ不等于DELETED
LIKE包含PET-01
GE大于等于100
GT大于100
LE小于等于500
LT小于500
BETWEEN区间2026-07-01,2026-07-31
IN属于集合OPEN,PROCESSING
NOT_IN不属于集合DELETED,CLOSED

IN、NOT_IN 使用英文逗号分隔多个值；BETWEEN 使用“开始值,结束值”。空值不会生成筛选条件。

6.2 开启或关闭 Show Filter Bar​

Show Filter Bar 控制整个运行时查询区域：

  • 开启：当 Query Fields 或 Query Form 至少配置一项时，显示查询区域。
  • 关闭：隐藏 Query Fields、Query Form、Search、More 和 Reset，但不影响 Fixed Filters。
  • 开启但未配置 Query Fields 和 Query Form：不显示空白查询区域。

查询范围固定、页面不允许用户继续缩小结果时，可以关闭 Show Filter Bar。

6.3 配置 Query Fields​

Query Fields 用于定义筛选栏首行的快捷查询控件。打开 Query Fields 对话框后，点击 Add，每一行可以配置：

属性说明
Field从当前 Business Object 的可查询字段中选择，不允许重复选择同一个字段
Operator按字段真实类型提供可用操作符
Placeholder运行时控件中的占位提示，用于说明查询用途

使用上移和下移图标调整查询字段顺序，使用删除图标移除字段。运行时控件按该顺序显示。配置对话框中的 Field、Operator 和 Placeholder 标签位于控件上方；Operator 为较长的本地化名称预留了完整显示空间。

Query Fields 根据字段类型渲染控件并限制操作符：

字段类型默认操作符可选操作符运行时控件
Text、String、TextareaContainsContains、Equals、Not equal文本输入框
Number、Decimal、MoneyEqualsEquals、Not equal、Greater than or equal、Greater than、Less than or equal、Less than数字输入框
Enum、Select、BooleanEqualsEquals、Not equal、In、Not in下拉框；In 和 Not in 使用多选
Date、DateTime、TimestampRangeRange日期或日期时间范围选择器
User、DepartmentEqualsContains、Equals、Not equal用户或部门选择器

运行时不重复显示可见 Label，而是使用 Placeholder 说明字段用途。日期和日期时间字段使用 Range：开始值编译为 GE，结束值编译为 LE，两个边界都包含在结果中。

6.4 创建并选择 Query Form​

Query Form 是可选配置，用于承载不适合全部放在首行的高级查询条件。DataList 引用的是 Objects Designer 中的 Data Form，不是 Task Form。

创建 Query Form：

  1. 进入 Spark Designer → Objects Designer，打开 Data Forms。
  2. 新建或编辑与 DataList 相同 Business Object 的 Data Form。
  3. 在 Usage Scenarios 中启用 Query。
  4. 只保留用户实际需要的可查询字段，设置合适的标题、Placeholder 和 Field Width。
  5. 保存 Data Form，返回 Page Designer，在 DataList 的 Query Form 中选择该表单。

Query Form 会保留 Data Form 中配置的 24 栅格 Field Width。例如，4 个字段都设置为宽度 6 时，运行时 More 区域会把它们保持在同一行；宽度依次为 8、8、8 时，一行显示 3 个字段。需要换行时，让当前行宽度合计达到 24，或在 Data Form 中调整字段顺序和宽度。

Query Form 下拉框只列出当前 Business Object 可用且支持 Query 场景的 Data Form。如果下拉列表为空，检查 Data Form 是否绑定了同一个 Business Object、是否启用了 Query 场景，以及当前版本是否已保存。

点击运行时的 More 图标后，Query Form 显示在快捷查询行下方。Query Form 字段遵循以下规则：

  • 只渲染当前 Business Object 中可查询且未隐藏的字段。
  • Text 使用包含匹配，普通标量字段使用等值匹配。
  • Date、DateTime 和 Timestamp 自动使用 Range 查询。
  • Query 模式不会强制 Required 校验，空字段不参与查询。
  • Uploader、Multi Row Input、Rich Editor 和 JSON Editor 不作为查询控件渲染。

6.5 Search、More 和 Reset​

  • Search：读取 Query Fields 和 Query Form 当前值，从第一页重新查询。
  • More 图标：仅在配置 Query Form 时出现，用于展开或收起高级查询区域。
  • Reset 图标：清空 Query Fields 和 Query Form 值、收起 More，并从第一页重新查询。
  • Enter：在文本型 Query Field 中按 Enter 可以直接查询。

空值不会参与查询。最终查询按以下关系组合：

Business Object 数据权限与隔离条件
AND DQL Query
AND Fixed Filters
AND Query Fields
AND Query Form

7. 配置 Toolbars（可选）​

DataList 支持左侧工具栏和右侧工具栏。Toolbars 是列表命令和自定义控件区域，不是内置查询栏的前置条件。普通字段查询优先使用 Query Fields 和 Query Form，不需要在 Toolbar 中重复添加 Search 和 Reset。

以下场景仍适合使用 Toolbars：

  • DQL 参数需要读取页面上的自定义 Input、Select 或 Date Picker
  • 提供 Create、Import、Export 等列表命令
  • 放置 Uploader、Dropdown 或业务专用按钮
  • 通过 Component API 主动刷新列表或替换本地数据

选中 DataList，在属性面板打开 Toolbars：

  1. 在 Left Toolbar 分组点击 Add，选择 Input、Date Picker、Select 等查询控件。
  2. 在 Toolbar 分组点击 Add，选择 Button、Dropdown 等操作控件。
  3. 点击已添加的控件，继续设置 Label、Name 和交互。

常见布局：

  • Left Toolbar：自定义 DQL 参数控件、Uploader 或其他业务输入。
  • Toolbar：Create、Import、Export 等操作按钮。

选中工具栏内的控件后，可继续在属性面板中编辑控件本身。请为查询控件设置稳定且不重复的名称，便于 DQL 参数和按钮交互引用。

7.1 自定义 DQL 查询按钮刷新 DataList​

只有在使用 Toolbar 控件驱动 DQL Parameters 等自定义查询时，才需要手工添加 Search 按钮并配置点击交互：

  1. 选中 Search 按钮，打开 Interaction editor。
  2. 新增 Component API 动作。
  3. Target Component 选择当前 DataList，例如 petList。
  4. Function 选择 reloadTable。
  5. 保存交互配置。

点击按钮时，DQL Parameters 会重新解析当前控件值，DataList 随后从第一页查询。

7.2 使用 setTableData 更新本地数据​

当按钮先调用自定义接口，并希望直接把接口返回数组展示在 DataList 中时，可以调用：

setTableData(data)

data 应为记录数组。该函数会替换当前表格数据，并同步重置分页状态。对于标准 Business Object 查询，优先使用 reloadTable，让分页、筛选和总数继续由模型查询统一处理。

7.3 工具栏 Uploader 与导入按钮​

需要先上传文件再执行导入时，可以采用以下结构：

  1. 在工具栏中添加 Uploader，并设置稳定名称，例如 importFiles。
  2. 添加 Import 按钮。
  3. 在 Import 按钮的请求参数中，通过 FX 读取 importFiles 的 Component Value。
  4. 请求成功后，再调用 DataList 的 reloadTable。

工具栏 Uploader 上传后的附件通过附件查看入口管理，不应将完整附件列表直接展开并撑大工具栏。表单中的 Uploader 用于表单字段，其展示和数据提交方式与工具栏场景不同。

8. 配置 Row Operations​

Row Operations 用于对当前记录执行 Business Object Action，例如编辑、启用、停用、归档或删除。

8.1 前置条件​

先在 Business Object 中定义动作及参数。DataList 不应使用前端临时逻辑替代需要复用、校验或审计的业务动作。

8.2 添加行操作​

  1. 展开 Row Operations。
  2. 点击添加操作。
  3. 选择 Business Object Action。
  4. 配置操作名称和显示方式。
  5. 将 Action 参数绑定到 Current Row 字段、静态值或页面上下文。
  6. 按业务顺序调整多个行操作的位置。

例如，删除动作通常将 Action 的记录参数绑定到当前行 id。

8.3 配置交互​

编辑行操作的 Interaction 时，可以配置：

  • 执行前确认提示
  • 打开 Dialog 或 Drawer
  • 设置 Page Context
  • 调用其他组件函数
  • 执行后刷新 DataList

危险操作应提供明确的确认步骤。操作完成后，可调用当前 DataList 的 reloadTable 显示最新数据。

9. Advanced 属性​

DataList 的高级属性包括：

属性说明
Enable Row Number显示行序号
Table Size设置 large、middle 或 small 密度
Show Header是否显示包含列标题的表头行；关闭后只隐藏列标题，不隐藏 DataList 标题、Toolbar、查询区域或数据行
Bordered是否显示表格边框
Row Unique Key每一行的唯一标识字段，默认使用 id

Row Unique Key 必须稳定且唯一。使用名称、状态等可能重复或变化的字段，会导致选中状态、更新和渲染出现异常。

10. 完整示例：使用 DQL 参数按 Pet Code 模糊查询​

目标：用户输入 Pet Code 后点击 Search，DataList 按编码模糊查询；未输入时显示全部可访问记录。

如果 code 只是普通可查询字段，更简单的方式是在 Query Fields 中添加 code，选择 Contains 并设置 Placeholder，运行时直接使用内置 Search 和 Reset。下面的示例用于说明需要复用参数化 DQL，或 DQL 参数必须来自自定义 Toolbar 控件时的配置方式。

第一步：创建 DQL​

在 Business Object 的 Data → Filters 中创建 DQL：

code LIKE :code

将 code 参数设置为非必填。

第二步：添加查询控件​

选中 DataList，打开 Toolbars，在 Left Toolbar 分组点击 Add 并选择 Input：

  • Label：Pet Code

第三步：绑定 DQL 参数​

  1. 在 DataList 中选择刚创建的 DQL Query。
  2. 在 DQL Parameters 中找到 code。
  3. 点击 FX。
  4. 添加变量 petCode。
  5. Source 选择 Component Value。
  6. Component 选择 Pet Code控件。
  7. 添加 “+”符号，添加变量
[[petCode]]

第四步：配置 Search 按钮​

为 Search 按钮添加 Component API 交互：

  • Target Component：当前 DataList
  • Function：reloadTable

第五步：验证​

  1. 不输入 Pet Code，点击 Search，应返回全部可访问记录。
  2. 输入部分编码，点击 Search，应返回编码包含该文本的记录。
  3. 清空输入后再次点击 Search，应恢复未按编码过滤的结果。
  4. 如同时配置 Fixed Filters、Query Fields 或 Query Form，确认结果满足所有条件的交集。

11. 保存、预览和运行验证​

完成配置后，建议按以下顺序验证：

  1. 保存页面。
  2. 打开 Preview，检查列宽、工具栏换行、Query Fields、Query Form 栅格和分页。
  3. 验证 DQL 参数有值和为空两种情况。
  4. 验证内置 Search、More、Reset、列链接和行操作。
  5. 打开实际 Runtime 页面，重复关键查询和操作。
  6. 确认 Preview 与 Runtime 的工具栏对齐、控件宽度和交互结果一致。

设计态只负责配置和近似预览，数据权限、真实附件上传、接口调用和模型查询应以 Runtime 验证结果为准。DataList 的 Network 请求应指向 Spark 模型运行时接口；如果页面直接请求了业务 Custom URL，应检查是否误用了 ProTable、CardSet 或自定义 Toolbar 交互。

12. 常见问题​

12.1 选择 Model 后没有可选字段​

检查 Business Object 是否已完成数据表映射，字段是否允许用于列表展示或查询，并确认当前版本已经保存或发布。

12.2 选择 DQL 后没有 DQL Parameters​

DQL 中只有使用 :PARAM_NAME 声明的参数才会出现在 DQL Parameters。先在 Objects Designer 中验证并保存 DQL，再返回页面重新选择。

12.3 参数为空时仍然查询不到数据​

检查该 DQL 参数是否被设置为必填。希望“空值不筛选”时，应将参数设置为非必填，并保证该参数只控制需要忽略的条件。

12.4 LIKE 查询没有结果​

直接传入用户输入文本，不要在 FX 值中添加 %。同时检查字段类型是否为可执行文本包含查询的类型。

12.5 点击自定义 Toolbar Search 后数据没有变化​

依次检查：

  1. Search 按钮是否配置了 Component API。
  2. Target Component 是否为正确的 DataList。
  3. Function 是否为 reloadTable。
  4. DQL 参数是否通过 FX 引用了正确控件。
  5. 控件名称是否唯一且未在配置后被修改。

12.6 Query Fields 没有显示或没有生效​

依次检查：

  1. Show Filter Bar 是否开启。
  2. Query Fields 中是否已经添加至少一个字段。
  3. Business Object 字段是否可搜索、可筛选、已索引或为标识字段。
  4. Operator 是否适用于该字段类型。
  5. 是否点击了内置 Search；空值不会参与查询。

12.7 Query Form 下拉列表为空​

检查 Data Form 是否绑定了与 DataList 相同的 Business Object，Usage Scenarios 是否包含 Query，以及当前开发版本是否已经保存。普通 Create、Edit 或 View Data Form 不会作为 Query Form 候选项。

12.8 行操作列表为空​

先在 Business Object 中定义 Object Action，并确认 DataList 绑定的就是该 Business Object。

12.9 行更新后页面仍显示旧数据​

在操作成功后的交互链中调用 DataList 的 reloadTable。如果使用 setTableData，确认传入的是完整记录数组，而不是单条对象或接口外层响应对象。

12.10 Preview 正常但 Runtime 报权限或数据隔离错误​

检查 Runtime 环境中的 Business Object 发布版本、数据源权限、用户数据权限和模型隔离配置。不要通过前端 DQL 参数绕过模型层的数据隔离规则。

13. 配置检查清单​

  • DataList 已绑定正确的 Business Object
  • 已确认当前场景需要 Model Data Source，而不是任意 Custom URL
  • 模型接口请求携带正确的页面环境和渲染场景 Header
  • Columns 只包含需要展示的字段
  • Row Unique Key 稳定且唯一
  • DQL 已验证，参数必填性符合业务需求
  • DQL Parameters 的 FX 来源和 Target Value 正确
  • Fixed Filters 不会误排除合法记录
  • Show Filter Bar 的开启状态符合页面需求
  • Query Fields 的字段、操作符、Placeholder 和顺序正确
  • 如需高级查询，Query Form 已绑定同一个 Business Object 并启用 Query 场景
  • 自定义 Toolbar Search 按钮调用了当前 DataList 的 reloadTable
  • 列链接传递了正确的行字段
  • Row Operations 已绑定正确的 Current Row 参数
  • Preview 与 Runtime 均已验证

完成以上配置后，DataList 就可以作为 Business Object 列表页的稳定数据入口，并与页面查询控件、DQL 和业务动作协同工作。

최종 수정: 에