TaskList 控件介绍
TaskList 用于在页面中展示 Spark Tasks。它以任务设计器中保存的 Filter 为基础数据范围，并复用任务权限、任务字段、任务详情和运行期查询能力。
阅读本手册后，你可以完成以下配置：
- 使用 Task Filter 限定 TaskList 的基础任务范围
- 使用 Task Form 渲染高级查询条件
- 添加系统字段和自定义字段作为表格列
- 调整列顺序、标题、宽度、排序、固定方式和超长省略
- 将 Task Key 或其他列配置为任务链接
- 控制筛选栏、列设置和分页大小
- 验证 Assignee、Select、Date 和 DateTime 字段的查询行为
1. TaskList 的适用场景
TaskList 适合以下场景：
- 在业务页面中展示某一种或一组任务
- 使用 TQL 固定任务类型、状态、步骤或其他基础条件
- 让用户继续按标题、负责人、时间和自定义字段缩小结果范围
- 点击列表中的任务编号或业务字段打开任务详情
- 在同一张表中同时展示任务系统字段和业务自定义字段
TaskList、DataList 和 ProTable 的数据边界不同：
| 控件 | 主要数据 | 查询定义 | 典型用途 |
|---|---|---|---|
| TaskList | Spark Tasks | Task Filter + 运行期条件 | 任务列表、审批列表、业务待办页面 |
| DataList | Business Object | DQL + 模型筛选 | 订单、客户、设备等对象数据 |
| ProTable | Custom URL 或模型数据源 | HTTP 请求参数或模型查询 | 第三方接口、聚合数据、自定义分页协议 |
如果页面展示的不是任务，请改用 DataList 或 ProTable。
2. 前置知识与示例来源
TaskList 展示的是 Spark Tasks 流程任务。开始配置前，建议先完成以下内容：
- 阅读流程设计器介绍，了解 Task Type、字段、表单、步骤、工作流和权限方案之间的关系。
- 完成 快速开始：采购审批流程，确保可以在 DEV 中创建并处理 Purchase Request。
本文直接复用该快速开始中已经配置完成的采购审批流程，不再重复创建流程资产。快速开始提供以下基础内容：
| 资产 | 示例配置 |
|---|---|
| Task Type | PURCHASE / Purchase Request |
| Workflow | Purchase Approval |
| 自定义字段 | 包括 Finance Review Result、Department Review Result、Required Date 等采购申请字段 |
| 运行数据 | 已在 DEV 中创建并完成不同审批分支验证的 Purchase Request |
在这些流程资产之上，本文继续配置 TaskList 所需的列表资产和页面属性：
| 资产或属性 | 本文配置 |
|---|---|
| Task Filter | All Purchase Request Tasks |
| Filter TQL | taskType = "PURCHASE" ORDER BY createdAt DESC |
| Query Form | purchaseQueryForm |
| Query Form 字段 | Assignee、Finance Review Result、Department Review Result、Required Date |
| Columns | Task Key、Title、Task Type、Current Step、Created At |
| Page Size | 20 |
| Show Filter Bar | 开启 |
| Show Column Settings | 开启 |
3. 使用前准备
3.1 准备任务资产
在当前应用和设计版本中确认以下资产已经保存：
- Task Type 已配置工作流、权限方案和所需表单。
- 需要展示或查询的自定义字段已经添加到 Task Type。
- 至少存在一个可供 TaskList 引用的 Task Filter。
- 如需高级查询，已经创建专用 Task Form。
TaskList 的候选项按当前 App + Version 加载。在 DEV 中，可以使用当前开发版本已经保存的任务资产；在 TEST 或 PROD 验证时，应确认对应版本已经发布到目标环境。
3.2 创建 Task Filter
进入 Task Designer → Data & Permission → Filters，创建 Filter 并保存 TQL。本文示例为：
taskType = "PURCHASE" ORDER BY createdAt DESC
输入 taskType = 后，从当前版本的候选列表中选择 Purchase Request。TQL 使用稳定的 Task Type Key PURCHASE，不要用显示名称代替 Key。
Task Filter 决定 TaskList 的基础任务范围。运行期用户不能移除这段 TQL，任务权限也不会因为 Filter 条件而放宽。有关语法和权限边界，请阅读 Filter 与 TQL。
3.3 创建 Query Form
Query Form 是可选配置，不是显示查询区域的前置条件。只要开启 Show Filter Bar，即使不选择 Query Form，TaskList 也会提供默认查询条件：
- 首行快捷条件：Title、Status、Task Type、Created At。
- 点击 More 后的高级条件：Current Step、SLA Status、Assignee、Updated At。
Search 保持为查询区域右侧的主按钮，More 和 Reset 使用紧随其后的图标按钮，列设置位于操作组末尾。配置 Query Form 后，TaskList 会保留上述默认条件，并在 More 区域继续追加 Query Form 中的自定义字段；Query Form 不会替换默认条件。关闭 Show Filter Bar 时，默认条件和 Query Form 都不会显示。
需要增加业务自定义查询字段时，建议创建专用 Task Form，只放置用户真正需要的查询字段，不要直接复制包含大量只读详情或附件的业务表单。
本文使用 purchaseQueryForm：
| 字段 | 字段类型 | 运行期查询控件 |
|---|---|---|
| Assignee | User | 用户选择器 |
| Finance Review Result | Select | Approved / Rejected 下拉框 |
| Department Review Result | Select | Approved / Rejected 下拉框 |
| Required Date | Date | 日期范围选择器 |
Query Form 不要求绑定某一个 Task Type 才能用于查询。字段定义仍来自当前应用和版本，因此应保证表单引用的字段没有被删除。
4. 添加并配置 TaskList
- 打开目标页面并进入 Page Designer。
- 在左侧组件面板展开 Task 分组。
- 将 TaskList 拖入页面中的可接收容器。
- 选中 TaskList，在属性面板完成基础配置。
TaskList 的主要属性如下：
| 属性 | 是否必填 | 说明 |
|---|---|---|
| Task Filter | 是 | 选择任务设计器中保存的 Filter，运行期按 Filter Key 加载 TQL |
| Query Form | 否 | 在默认查询条件之外，将 Task Form 字段追加到 More 区域 |
| Columns | 否 | 按顺序配置系统字段和自定义字段；未配置时使用任务列表默认列 |
| Show Filter Bar | 否 | 控制是否显示整个查询区域 |
| Show Column Settings | 否 | 控制右上角列设置入口；只有显示筛选栏时才会出现 |
| Page Size | 否 | 默认每页数量，默认值为 20，允许范围为 1 到 200 |
本文示例选择：
Task Filter: All Purchase Request Tasks
Query Form: purchaseQueryForm
Show Filter Bar: On
Show Column Settings: On
Page Size: 20
关闭 Show Filter Bar 后，快捷条件、More、Search、Reset 和列设置入口都会隐藏，页面只保留任务表格与分页器。适合查询范围固定、不允许用户继续调整条件的页面。
5. 配置 Columns
5.1 添加和排序列
展开 TaskList 下的 Columns，点击 Add。每次添加都会在左侧树中生成一条 Task Column，而不是把所有列保存在一个多选框中。
对每一条列配置：
- 在 Task Field 中选择系统字段或自定义字段。
- 检查自动带出的 Column Title，按页面语义修改标题。
- 打开 Advanced，按需要设置宽度、任务链接、排序、固定列和超长省略。
- 在左侧树中拖动 Task Column，调整运行期列顺序。
设计画布中的表头应随 Task Field、Column Title 和列顺序同步变化。Column Title 已经承担列显示名称，不需要再维护额外的 Display Name。
5.2 可选字段
Task Field 候选分为两组：
- System Fields：Task Key、Title、Task Type、Status、Current Step、Assignee、Creator、Created At、Updated At、SLA 等。
- Custom Fields：当前应用和版本中定义的任务字段，例如 Amount、Category、Required Date、Department Review Result。
自定义字段即使不是独立 Worklist 的默认可见列，也可以由页面作者明确添加到 TaskList。
5.3 列高级属性
| 属性 | 说明 |
|---|---|
| Width | 列宽，单位为像素 |
| Task Link | 点击该列值时打开任务 |
| Enable Sorting | 允许用户按该列排序，仅对后端支持排序的字段生效 |
| Fixed Column | 将列固定在表格左侧或右侧 |
| Show Ellipsis | 内容超出列宽时显示省略效果 |
SLA 状态列显示时固定在第一列。建议紧随其后放置 Task Key 和 Title，并为这两列开启 Task Link。也可以把其他业务字段设为任务链接；如果显式关闭某一列的 Task Link，该列会按普通文本显示。
运行期列设置只能临时隐藏已配置列或调整排序，不会反向修改页面设计器中的列结构和顺序。
6. 运行期查询区域
6.1 快捷查询条件
开启 Show Filter Bar 后，TaskList 顶部默认展示以下快捷条件：
- Title
- Status
- Task Type
- Created At
这些控件使用 Placeholder 说明用途，不重复显示可见 Label。Search、More、Reset 和列设置按此顺序位于右侧；More 和 Reset 使用带 Tooltip 的图标按钮。查询条件与操作组在同一水平线上垂直居中。
点击 More 后会显示：
- Current Step
- SLA Status
- Assignee
- Updated At
- Query Form 中配置的字段
内置高级条件同样使用 Placeholder，不重复显示 Label。Query Form 字段保留表单自身的字段标题和布局，便于区分自定义业务条件。
6.2 Search 和 Reset
- Search：读取当前快捷条件和 Query Form 值，从第一页重新查询。
- More 图标：展开或收起高级条件和 Query Form。
- Reset 图标：清空运行期条件和 Query Form 值，然后重新查询。
- Enter：在 Title 输入框中按 Enter 可以直接执行查询。
空值不会参与查询。Task Filter、快捷条件和 Query Form 条件按 AND 关系叠加，租户、应用、环境和任务浏览权限始终由后端强制执行。
例如，本文基础 Filter 已限定 taskType = "PURCHASE"。再选择 Assignee 和 Required Date 后，结果必须同时满足：
Purchase Request 基础范围
AND 当前 Assignee
AND Required Date 范围
AND 当前用户可浏览任务权限
7. Query Form 字段的查询规则
查询控件由字段的真实类型决定，不根据字段名称猜测控件类型。
| 字段类型 | 查询行为 |
|---|---|
| Text、Textarea、Rich Text、Markdown | 包含匹配 |
| Select、Radio、Switch | 等值匹配 |
| 多选字段 | 集合匹配，即 IN |
| Number | 等值匹配 |
| User、Assignee | 用户选择器提交用户 ID，界面持续显示用户名称 |
| Department | 部门树选择器 |
| Date、DateTime | Range 方式查询，开始和结束边界都包含在结果中 |
| Attachment | 查询模式不渲染 |
隐藏字段不会进入 Query Form。业务表单中的 Required 属性在查询模式下不会强制用户输入；未填写的条件会被忽略。
7.1 Assignee
Assignee 从当前应用可用的用户目录中搜索。选择用户后，查询请求使用稳定的用户 ID，但控件仍显示用户名称或账号，不应在点击 Search 后变成纯数字 ID。
7.2 Select
Select 必须按字段配置的 Options 渲染。本文的 Department Review Result 和 Finance Review Result 都显示：
Approved
Rejected
字段名称中包含 Department 不会把 Select 误判为部门选择器。只有真实类型为 Department 的字段才显示部门树。
7.3 Date 和 DateTime
Query Form 中的 Date 和 DateTime 使用范围选择器：
- 只选择开始值：查询
field >= start - 只选择结束值：查询
field <= end - 同时选择：查询
field >= start AND field <= end
两个边界都是包含关系。Date 字段按日期值查询；DateTime 字段允许选择具体时间。
8. 打开任务和页面交互
开启某一列的 Task Link 后，点击该列值会打开任务。
- 未配置
onTaskClick：在新的浏览器标签页中打开 Spark 标准任务详情页，当前业务页面保持不变。 - 已配置
onTaskClick：在当前页面执行页面设计器中的交互，并提供task和record上下文；此时不会自动打开标准详情页。 - Ctrl / Command 点击等浏览器修饰点击：保留链接的浏览器默认行为。
需要由页面中的其他按钮刷新 TaskList 时，可以对该控件调用 Component API：
reloadTable
9. 示例验证清单
在本文示例的 DEV 运行页面中依次验证：
- 列表只返回 Filter 范围内的 Purchase Request。
- 表头按 Task Key、Title、Task Type、Current Step、Created At 的顺序显示。
- Task Key 和 Title 都显示为链接，点击后在新的浏览器标签页中打开对应任务。
- 展开 More 后可以看到
purchaseQueryForm的四个字段。 - 选择 Assignee 并点击 Search 后，控件仍显示用户名称。
- Department Review Result 显示 Approved / Rejected，而不是部门树。
- Required Date 选择不包含任务日期的区间时，该任务从结果中排除。
- 点击 Reset 后恢复到 Task Filter 的基础结果。
- 列设置可以临时隐藏列并切换可排序字段。
- 表格最后一条数据后直接衔接带分隔线的分页区域，没有无意义的大块空白。