# @datafe-open/markdown-chart-kpi 中文文档

规范地址：https://npmcn.com/package/%40datafe-open/markdown-chart-kpi/

版本：0\.4\.1
npm 元数据更新时间：2026-10-31T14:54:59.617Z
中文译文更新时间：2026-11-11T13:48:02.097Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40datafe-open/markdown-chart-kpi
原文对照：https://npmcn.com/package/%40datafe-open/markdown-chart-kpi/?lang=original
项目主页：https://github.com/datafe/markdown-chart#readme
源码仓库：https://github.com/datafe/markdown-chart

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：96.6 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-09-03T08:27:00.209Z
- 最新版本发布：2026-10-31T14:54:59.292Z
- 近 30 天下载量：3732（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

Markdown 图表的严格框架中性KPI卡渲染器

## 安装

```sh
npm install @datafe-open/markdown-chart-kpi
```

也可以使用：`pnpm add @datafe-open/markdown-chart-kpi`、`yarn add @datafe-open/markdown-chart-kpi`、`bun add @datafe-open/markdown-chart-kpi`

## README

# `@datafe-open/markdown-chart-kpi`

严格、框架中立的 KPI 卡片渲染器 [`@datafe-open/markdown-chart`](https://npmcn.com/package/%40datafe-open/core/README.md)。 。 。 .

Metrics 共享一个单一的外图框架,项目间有空白, plain 状态文本,以及紧凑的图表/数据工具栏。 明确格式前缀和 后缀使用更小的类型而不修改其文本或空格。 线和面积 火花保持44px高;没有趋势的度量标准不需要保留趋势空间.

```ts
import { ChartRendererRegistry } from '@datafe-open/markdown-chart';
import { createKpiRenderer } from '@datafe-open/markdown-chart-kpi';

const registry = new ChartRendererRegistry().register(createKpiRenderer());
```

条形栅栏保持默认或命名数据集与 渲染器拥有的字段、格式、趋势、状态和参考配置:

````markdown
```markdown-chart
{
  "version": 1,
  "renderer": "kpi",
  "data": {
    "kind": "inline",
    "source": [
      { "day": "2026-08-31", "revenue": 16800000, "tone": "warning" },
      { "day": "2026-09-01", "revenue": 18000000, "tone": "positive" }
    ]
  },
  "spec": {
    "colorConvention": "green-up-red-down",
    "timeField": "day",
    "items": [
      {
        "id": "revenue",
        "title": "Revenue",
        "value": {
          "field": "revenue",
          "reduce": "lastNonNull",
          "format": {
            "style": "currency",
            "currency": "CNY",
            "notation": "compact",
            "maximumFractionDigits": 1
          }
        },
        "status": {
          "text": { "literal": "Above target" },
          "tone": { "field": "tone" }
        },
        "trend": {
          "type": "area",
          "compare": {
            "lag": 1,
            "mode": "relative",
            "label": "vs previous day",
            "polarity": "higher-is-better"
          }
        },
        "references": [
          { "ref": "docs://metrics/revenue", "label": "Revenue definition" }
        ]
      }
    ]
  }
}
```
````

`value.field` 从犬科数据和默认读取到 `lastNonNull` 减少. 格式化使用已验证的子集 `Intl.NumberFormat`数字 : `text`, (中文(简体) ), `decimal`, (中文(简体) ), `percent`, (中文(简体) ), `currency`,或 `unit`,加上符号,分数,前缀, 后缀和无效显示。 功能和任意表达遭到拒绝.

项目使用默认的顶级 `data` 除非他们设定 `dataset` 键 顶级 `datasets` 地图。 优先使用共享默认数据匹配 graft, 过滤器,和源; 当不同时使用命名数据集 。 每一个选定 内置/重置数据集实现一次,总行/单元格限制跨度 选定收藏。 默认 `data` 仍然是内置来源 数据表; 一个只命名的组在不切换该单一数据集的情况下生成 .

```json
{
  "data": { "kind": "inline", "source": [{ "revenue": 18000000 }] },
  "datasets": {
    "inventory": { "kind": "inline", "source": [{ "stock": 23 }] }
  },
  "spec": {
    "items": [
      { "id": "revenue", "title": "Revenue", "value": { "field": "revenue" } },
      { "id": "inventory", "title": "Inventory", "dataset": "inventory", "value": { "field": "stock" } }
    ]
  }
}
```

一个项目可以省略 `trend`,或使用一个 `line`编号 :`area` 带有精确源的闪光 行滞后、绝对/相对比较、极性、可选零包容性Y 缩放。 不到两个有效的数值点可以隐藏趋势而不失败 KPI (英语). 源命令是权威的; 无效后缀行不被跳过 .

参考犬科数据仍为主机所拥有. 将解析器传递到此渲染器 直接或通过 React/Vue 适配器 `kpi` 选项 :

```ts
const renderer = createKpiRenderer({
  validateDataRef: (ref) => ref.startsWith('dataset://'),
  resolveDataRef: (ref, { signal }) => loadDataset(ref, signal),
  referenceIcon: ({ document }) => createHostReferenceIcon(document),
});
```

解析数据集用于数值、趋势、比较和 共享数据表。 制造者从不获取或解释自己.

参考文献是单独的不透明项目配置,只成为控制 当宿主供给的时候 `referenceActions`数字 :

```ts
const referenceActions = {
  canOpen: ({ reference }: { reference: { ref: string } }) =>
    reference.ref.startsWith('docs://'),
  open: ({ reference }: { reference: { ref: string } }) => {
    openDocumentation(reference.ref);
  },
};
```

`referenceIcon` 是一个可信任的唯主机演示文稿钩。 它接收到 模糊的引用事件加控件所有者 `document` 返回一个新的 创建了装饰性的 HTML/SVG 元素。 如果钩子没了,就回不回来,或者 抛出,渲染器使用默认链接glyph. 渲染器不指定 域意指任何图标.

主机可以通过 `--markdown-chart-kpi-*` CSS自定义属性. 未设置属性有光和 从图表挂载主题中选择的暗后退 .

### 方向颜色

设定 `spec.colorConvention` 改为 `red-up-green-down` 用于中文输出或 `green-up-red-down` 用于英文产出。 比较文本及其行/区域 闪光线使用实际三角形方向,独立于 `polarity`零用途 中性灰色; 缺少/未定义的比较保留了普通口音闪光. 状态吨位仍然描述了企业状况. 没有这个可选字段, 旧 信件保留以极性为基础的比较颜色和口音闪光线. 被存储的会话控制回放;浏览器语言不会更改.

方向颜色支持 `--markdown-chart-kpi-red` 财务报告和审定财务报表 `--markdown-chart-kpi-green`,带有光/暗默认值;状态颜色变量 不变。 在启用此字段的 Skill 输出前, 更新渲染器 .

## 常见问题

### @datafe-open/markdown-chart-kpi 是什么？

Markdown 图表的严格框架中性KPI卡渲染器

### 如何安装 @datafe-open/markdown-chart-kpi？

在项目目录运行 npm install @datafe-open/markdown-chart-kpi，或使用 pnpm add / yarn add / bun add。

### @datafe-open/markdown-chart-kpi 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @datafe-open/markdown-chart-kpi 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @datafe-open/markdown-chart-kpi 可以商用吗？

@datafe-open/markdown-chart-kpi 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @datafe-open/markdown-chart-kpi 的下载量有多少？

根据 npm 官方下载统计，@datafe-open/markdown-chart-kpi 在 2026/10/12 – 2026/11/10 这 30 天内被下载 3,732 次，日均约 124 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @datafe-open/markdown-chart-kpi 还在维护吗？

最新版本 0\.4\.1 发布于 2026/10/31（10 天前）；至今共发布 13 个版本，其中过去 12 个月发布了 13 个；首次发布于 2026/09/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。