# @gravity-ui/chartkit 中文文档

规范地址：https://npmcn.com/package/%40gravity-ui/chartkit/

版本：8\.13\.0
npm 元数据更新时间：2026-11-16T14:08:10.311Z
中文译文更新时间：2026-11-16T23:46:02.647Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gravity-ui/chartkit
原文对照：https://npmcn.com/package/%40gravity-ui/chartkit/?lang=original
项目主页：https://github.com/gravity-ui/ChartKit#readme
源码仓库：https://github.com/gravity-ui/ChartKit

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

- 包体积（解压后）：474 kB，269 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：9 个
- peer 依赖：react ^16\.0\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0，@gravity-ui/uikit ^7\.0\.0
- 首次发布：2022-10-03T20:14:59.694Z
- 最新版本发布：2026-11-16T14:08:10.048Z
- 近 30 天下载量：35114（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：351（近 12 个月 112 个）

## 中文简介

基于插件的 React 组件,它通过一个单一的 ChartKit API,通过移动方便的工具提示和自定义插件支持,使多个图表库的图表如Gravity Charts 和 Yagr 生成

## 安装

```sh
npm install @gravity-ui/chartkit
```

也可以使用：`pnpm add @gravity-ui/chartkit`、`yarn add @gravity-ui/chartkit`、`bun add @gravity-ui/chartkit`

## README

# 重力 UI 图表 Kit [![npm package](https://img.shields.io/npm/v/@gravity-ui/chartkit)](https://www.npmjs.com/package/@gravity-ui/chartkit) [![License](https://img.shields.io/github/license/gravity-ui/ChartKit)](https://npmcn.com/package/%40gravity-ui/chartkit/LICENSE) [![CI](https://img.shields.io/github/actions/workflow/status/gravity-ui/ChartKit/.github/workflows/ci.yml?label=CI&logo=github)](https://github.com/gravity-ui/ChartKit/actions/workflows/ci.yml?query=branch:main) [![storybook](https://img.shields.io/badge/Storybook-deployed-ff4685)](https://preview.gravity-ui.com/chartkit/)

基于插件的 React 组件,通过一个单一的 ChartKit API,通过移动方便的工具提示和自定义插件支持,从多个图表库,如Gravity Charts 和 Yagr 生成图表. 您注册一个或多个插件,并通过 `<ChartKit type="..." data={...} />` ——ChartKit自动向正确的渲染器发送.

每个插件渲染器都是懒惰地加载的,所以基础库代码只有在ChartKit在UI中实际提供时才会被下载. ChartKit还处理出框外显示的方便移动的工具提示. 您可以使用内置插件或执行自己的插件.

**何时使用 :**

