# 关键指标卡片组

在易企办仪表盘呈现待办数量、完成率、业务金额等关键指标。

## 放置与配置

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

| 参数标识 | 类型 | 标准场景 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `cardsConfig` | 变量或表达式 | 需要 | 卡片数据。指标卡片配置，支持 JSON 数组、包含 cards、items 或 data 的对象、变量或表达式结果。 | `[{"title":"待审采购单","value":42,"format":"number","suffix":" 单","trend":"+12%","trendDirection":"up","tone":"blue","icon":"采","targetLabel":"目标","targetValue":"少于 50 单"},{"title":"准时完成率","value":96.5,"format":"percent","decimals":1}]` |
| `titleText` | 文本 | 按需 | 标题。显示在卡片组上方的可选标题。 | `采购运营指标` |
| `subtitleText` | 文本 | 按需 | 副标题。标题下方的辅助说明。 | `本周审批与交付概况` |
| `layoutMode` | 文本 | 按需 | 卡片布局。支持自动布局或固定一至四列，默认 auto。 | `auto` |
| `cardTone` | 文本 | 按需 | 默认卡片色调。卡片未单独指定色调时使用。可用 blue、green、amber、red、violet、slate。 | `blue` |
| `titleField` | 变量或表达式 | 按需 | 标题字段。用于读取指标名称的可选字段，例如 MetricName。 | `MetricName` |
| `valueField` | 变量或表达式 | 按需 | 数值字段。用于读取指标值的可选字段，例如 MetricValue。 | `MetricValue` |
| `subtitleField` | 变量或表达式 | 按需 | 副标题字段。用于读取卡片辅助说明的字段。 | `MetricNote` |
| `trendField` | 变量或表达式 | 按需 | 趋势字段。用于读取变化值或趋势说明的字段。 | `ChangeText` |
| `trendDirectionField` | 变量或表达式 | 按需 | 趋势方向字段。用于读取趋势方向，值可为 up、down 或 neutral。 | `Direction` |
| `toneField` | 变量或表达式 | 按需 | 色调字段。用于读取卡片色调，值可为 blue、green、amber、red、violet 或 slate。 | `Tone` |
| `formatField` | 变量或表达式 | 按需 | 格式字段。用于读取数值格式，可用 auto、number、percent 或 text。 | `DisplayFormat` |
| `prefixField` | 变量或表达式 | 按需 | 前缀字段。用于读取数值前方的文字。 | `Prefix` |
| `suffixField` | 变量或表达式 | 按需 | 后缀字段。用于读取数值后方的单位或文字。 | `Unit` |
| `iconField` | 变量或表达式 | 按需 | 角标字段。用于读取卡片角标文字。 | `Badge` |
| `targetLabelField` | 变量或表达式 | 按需 | 目标名称字段。用于读取目标的名称。 | `GoalLabel` |
| `targetValueField` | 变量或表达式 | 按需 | 目标值字段。用于读取目标值。 | `GoalValue` |
| `decimalsField` | 变量或表达式 | 按需 | 小数位字段。用于读取每张卡片的小数位数。 | `Decimals` |
| `showTrend` | 变量或表达式 | 按需 | 显示趋势。控制变化值或趋势说明显示，支持布尔值或表达式。 | `true` |
| `showIcon` | 变量或表达式 | 按需 | 显示角标。控制卡片角标显示，支持布尔值或表达式。 | `true` |
| `compactMode` | 变量或表达式 | 按需 | 紧凑布局。启用后缩小间距，支持布尔值或表达式。 | `false` |
| `emptyStateText` | 文本 | 按需 | 空状态提示。缺少卡片配置时的提示。 | `暂无采购指标` |
| `numberLocale` | 文本 | 按需 | 数字地区格式。数字格式的语言区域，默认 zh-CN。 | `zh-CN` |
| `decimalPlaces` | 文本 | 按需 | 默认小数位数。所有数值卡片的默认小数位数，默认为 0。 | `0` |
| `minCardWidth` | 文本 | 按需 | 最小卡片宽度。自动布局时的最小卡片宽度，默认为 220 像素。 | `220` |
| `valueSize` | 文本 | 按需 | 数值字号。可设为 small、medium 或 large，默认为 medium。 | `medium` |

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

1. 准备指标卡片数据。
2. 配置字段映射和数值格式。
3. 核对数值、趋势和排版。

## 业务示例与结果

采购看板显示「待审采购单 42单」与「准时完成率 96.5%」。用原生卡片键可直接预览。业务数据若使用 MetricName、MetricValue 等字段，则按表绑定相应映射。

卡片可显示指标、单位、趋势、目标和角标。控件从 cardsConfig 读取已计算的数据，业务汇总可由页面数据源或表达式提供。百分比格式请用代表实际百分点的值，例如 96.5 显示为 96.5%。

## 预览验收

验证内置卡片结构、自定义字段映射、百分比、小数位、趋势开关、空数据和窄屏布局。

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

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

源模板 CCT1E77C。 [Yeeflow 原站控件](https://www.yeeflow.com/templates/custom-code/kpi-card-set)