bklit-ui

Bklit UI

基于 visx + motion 构建的可组合 React 图表组件，通过 @bklit shadcn 注册表分发。shadcn add 会将源代码复制到用户的项目中——用户拥有这些代码，且源代码是 props 的唯一依据。

使用项目的包运行器运行 shadcn CLI：npx shadcn@latest、pnpm dlx shadcn@latest、bunx --bun shadcn@latest 或 yarn dlx shadcn@latest。

当前项目上下文

!`npx shadcn@latest info --json`

如果上面的代码块为空，或仍显示命令（无法展开 ! 注入内容的 Agent），请先自行运行 npx shadcn@latest info --json，再编写代码。使用其输出了解框架、别名（@/…）、Tailwind 版本和已安装的组件。

• 没有 components.json？ 请先运行 npx shadcn@latest init。
• registries 中没有 @bklit？ 添加 "@bklit": "https://ui.bklit.com/r/{name}.json"（参见 installation.md），或通过 URL 安装：npx shadcn@latest add https://ui.bklit.com/r/line-chart.json。

原则

1. 先安装，再自行实现。 使用 npx shadcn@latest add @bklit/<item>——绝不要手写 SVG 图表或重新实现注册表中的组件。
2. 从已安装的文件导入，绝不要从 @bklitui/ui/charts 导入。 那是一个私有 monorepo 包。组件会安装到 components/charts/<file>.tsx（项目使用 src/ 时则安装到该目录下）；使用用户的别名导入，例如 @/components/charts/line-chart。参见导入。
3. 阅读已安装的源代码。 执行 add 后，打开 components/charts/ 中的文件，确认 prop 名称和默认值，再使用这些组件。
4. 组合，不要扁平化。 根图表 → Grid/Background → 系列 → 坐标轴 → 覆盖层 → ChartTooltip。参见 composition.md。
5. 使用令牌设置主题。 使用 --chart-* 变量和 chartCssVars，不要使用一次性的十六进制值。参见 theming.md。

导入

组件没有统一的导出文件——请从定义各导出的文件中分别导入（路径相对于 components/charts/ 别名）：

导入自	导出项
line-chart	LineChart、Line
area-chart	AreaChart、Area
bar-chart / bar / bar-x-axis / bar-y-axis	BarChart / Bar / BarXAxis / BarYAxis
sparkline	LineSparkline、AreaSparkline、BarSparkline、useSparklineHover
composed-chart / series-bar	ComposedChart / SeriesBar（以及各自图表中的 Line、Area）
scatter-chart	ScatterChart、Scatter
candlestick-chart / candlestick	CandlestickChart / Candlestick
live-line-chart / live-line / live-x-axis / live-y-axis	LiveLineChart / LiveLine / LiveXAxis / LiveYAxis
pie-chart / pie-slice / pie-center	PieChart / PieSlice / PieCenter
ring-chart / ring / ring-center	RingChart / Ring / RingCenter
radar-chart、radar-grid、radar-axis、radar-labels、radar-area	各导出一个组件
gauge	Gauge（由 @bklit/gauge-chart 安装）
funnel-chart	FunnelChart
sunburst-chart、sunburst-segment、sunburst-center、sunburst（buildArcs）…	sunburst 组件
heatmap · choropleth · sankey	文件夹的 index.ts 会重新导出所有组件
grid · x-axis · y-axis · background · reference-area · projection-line · trend-line	Grid · XAxis · YAxis · Background · ReferenceArea · ProjectionLine · TrendLine
band · bollinger	Band · withBollingerBands（由 @bklit/line-chart 安装，也可由 @bklit/band 安装）
weekends · deadline	Weekends · Deadline（日期坐标轴底纹和截止日期标记）
tooltip · legend · markers · patterns	文件夹的 index.ts（ChartTooltip、Legend*、ChartMarkers、Pattern*）
chart-context	chartCssVars、useChart、TooltipData

import { LineChart, Line } from "@/components/charts/line-chart";
import { Grid } from "@/components/charts/grid";
import { XAxis } from "@/components/charts/x-axis";
import { ChartTooltip } from "@/components/charts/tooltip";
import { chartCssVars } from "@/components/charts/chart-context";

关键规则

组合 → composition.md

• 系列、坐标轴、叠加层和 ChartTooltip 都是根图表的子元素——它们会读取图表上下文。
• **每个图表只能有一个根组件。**日期上的柱形 + 折线混合图 → 使用 ComposedChart 和 SeriesBar（而非 Bar）。
• 先放置 Grid（或 Background），这样系列会绘制在其上方。
• 实时图表使用 LiveLine、LiveXAxis、LiveYAxis——而不是 Line/XAxis。
• BarChart 使用 BarXAxis / BarYAxis（带状比例尺），而不是 XAxis。

主题 → theming.md

