@datafe-open/markdown-chart-kpi

严格、框架中立的 KPI 卡片渲染器 @datafe-open/markdown-chart。 。 。 .

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

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

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

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

```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 仍然是内置来源 数据表; 一个只命名的组在不切换该单一数据集的情况下生成 .

{
  "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 选项 :

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

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

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

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 输出前, 更新渲染器 .