Gravity UI ChartKit ·

一个基于插件的 React 组件，为多个图表库提供统一的渲染接口。您注册一个或多个插件，然后通过 <ChartKit type="..." data={...} /> 渲染图表 — ChartKit 会自动分发到正确的渲染器。

每个插件渲染器都是惰性加载的，因此底层库代码仅在 ChartKit 实际渲染到 UI 时才会被下载。ChartKit 还开箱即用地处理了移动端友好的工具提示显示。您可以直接使用内置插件，也可以实现自己的插件。

何时使用：

您需要现代声明式图表 (gravity-charts) 或时间序列/监控图表 (yagr)
您需要在单一一致的 API 下使用多种图表类型
您正在 Gravity UI 生态系统中进行开发

何时不使用：

您只需要一个特定的图表库 — 建议直接使用 @gravity-ui/charts

入门

要求

React 16、17 或 18
[@gravity-ui/uikit](https://github.com/gravity-ui/uikit) — 必需的 peer 依赖项（提供主题和 UI 基础组件）

安装

npm install @gravity-ui/chartkit @gravity-ui/uikit

样式

在您的入口文件中导入 @gravity-ui/uikit 的样式：

import '@gravity-ui/uikit/styles/fonts.css';
import '@gravity-ui/uikit/styles/styles.css';

有关完整的设置详细信息，请参阅 uikit 样式指南。

基本用法

ChartKit 使用全局插件注册表。在您的应用程序入口点调用 settings.set 一次，以注册您需要的插件。当 <ChartKit type="..." /> 渲染时，它会查找匹配的插件 — 如果找不到，则会抛出错误。每个插件的渲染器都是一个 React.lazy 组件，因此其代码仅在 ChartKit 首次出现在 UI 中时才会被获取。

您可以一次注册多个插件：

settings.set({plugins: [GravityChartsPlugin, YagrPlugin]});

或者多次调用 settings.set — 它会合并插件列表而不是替换它。

基本示例：

import {ThemeProvider} from '@gravity-ui/uikit';
import ChartKit, {settings} from '@gravity-ui/chartkit';
import {GravityChartsPlugin} from '@gravity-ui/chartkit/gravity-charts';

import '@gravity-ui/uikit/styles/fonts.css';
import '@gravity-ui/uikit/styles/styles.css';

settings.set({plugins: [GravityChartsPlugin]});

const data = {
  series: {
    data: [
      {
        type: 'line',
        name: 'Series',
        data: [
          {x: 0, y: 10},
          {x: 1, y: 25},
          {x: 2, y: 18},
          {x: 3, y: 30},
        ],
      },
    ],
  },
};

export default function App() {
  return (
    <ThemeProvider theme="light">
      <div style={{height: 300}}>
        <ChartKit type="gravity-charts" data={data} />
      </div>
    </ThemeProvider>
  );
}

ChartKit 会适应其父容器的大小 — 确保容器具有明确的高度。

更新图表包

ChartKit 将两个 Gravity UI 图表库作为依赖项捆绑：

@gravity-ui/charts — 为 gravity-charts 插件提供支持
@gravity-ui/yagr — 为 yagr 插件提供支持

如果您需要这些包的更新版本，请打开一个包更新请求 issue 并选择您需要的包。维护者将更新选定的包并发布更新。

开发

先决条件

Node.js 22 (请参阅 .nvmrc)
npm 10 或更高版本

设置

克隆仓库并安装依赖项：

git clone https://github.com/gravity-ui/ChartKit.git
cd ChartKit
npm ci

运行 Storybook

npm run start

Storybook 将在 http://localhost:7007 上可用。

使用本地依赖项进行开发

要在不发布到 npm 的情况下，在 Storybook 中查看对依赖项（例如 @gravity-ui/charts）的更改：

1. 链接本地包

# 在您的本地克隆的 @gravity-ui/charts 中：
git clone https://github.com/gravity-ui/charts.git
cd charts
npm ci
# 进行您的更改
npm run build
npm link

# 在 ChartKit 中：
npm link @gravity-ui/charts

2. 配置本地包的监视

在 ChartKit 的根目录创建一个 .env.local 文件（它会被 gitignore）：

LOCAL_PKG=@gravity-ui/charts

这会告诉 Vite 监视 node_modules 中的该包并跳过预打包。在重新构建 @gravity-ui/charts 后，Storybook 将自动热重载。

对于多个包，请使用逗号分隔的列表：

LOCAL_PKG=@gravity-ui/charts,@gravity-ui/uikit

3. 启动 Storybook

npm run start

4. 恢复原始包

完成后：

在 .env.local 中注释掉 LOCAL_PKG
在 ChartKit 中运行 npm install — 这会将符号链接替换为注册表版本

# 在 ChartKit 中：
npm ci

运行测试

npm test

视觉回归测试在 Docker 中运行，以确保跨环境的截图一致性：

npm run test:docker

在有意进行 UI 更改后更新参考截图：

npm run test:docker:update

贡献

在提交拉取请求之前，请参阅贡献指南。

许可证

MIT 协议发布。详情请参阅 LICENSE。

适用于 AI 代理

一个插件分发的 React 组件，通过单一的 <ChartKit type="..." data={...} /> API 渲染多个 Gravity UI 图表库的图表——当您需要一个统一的、支持懒加载的入口点来处理混合图表类型时，请使用它，而不是直接导入每个图表库。

何时使用

在一个统一的组件背后渲染多个图表引擎（例如 gravity-charts + yagr）。
懒加载图表包——每个插件的渲染器都是 React.lazy，因此一个库的代码仅在其实际显示图表类型时才会被获取。
将图表打包到 Gravity UI 应用中，该应用希望开箱即用地获得移动友好型工具提示和统一的主题。

何时避免使用

如果只使用一种图表类型，请直接导入 @gravity-ui/charts（通用）或 @gravity-ui/yagr（高性能时间序列）——插件注册表对于单个引擎来说是额外的开销。
要组合一个包含小部件的仪表板网格，请使用 @gravity-ui/dashkit——ChartKit 渲染图表；DashKit 安排多个小部件。

常见陷阱

在 settings.set({plugins: [...]}) 之前渲染 <ChartKit>——全局插件注册表必须在应用程序入口处填充；未注册的 type 会在渲染时抛出错误。
错误的 chartType / library 属性——分发属性是 type（例如 type="gravity-charts"），数据是 data。
忘记容器高度——ChartKit 会填充其父容器；如果没有为包装器设置显式高度，图表将收缩为零。
期望插件已打包——插件渲染器（@gravity-ui/chartkit/gravity-charts、.../yagr）是懒加载的；第一次渲染某个类型时会获取其包。
缺少 uikit 样式导入——主题依赖于 @gravity-ui/uikit/styles/styles.css；没有它，图表将渲染为未样式化。

适用于 AI 代理的文档

已安装版本的代理可读文档位于 node_modules/@gravity-ui/chartkit/build/docs/INDEX.md。

ChartKit

§Gravity UI ChartKit ·

§目录

§入门

§要求

§安装

§样式

§基本用法

§更新图表包

§开发

§先决条件

§设置

§运行 Storybook

§使用本地依赖项进行开发

§运行测试

§贡献

§许可证

§适用于 AI 代理

§何时使用

§何时避免使用

§常见陷阱

§适用于 AI 代理的文档