# 分布图控件

在易企办自定义页面按状态、部门或类别展示列表记录的数量和占比。

## 放置与配置

在易企办自定义页面或仪表盘添加自定义代码控件，将下载的 TSX 完整粘贴到编辑器。先在测试应用核对字段类型与读写权限，再配置下表。

| 参数标识 | 类型 | 标准场景 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `dataListId` | 变量或表达式 | 需要 | 数据列表 ID。图表的数据来源列表，支持通过表达式获取 ID。 | `目标库存列表 ID` |
| `categoryField` | 变量或表达式 | 需要 | 分类字段。用于分组的字段标识，例如状态、部门或类别字段。 | `StockStatus` |
| `titleText` | 文本 | 按需 | 标题。可选的图表标题。 | `库存状态分布` |
| `subtitleText` | 文本 | 按需 | 副标题。显示在标题下方的操作说明。 | `按库存状态统计在库记录` |
| `chartType` | 文本 | 按需 | 图表类型。支持环形图 donut、饼图 pie、条形图 horizontalBar 或 bar，以及柱形图 verticalBar。 | `donut` |
| `maxCategories` | 文本 | 按需 | 单独显示的最大分类数。单独显示的分类上限，剩余分类汇总到「其他」。默认为 8。 | `6` |
| `showLegend` | 变量或表达式 | 按需 | 显示图例。控制图例显示，支持布尔值或表达式。 | `true` |
| `showCount` | 变量或表达式 | 按需 | 显示数量。控制图表和图例中的数量文字，支持布尔值或表达式。 | `true` |
| `emptyText` | 文本 | 按需 | 空状态提示。暂无可汇总记录时的提示。 | `暂无库存数据` |
| `colorMode` | 文本 | 按需 | 配色方案。可选 yeeflow、soft、status 或 slate。默认使用易企办配色。 | `status` |
| `sortMode` | 文本 | 按需 | 排序方式。可按数量升降序、名称升降序或来源顺序排列。默认 countDesc。 | `countDesc` |
| `filterExpression` | 变量或表达式 | 按需 | 查询筛选条件。按宿主支持的格式提供查询条件对象、数组或 JSON。留空使用无额外条件的查询。 | 按需留空 |
| `height` | 文本 | 按需 | 图表高度。图表区域的像素高度，默认为 280。 | `280` |
| `pageSize` | 文本 | 按需 | 查询条数。用于本次汇总的查询条数，默认为 500。 | `500` |
| `unknownLabel` | 文本 | 按需 | 空分类名称。分类字段为空时的分组名称，默认为「未分类」。 | `未分类` |
| `otherLabel` | 文本 | 按需 | 其他类别名称。超出单独显示数量的分类合并后的组名，默认为「其他」。 | `其他状态` |

示例字段和列表 ID 请替换为目标应用的实际值。表达式请在编辑器中绑定。

1. 选择来源数据列表。
2. 设置分类字段和图形。
3. 核对计数与占比。

## 业务示例与结果

用「在库」「待补货」「冻结」等状态生成库存环形图。状态为空的记录归入「未分类」，超出单独显示上限的类别合并到「其他状态」。

同一分类记录计数后按总记录数计算占比。支持环形、饼形、条形和柱形布局，可隐藏图例或数量。列表内容由使用者的权限决定。

来源列表需授予使用者读取权限。控件处理查询返回的记录。列表量较大时，请按目标租户的 SDK 筛选格式缩小查询范围，并核对查询条数上限。

## 预览验收

核对总条数、比例、空分类、合并类别、筛选后范围和空数据。切换图表类型确认同一组数据一致。

出现空结果时，先核对参数值、来源数据、字段标识和使用者权限。涉及写回时，再检查可写目标类型、当前页面权限及保存后的实际值。

模板已做本地源码与交互检查。发布到业务环境前，请在目标易企办租户验证当前版本的控件编辑器、数据权限和实际读写。

源模板 CCT3E128。 [Yeeflow 原站控件](https://www.yeeflow.com/templates/custom-code/distribution-chart-module)