• 系列使用 --chart-1 … --chart-5；语义角色使用 chartCssVars.linePrimary 等变量。
• 注册表会添加缺失的 --chart-* 令牌，不会覆盖应用已有的令牌。
• 在 :root / .dark 中覆盖令牌；不要在图表 SVG 上使用 dark: 类。

工具提示 → tooltips.md

• ChartTooltip 的 content 接收 ({ point, index })；rows 返回 { color, label, value }[]。
• indicatorColor 可以是字符串，也可以是 (point) => string。
• 自定义十字线/指示器使用 useChart()——不要使用全局鼠标监听器。

迷你图（@bklit/sparkline）

• LineSparkline / AreaSparkline / BarSparkline 都是单个元素——只需 data 和 dataKey，不需要子元素。不要用带隐藏坐标轴的 LineChart 来构建迷你图。
• 省略 width 即可填满父元素；height 默认值为 32。color、curve（默认值为 "monotone"）、strokeWidth、endDot；面积图支持 fill="gradient" | "solid" + fillOpacity；柱状图支持 barGap、barRadius。
• **设计上不提供工具提示。**使用 const hover = useSparklineHover<Row>()，展开 hover.sparklineProps（可用于多个迷你图，以同步十字线），并自行渲染 hover.datum ?? latest。crosshair（默认值为 "dashed"，还可设为 "solid"、"gradient" 或 false）、dot、interactive={false}。悬停时，系列会淡出，并像主图表一样重新描绘悬停的线段（showHighlight、inactiveOpacity 设为 0.5；柱状图会将未聚焦的柱形淡化至 0.4）。十字线和点会在数据点之间平滑移动（设置 hoverTransition={false} 可立即跳转，使用 springConfig 可调整效果），新 data 会在 dataTransitionDuration 期间（500ms；设为 0 可立即跳转）平滑过渡。减少动态效果时，两者都会立即跳转。
• 默认启用入场动画（animate，900ms）；减少动态效果时会改用淡入动画。

叠加层 → overlays.md

• ChartMarkers 是 ChartTooltip 的同级元素；标记的悬停内容应放在 ChartTooltip 子元素中。
• ChartBrush 没有注册表条目——不要承诺提供 @bklit/brush。
• TrendLine（@bklit/trend-line）会拟合现有系列的 dataKey；将其放在该系列之后（折线、面积图、柱状图〔包括横向柱状图〕、组合图）。

动画和加载 → animation.md、loading.md

• 默认入场动画：1100ms，缓动为 cubic-bezier(0.85, 0, 0.15, 1)；柱形会在该时长约 40% 的范围内依次出现。
• 使用 revealSignature 或新的 key 重新播放。
• 在 LineChart / AreaChart / BarChart / HeatmapChart 上设置 status="loading"——使用同一个实例，不要替换组件。
• 内部仅部分处理减少动态效果的设置——详见 animation.md。

安装 → installation.md