-   需要现代的申报图表( Y)`gravity-charts`)或时间序列/监测图表(`yagr`(中文(简体) )
-   在单一一致的 API 下需要多个图表类型
-   您想要与您的UI 其它部分一样遵循光/ 暗主题的图表出框

**不使用时 :**

-   您只需要一个特定的图表库 [@重力-ui/图](https://github.com/gravity-ui/charts) 直接

## 目录

-   [开始吧](https://npmcn.com/package/%40gravity-ui/chartkit/#readme-getting-started)
-   [更新图表软件包](https://npmcn.com/package/%40gravity-ui/chartkit/#readme-updating-charting-packages)
-   [发展](https://npmcn.com/package/%40gravity-ui/chartkit/#readme-development)

## 开始

### 所需资源

-   反应 16、17或18
-   [`@gravity-ui/uikit`](https://github.com/gravity-ui/uikit) - 所需同伴依赖(提供主题和UI原始人)

### 安装

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

### 样式

导入样式从 `@gravity-ui/uikit` 输入点 :

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

详细情况请参见 [uikit 样式指南](https://github.com/gravity-ui/uikit?tab=readme-ov-file#styles)。 。 。 .

### 基本用途

ChartKit使用全局插件注册. 打电话 `settings.set` 一旦在您的应用程序入口点注册您需要的插件。 何时 `<ChartKit type="..." />` ,它查找匹配的插件——如果找不到,则会出错。 每个插件的渲染器是 `React.lazy` 组件,所以其代码只有在 ChartKit 第一次出现在 UI 时才获取.

您可以同时注册多个插件 :

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

或者打电话 `settings.set` 多次——它合并了插件列表而不是取而代之.

**基本实例:**

```tsx
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` 适应其母体大小——确保容器有明显的高度.

### 分割工具

分页工具提示布局 `gravity-charts` 用于触摸设备(`tooltip={{splitted: true}}`)也可作为一个独立的组成部分。 它与任何内容一起工作:它使主面板和工具提示面板相并(或堆放,视容器大小而定),它们之间有一个可拖动的活化器.

```tsx
import {SplitTooltip} from '@gravity-ui/chartkit';

export function Panel() {
  return (
    <div style={{height: 400}}>
      <SplitTooltip
        renderMainPane={() => <MyVisualization />}
        renderTooltip={() => <MyTooltipContent />}
      />
    </div>
  );
}
```

见 `SplitTooltipProps` 类型用于布局控制、窗格大小和再分配选项.

## 更新图表软件包

ChartKit将两个Gravity UI绘图库作为依赖性:

-   [`@gravity-ui/charts`](https://github.com/gravity-ui/charts) - 授权 `gravity-charts` 插件
-   [`@gravity-ui/yagr`](https://github.com/gravity-ui/yagr) - 授权 `yagr` 插件

如果您需要这些软件包的更新版本,请打开一个 [软件包更新请求](https://github.com/gravity-ui/ChartKit/issues/new?template=package-update-request.yml) 并选择所需的软件包。 维护者会撞击所选的软件包并发布更新.

## 发展

### 先决条件

-   [节点.js](https://nodejs.org/) 22 (见 [.nvmrc (英语)](https://github.com/gravity-ui/ChartKit/blob/main/.nvmrc)(中文(简体) )
-   [无](https://www.npmjs.com/) 10岁或以后

### 设置

清除寄存器并安装依赖性 :

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

### 运行故事本

```shell
npm run start
```

故事书将在 `http://localhost:7007`。 。 。 .

### 与当地依附关系发展

从事依赖性工作(例如:. `@gravity-ui/charts`),并看到您的更改在"故事书"中现场直播而不发布到npm:

**1\. 将当地一揽子计划联系起来**

```shell
# In your local clone of @gravity-ui/charts:
git clone https://github.com/gravity-ui/charts.git
cd charts
npm ci
# make your changes
npm run build
npm link

# In ChartKit:
npm link @gravity-ui/charts
```

**2\. 配置本地软件包观看**

创建一个 `.env.local` 在 ChartKit 根中的文件( 它被 gitignored) :

```shell
LOCAL_PKG=@gravity-ui/charts
```

这告诉Vite 查看软件包 `node_modules` 并跳过预捆绑。 重建后 `@gravity-ui/charts`故事书会自动重载.

对于多个软件包,使用逗号分隔列表:

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

**3\. 开始故事书**

```shell
npm run start
```

**4\. 恢复原包**

完事时:

1.  评论 `LOCAL_PKG` 内 `.env.local`
2.  运行 `npm install` 在 ChartKit 中——它用注册版本取代了符号链接

```shell
# In ChartKit:
npm ci
```

### 正在测试

```shell
npm test
```

在 Docker 中进行视觉回归测试,以确保在各种环境中的截图一致:

```shell
npm run test:docker
```

在有意的UI更改后更新参考截图:

```shell
npm run test:docker:update
```

### 捐款

请参看 [贡献指南](https://npmcn.com/package/%40gravity-ui/chartkit/CONTRIBUTING.md) 在提交拉动请求之前.

## 许可证

根据麻省理工学院的许可证分发。 见 [自由主义](https://npmcn.com/package/%40gravity-ui/chartkit/LICENSE) 详细情况.

## 对于人工智能特工

基于插件的 React 组件,通过一个单一的图库,例如重力图库和Yagr库来制作图表 `<ChartKit type="..." data={...} />` API,每个库只有在其图表类型被渲染时才懒惰地加载.

### 何时使用

-   在一个连贯的组件后渲染不止一个绘图引擎: `gravity-charts` (通过SVG声明表) [`@gravity-ui/charts`](https://github.com/gravity-ui/charts)和 `yagr` (uPlot基于时间序列通过 [`@gravity-ui/yagr`](https://github.com/gravity-ui/yagr)) (中文(简体) ).
-   懒汉图捆绑——每个插件的渲染器是 `React.lazy`,所以只有当其图表类型实际显示时,才获取库的代码.
-   框外的方便移动的工具提示——图表及其工具提示以可调整的分页窗格显示,而不是悬浮弹出 `gravity-charts` 打开它 `<ChartKit type="gravity-charts" tooltip={{splitted: true}} />`。 。 。 .
-   自行使用分页工具提示布局—— `SplitTooltip` 是根项导出的独立组件:通过 `renderMainPane` 财务报告和审定财务报表 `renderTooltip`,它将它们划分为任何内容的可扩展的平面(垂直或水平,取自容器大小),而不仅仅是ChartKit图表.
-   写入自己的插件——寄存器 `{type, renderer}` 通过 `settings.set({plugins: [...]})`时 `renderer` 是一个 `React.lazy` 组件; ChartKit 向它发送 `type` 和内置插件完全一样.
-   连续的光线/暗色地环绕着盒子外的每个图表引擎——图表沿着 `@gravity-ui/uikit` 周围应用程序的主题.

### 不使用时

-   仅用于单个图表类型,导入 [`@gravity-ui/charts`](https://github.com/gravity-ui/charts) (一般情况)或 [`@gravity-ui/yagr`](https://github.com/gravity-ui/yagr) (高性能时间序列)直接——插件注册为一台引擎的间接费用.
-   要编成一个由部件组成的仪表板网格,请使用 [`@gravity-ui/dashkit`](https://github.com/gravity-ui/dashkit) —— ChartKit 生成一个图表; DashKit 安排了许多部件 .

### 常见陷阱

-   **渲染 `<ChartKit>` 在此之前 `settings.set({plugins: [...]})`** ——全局插件注册必须包含在应用程序条目;未注册的 `type` 时投出.
-   **迷幻道具 `chartType` 编号 : `library`** - 发送道具是 `type` (例如:. `type="gravity-charts"`),数据为: `data`。 。 。 .
-   **从根项导入插件** ——插件活在子路径导出(例如. `@gravity-ui/chartkit/gravity-charts`, (中文(简体) ), `@gravity-ui/chartkit/yagr`); 词根 `@gravity-ui/chartkit` 条目不再出口.
-   **假设一个 `data` 每张 `type`** ——形状取决于插件,例如. `gravity-charts` 带 `ChartData` 从 `@gravity-ui/charts` (单位:千美元)`{series: {data: [...]}}`),同时 `yagr` 带 `{data: {graphs, timeline}, libraryConfig}` 与 `libraryConfig` 所需经费.
-   **忘记容器高度** —— 说 `ChartKit` 填充其母;包装上没有明显的高度,图表会倒塌为零.
-   **缺少 uikit 样式导入** - 主题取决于 `@gravity-ui/uikit/styles/styles.css`没有它,图表就变无风格.

## AI代理的文件

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

## 常见问题

### @gravity-ui/chartkit 是什么？

基于插件的 React 组件,它通过一个单一的 ChartKit API,通过移动方便的工具提示和自定义插件支持,使多个图表库的图表如Gravity Charts 和 Yagr 生成

### 如何安装 @gravity-ui/chartkit？

在项目目录运行 npm install @gravity-ui/chartkit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^16\.0\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0）、@gravity-ui/uikit（^7\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gravity-ui/chartkit 支持 TypeScript 吗？

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

### @gravity-ui/chartkit 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @gravity-ui/chartkit 可以商用吗？

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

### @gravity-ui/chartkit 的下载量有多少？

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

### @gravity-ui/chartkit 还在维护吗？

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

