@blazes/data-visualization

面向 Blazes 应用的可复用数据标准化与数据看板运行时组件。

本包提供可序列化的 DashboardConfig v1 Schema、引用校验、注册表、Provider 执行、看板变量与 URL 状态、 Dataset 标准化、两级缓存、基于 generation 的调度、格式化、遥测以及相互隔离的 Panel 状态。Vue 入口包含 看板外壳、筛选栏、面板状态 UI，以及 Metric、Line、Bar、Pie 和基础表格渲染器。WordCloud 与实验性 S2 通过独立的异步入口提供。

包入口

| 入口 | 职责 | | ------------------------------------------------- | ------------------------------------------------------ | | @blazes/data-visualization | 与框架无关的 Core 导出 | | @blazes/data-visualization/core | 配置、Provider、Dataset、Adapter、运行时、格式化与诊断 | | @blazes/data-visualization/vue | Vue 看板、面板与标准渲染器集成 | | @blazes/data-visualization/style.css | 看板与标准渲染器样式 | | @blazes/data-visualization/renderers/word-cloud | 可选的 WordCloud 渲染器 | | @blazes/data-visualization/experimental/s2 | 可选的实验性 S2 渲染器 |

Core 入口不得依赖 Vue、Ant Design Vue、ECharts、S2、Axios 或 @blazes/charts。

图表集成要求 @blazes/charts 2.x（当前最低版本为 2.0.0-alpha.0）。标准 Vue Renderer 统一从 @blazes/charts 根入口 导入 Line、Bar、Pie、Size 与 FormatType；该入口不包含 S2。直接使用透视表组件时，宿主从 @blazes/charts/sheet 导入；看板的实验性 S2 Renderer 仍从本包的 experimental/s2 入口注册。

Core 用法

import {
  createCoreRegistries,
  createDashboardDataRuntime,
  type DashboardConfig
} from "@blazes/data-visualization/core";

const registries = createCoreRegistries();
registries.providers.register({
  id: "statistics",
  operations: {
    trend: {
      async execute(input, { signal }) {
        return apiGetTrend(input, { signal });
      }
    }
  }
});

const config = {
  schemaVersion: "1.0",
  id: "operations",
  title: "运营看板",
  variables: [{ id: "start", label: "开始日期", defaultValue: "2026-08-01" }],
  requests: [
    {
      id: "trend-request",
      providerId: "statistics",
      operationId: "trend",
      input: { start: { source: "variable", variableId: "start", codecId: "iso-date" } }
    }
  ],
  datasets: [
    {
      id: "trend-dataset",
      name: "趋势",
      input: { type: "single", requestId: "trend-request", responsePath: "rows" },
      fields: [
        { key: "date", label: "日期", role: "time", dataType: "date", required: true },
        { key: "value", label: "数值", role: "metric", dataType: "number", required: true }
      ]
    }
  ],
  panels: []
} satisfies DashboardConfig;

const runtime = createDashboardDataRuntime({
  config,
  registries,
  timezone: "Asia/Shanghai",
  locale: "zh-CN"
});

const context = runtime.createContext();
const dataset = await runtime.runDataset("trend-dataset", context);

首次执行 Provider 之前，运行时会校验配置结构和 Registry 引用。多请求 Dataset 必须注册同步 Transformer。 必填字段校验失败时会拒绝整个 Dataset；可选字段的无效值会转换为 null，并附带诊断信息。

Dashboard 用法

每个独立看板运行时都需要注册一次标准 Core 与 Vue 插件：

import { createDashboardRuntime, createStandardCoreRegistries } from "@blazes/data-visualization/core";
import { createVueRendererRegistry, registerStandardVueRenderers } from "@blazes/data-visualization/vue";
import "@blazes/charts/style.css";
import "@blazes/data-visualization/style.css";

const registries = createStandardCoreRegistries();
registries.providers.register(statisticsProvider);

export const runtime = createDashboardRuntime({
  config,
  registries,
  timezone: "Asia/Shanghai",
  locale: "zh-CN"
});
export const rendererRegistry = registerStandardVueRenderers(createVueRendererRegistry());

<DashboardRenderer :runtime="runtime" :renderer-registry="rendererRegistry" />

DashboardRenderer 默认懒加载 Panel。Panel 进入视口或默认的 600px 0px 预加载范围时开始加载。设置 :lazy-load="false" 可恢复立即加载，也可以通过 lazy-load-root-margin="300px 0px" 调整预加载距离。 不支持 IntersectionObserver 的浏览器会回退到立即加载。懒加载模式下，筛选变化和筛选栏刷新操作只刷新 预加载范围内的 Panel；屏外 Panel 接近视口时，再使用最新变量加载。