• 让 shadcn add 安装 npm 依赖和 @bklit/* 注册表依赖；不要手动固定 @visx/* 版本。
• 不要将 *-example 条目安装到现有应用中——它们会写入 app/page.tsx。

目录

所有条目均可通过 npx shadcn@latest add @bklit/<item> 安装。对于任意 <item>：

• 文档：https://bklit.com/docs/components/<item>（扩展项位于 https://bklit.com/docs/utility/… 下，例如 /tooltip、/legend、/axis/y-axis）
• 图库：https://bklit.com/charts/<item> · Studio（调整属性、复制代码）：https://bklit.com/studio?chart=<item>
• 注册表 JSON：https://ui.bklit.com/r/<item>.json

图表

项目	适用场景
line-chart	时间序列、多线趋势、标记、虚线尾部
area-chart	带填充区域的趋势、渐变／图案填充
sparkline	用于表格单元格、KPI 和统计卡片、密集网格中的迷你行内折线／面积／柱形趋势图——无坐标轴、网格或工具提示；使用 useSparklineHover 读取悬停值
bar-chart	类别对比；分组、堆叠、水平、方形柱形条
composed-chart	在同一日期轴上显示柱形条 + 折线／面积，支持双 Y 轴
live-line-chart	流式／实时值（{ time: unixSeconds, value }）
scatter-chart	随时间变化的点云、多数据系列
candlestick-chart	OHLC 金融数据
profit-loss-line	穿过零点的单数据系列，按正负值着色（也有对应的 Studio slug）
pie-chart	部分占整体的切片，可选中心统计值
ring-chart	同心进度环／圆环 KPI
radar-chart	跨实体的多指标对比
gauge-chart	单个 0–100 数值，可使用弧形或带刻度的线性轨道
heatmap-chart	日历／贡献网格、分箱强度
funnel-chart	阶段间转化
sankey-chart	节点间流动
sunburst-chart	支持下钻的层级部分占整体图
choropleth-chart	按数值为地理区域着色（世界／国家地图）

附加组件（大多数会自动作为依赖安装）

grid、x-axis、y-axis（line／area 不会引入此项——需要数值轴时请添加）、chart-tooltip、legend、markers、background、patterns、reference-area、projection-line、trend-line（用于 line／area／bar／composed 的最小二乘趋势叠加）、band（LineChart 上的范围／布林带；已包含在 line-chart 中）、bar-depth（BarChart 上的 3D／凸起柱形条）、chart-stat-flow（用于饼图／圆环图／仪表盘中心和统计卡片的动画统计数值）。内部基础组件（chart-context、chart-animation、chart-series、chart-utils、chart-parent-size、utils、shimmering-text）会自动引入。

**Brush：**目前没有任何注册项包含 ChartBrush / ChartBrushLayout（文档：/docs/utility/brush）。如果用户需要 Brush 缩放，请告知并指向文档／源码，不要编造安装命令。

区块（统计卡片；可在 https://bklit.com/blocks 浏览）

项目	内容
stat-card-area-01	收入卡片：AreaSparkline（渐变）、悬停读取数值、NumberFlow、趋势徽标
stat-card-line-01	会话卡片：带叠加数值的 LineSparkline、悬停读取数值、趋势徽标
stat-card-choropleth-01	访客卡片：等值区域迷你地图、趋势徽标

面积图和折线图卡片基于 @bklit/sparkline（作为依赖安装），并使用 useSparklineHover 将标题数值替换为悬停值。在表格行或自定义卡片中使用迷你趋势图时，请直接组合 @bklit/sparkline，而不要安装区块。

区块需要 shadcn card + badge，请将示例数据写在 data/ 下，并从它们创建的 @/components/charts 汇总导出文件（components/charts/index.ts）导入。安装第二个区块会覆盖该汇总导出文件和共享文件（stat-card-chart.tsx、stat-card-sparkline-hover.ts、trend-badge.tsx）——请手动合并。

工作流

1. 获取项目上下文（上方注入的内容或 npx shadcn@latest info --json）；确认已配置 @bklit。
2. 根据数据所讲述的内容，从目录中选择项目；如不明确，请先询问。
3. 安装：npx shadcn@latest add @bklit/<item>（如有需要，还需添加 @bklit/y-axis、@bklit/legend 等）。
4. 阅读已安装的源码（CLI 刚写入 components/charts/ 的文件）——确认导出项、属性名称、默认值和数据形状。如果源码与记忆或文档不一致，优先以源码为准。
5. 按 root → grid → series → axes → overlays → tooltip 的顺序组合；使用项目别名从已安装的路径导入。
6. 使用 tokens 设置主题；检查浅色和深色模式。
7. 向用户提供 gallery / Studio URL，供其查看不同变体。

快速参考

npx shadcn@latest info --json
npx shadcn@latest add @bklit/line-chart @bklit/y-axis
npx shadcn@latest view @bklit/line-chart     # inspect files before installing

"use client";

import { ChartTooltip } from "@/components/charts/tooltip";
import { Grid } from "@/components/charts/grid";
import { Line, LineChart } from "@/components/charts/line-chart";
import { XAxis } from "@/components/charts/x-axis";

const data = [
  { date: new Date("2025-01-01"), users: 1200, sessions: 1800 },
  { date: new Date("2025-02-01"), users: 1350, sessions: 1950 },
];

export function UsersChart() {
  return (
    <LineChart data={data}>
      <Grid horizontal />
      <Line dataKey="users" stroke="var(--chart-1)" />
      <Line dataKey="sessions" stroke="var(--chart-2)" />
      <XAxis />
      <ChartTooltip />
    </LineChart>
  );
}

相关技能

• bklit-ui-design — 设计词汇与方案：图案和纹理、圆角超椭圆／圆角／3D 柱、边缘渐隐、渐变、加载样式，以及使图表与应用主题相匹配。当请求涉及图表的外观时使用。
• bklit-ui-migrate — 将 Recharts、shadcn ChartContainer / ChartConfig 或 TanStack Charts（@tanstack/charts）图表迁移为 Bklit 对应实现，包括将微型图表转换为迷你图。

使用 npx skills add bklit/bklit-ui 安装全部三项。

参考资料

• composition.md — 结构、数据形状、多系列
• theming.md — 令牌、chartCssVars、深色模式
• tooltips.md — ChartTooltip 属性、自定义内容、useChart
• overlays.md — 图例、标记、参考区域、投影、趋势线、背景、刷选器
• animation.md — 进入动画时序、重播、实时图表、减少动态效果
• loading.md — status、骨架屏、加载标签
• installation.md — 注册表设置、文件布局、依赖项