@gravity-ui/chartkit

中文文档
8.13.0发布于 2026/11/16MITTypeScriptCommonJS近 30 天下载 3.5万

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

中文使用文档
文档目录21 节
  1. 目录
  2. 开始
  3. 所需资源
  4. 安装
  5. 样式
  6. 基本用途
  7. 分割工具
  8. 更新图表软件包
  9. 发展
  10. 先决条件
  11. 设置
  12. 运行故事本
  13. 与当地依附关系发展
  14. 正在测试
  15. 捐款
  16. 许可证
  17. 对于人工智能特工
  18. 何时使用
  19. 不使用时
  20. 常见陷阱
  21. AI代理的文件

重力 UI 图表 Kit npm package License CI storybook

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

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

何时使用 :

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

不使用时 :

目录

开始

所需资源

  • 反应 16、17或18
  • @gravity-ui/uikit - 所需同伴依赖(提供主题和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 适应其母体大小——确保容器有明显的高度.

分割工具

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

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

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

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

更新图表软件包

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

如果您需要这些软件包的更新版本,请打开一个 软件包更新请求 并选择所需的软件包。 维护者会撞击所选的软件包并发布更新.

发展

先决条件

设置

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

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

运行故事本

npm run start

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

与当地依附关系发展

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

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

# 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) :

LOCAL_PKG=@gravity-ui/charts

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

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

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

3. 开始故事书

npm run start

4. 恢复原包

完事时:

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

正在测试

npm test

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

npm run test:docker

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

npm run test:docker:update

捐款

请参看 贡献指南 在提交拉动请求之前.

许可证

根据麻省理工学院的许可证分发。 见 自由主义 详细情况.

对于人工智能特工

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

何时使用

  • 在一个连贯的组件后渲染不止一个绘图引擎: gravity-charts (通过SVG声明表) @gravity-ui/charts和 yagr (uPlot基于时间序列通过 @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 (一般情况)或 @gravity-ui/yagr (高性能时间序列)直接——插件注册为一台引擎的间接费用.
  • 要编成一个由部件组成的仪表板网格,请使用 @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 共发布 351 个版本,首次发布于 2022/10/04;过去 12 个月发布了 112 个版本。

版本发布日期距今
8.13.0latest2026/11/16今天
8.12.12026/11/106 天前
9.0.02026/11/0610 天前
8.12.02026/11/0313 天前
8.11.02026/10/3017 天前
8.10.12026/10/2225 天前

其他发布通道:beta → 4.0.0-beta.7,untagged → 5.23.0。

关于 @gravity-ui/chartkit 的常见问题

@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 和提交记录判断。