refreshPanel() 只为指定 Panel 执行相互隔离的请求与 Dataset 链路。refreshDataset() 和全局刷新仍会更新 共享 Request 的所有下游消费者。变量快速变化时会取消上一个全局 generation；刷新失败时以 stale 状态 保留最近一次成功的 ViewModel。所有标准渲染器都支持 CSV 导出，Line、Bar、Pie 和 WordCloud 还支持 PNG 导出。

日期快捷范围按看板 timezone 的昨天作为结束日期，包含昨天、排除今天；其他结束日期的范围不会被识别为“近 N 天”。 启用 URL 同步时，筛选值变化会立即更新链接参数，不等待数据请求完成。

可在看板元素或其祖先设置 CSS 变量 --dv-primary 覆盖主色，默认使用 #315fc4。卡片 loading、筛选栏 刷新按钮与普通表格分页的选中、hover、键盘聚焦颜色均使用该主色，分页的浅色背景由主色生成。

卡片标题说明

所有 Panel 可配置 titleNote，在标题旁常驻展示补充说明，使用浅灰色小号文字，空间不足时自动换行。 title 是卡片名称，description 继续作为问号图标的悬浮提示；省略或传入空的 titleNote 时不展示补充文字。 这些字段仅控制展示，统计范围由 Request 的输入绑定决定。

{
  title: "进线量",
  titleNote: "默认全部客服",
  description: "用户进线客服系统的数量"
}

柱状图滚动

柱状图可通过 enhancement.bar.visibleCount 限制同屏展示的类别数（2 到 200），完整数据仍保留在 Dataset 和图表中。超过限制时显示滑条，也可在图表内使用鼠标滚轮或拖动切换；未超过时不显示滑条。 横向排行建议降序排列，首项显示在顶部：

enhancement: {
  type: "bar",
  bar: { orientation: "horizontal", sort: "descending", showLabels: true, visibleCount: 10 }
}

可选渲染器

WordCloud 的可序列化 binding、Adapter 和渲染器定义已包含在标准 Core 注册中。在挂载使用 rendererId: "wordCloud" 的看板前，需要先加载其 Vue 实现：

import { registerWordCloudVueRenderer } from "@blazes/data-visualization/renderers/word-cloud";

await registerWordCloudVueRenderer(rendererRegistry);

S2 仍处于实验阶段。Core 和 Vue 均需显式注册，并且必须在看板运行时校验配置前完成：

import { registerPivotTableS2 } from "@blazes/data-visualization/experimental/s2";

await registerPivotTableS2(registries, rendererRegistry);

S2 面板使用固定的维度与指标配置，不直接暴露原始 S2 options：

{
  rendererId: "pivotTableS2",
  binding: {
    type: "pivotTableS2",
    datasetId: "sales",
    rowFields: ["region"],
    columnFields: ["month"],
    valueFields: ["amount", "growth"]
  }
}

两个加载器都使用独立的动态 chunk。缺少可选依赖时只会导致对应的可选渲染器失败，不会影响根入口、Core 或标准 Vue 入口。

开发

本仓库使用 Node 18 与 Yarn Classic。

yarn install
yarn verify

常用命令：

yarn typecheck
yarn test
yarn build
yarn performance:dataset
yarn size

本地包同步

默认使用 npm 已发布的 @blazes/[email protected]。需要联调未发布的组件库改动时，可选择使用 Yalc：

# /Users/yh-110081m/dev/chart
yarn yalc:publish

# /Users/yh-110081m/dev/data-visualization
yarn yalc:add:charts
yarn yalc:publish

# 消费项目
yalc add @blazes/charts @blazes/data-visualization
yarn install

首次添加后，在发生变更的组件库中执行 yarn yalc:push，即可把后续版本推送到所有已注册的消费项目。 chart 脚本通过 Volta 选择所需的 Node 22 运行时。当 chart 类型变更会影响本包时，先在 chart 中执行 yarn yalc:push，验证 data-visualization 后，再在本仓库执行 yarn yalc:push。本地包的依赖列表发生变化后， 使用对应的 yalc:update 脚本更新。.yalc/ 和 yalc.lock 是本地生成产物，不提交到 Git；发布消费项目的 manifest 前，应恢复正常版本范围。

yarn build 会生成 ESM 文件、类型声明和 reports/bundle-stats.html。yarn size 为根入口、Core 和 Vue 运行时入口依赖图执行初始 50 KB gzip 体积预算；如需测试经过明确批准的其他预算，可设置 DV_SIZE_LIMIT_KB。yarn performance:dataset 对 10,000 行数据执行初始 100ms P95 标准化性能预算；如需覆盖 经过明确批准的阈值，可设置 DV_DATASET_P95_LIMIT_MS。