bklit-studio-chart-performance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Studio chart performance

Studio 图表性能

Use when a chart feels sluggish in Studio but similar charts (e.g. pie-chart) are fine.

当Studio中的图表运行卡顿，但同类图表（如饼图）运行正常时使用本方案。

One-line rule

一句话准则

Keep enter animation on paths if you need it, then drop Motion path subscriptions and isolate hover so Studio slider and legend updates don't replay expensive arc/path math across every series every frame.

如果需要路径的入场动画，请保留该动画，然后移除Motion路径订阅并隔离悬停逻辑，这样Studio滑块和图例更新时，就不会在每一帧都对所有系列重复执行高开销的圆弧/路径计算。

1. Find what re-renders on every interaction

1. 找出每次交互时会重新渲染的内容

Studio updates

displayState

on every slider tick and on legend/slice hover. Trace:

Does hover live in the same context as data, scales, and animation config?
Does the preview recreate children (
```
data.map
```
, pattern defs, motion props) every render?
Does the chart remount unnecessarily (
```
key
```
tied to motion signature vs manual replay)?

Pattern: Split context like cartesian / pie charts — stable slice (data, geometry, animation config) vs hover slice (

hoveredIndex

, tooltip). Consumers that don't need hover use only the stable hook (

usePieStable

useRingStable

useChartStable

, …).

Studio pan: Wrap chart render in

StudioChartRender

(

packages/studio/src/components/studio-chart-render.tsx

) so camera pan / FPS counter parent updates skip the chart tree when render props are unchanged.

Studio会在每次滑块刻度变化、图例/切片悬停时更新

displayState

。排查方向：

悬停逻辑是否与数据、比例尺、动画配置处于同一上下文？
预览是否会在每次渲染时重新创建子组件（
```
data.map
```
、图案定义、motion属性）？
图表是否会不必要地重新挂载（
```
key
```
绑定到motion签名而非手动重放）？

模式： 像笛卡尔图/饼图那样拆分上下文 —— 稳定切片（数据、几何形状、动画配置） vs 悬停切片（

hoveredIndex

、提示框）。不需要悬停功能的消费者仅使用稳定钩子（

usePieStable

、

useRingStable

、

useChartStable

等）。

Studio平移： 将图表渲染包裹在

StudioChartRender

（

packages/studio/src/components/studio-chart-render.tsx

）中，这样相机平移/FPS计数器父组件更新时，若渲染属性未变化，就会跳过图表树的更新。

2. Treat SVG path

animation as expensive

2. 视SVG路径

动画为高开销操作

Animating

with Motion /

useTransform

+ d3 arc (or similar) runs layout + paint every frame, per series.

Prefer	Avoid
`transform` / `opacity` for hover (compositor-friendly)	Continuous `d` morphing after enter is done
Static `d` once enter finishes	Keeping Motion subscriptions on `d` for the chart's lifetime
Enter animation only, then static paths	Re-running enter path math on unrelated prop changes

Pattern:

useMountProgress

for enter → when progress ≥ 1 (

useEnterComplete

), render static paths and only animate hover with

opacity

scale

on a motion.g
wrapper (not per-path

scale

motion.path

Shared hook:

packages/ui/src/charts/use-enter-complete.ts

使用Motion /

useTransform

+ d3 arc（或类似工具）对

属性进行动画，会在每一帧对每个系列执行布局+绘制操作。

推荐方案	避免操作
使用 `transform` / `opacity` 实现悬停（合成器友好）	入场完成后持续对 `d` 属性进行变形动画
入场完成后使用静态 `d` 属性	在图表生命周期内保持对 `d` 属性的Motion订阅
仅保留入场动画，之后使用静态路径	在无关属性变化时重新执行入场路径计算

模式： 使用

useMountProgress

处理入场动画 → 当进度≥1时（通过

useEnterComplete

判断），渲染静态路径，并仅在**

motion.g

**容器上使用

opacity

scale

实现悬停动画（而非在每个

motion.path

上单独设置

scale

）。

共享钩子：

packages/ui/src/charts/use-enter-complete.ts

3. Memoize chart shell context

3. 记忆化图表外壳上下文

Unmemoized provider values force all children to reconcile on every parent render.

Memoize the stable context object with explicit deps (data, arcs/radii, dimensions, callbacks).
Memoize hover context on
```
hoveredIndex
```
+ stable
```
setHoveredIndex
```
(
```
useCallback
```
in chart shell).
Match isLoaded
to ring/cartesian:
```
useEffect
```
+ timeout, not a lazy
```
useState
```
initializer.

Reference:

pie-context.tsx

ring-context.tsx

chart-context.tsx

PieChartCore

RingChartCore

useMemo

on provider value.

未记忆化的提供者值会强制所有子组件在每次父组件渲染时重新协调。

使用显式依赖项（数据、圆弧/半径、尺寸、回调）记忆化稳定上下文对象。
基于
```
hoveredIndex
```
和稳定的
```
setHoveredIndex
```
（图表外壳中的
```
useCallback
```
）记忆化悬停上下文。
匹配环形图/笛卡尔图的**
```
isLoaded
```
**逻辑：使用
```
useEffect
```
+ 超时，而非惰性
```
useState
```
初始化器。

参考实现：

pie-context.tsx

、

ring-context.tsx

、

chart-context.tsx

、

PieChartCore

RingChartCore

中对提供者值使用

useMemo

。

4. Studio preview–specific wins

4. Studio预览专属优化技巧

Chart-agnostic; apply in

packages/studio/src/components/charts/*-studio*.tsx

Win	How
Conditional defs	Only pass `patternDefs` / gradients when a series uses patterns
Memo derived data	Colored/mapped data arrays; slice/series lists ( `useMemo` , deps: `dataSeed` + design fields that affect color)
Memo motion enter	Don't call `getStudioMotionEnterProps` inline; `useMemo` with motion-only deps (not full `state` )
Memo legend hover	`{ hoveredIndex, setHoveredIndex }` in `useMemo` — already in `studio-legend-hover.tsx`
Memo chart body	`memo()` wrapper; pass primitives ( `chartKey` , `chartSize` , `data` ) not whole `ctx` so pan/shell re-renders skip rebuild
Disable glow in Studio	`showGlow={false}` on series components

Reference:

pie-studio-preview.tsx

ring-studio-preview.tsx

与图表类型无关；可在

packages/studio/src/components/charts/*-studio*.tsx

中应用：

优化点	实现方式
条件式定义	仅当系列使用图案时才传递 `patternDefs` / 渐变
记忆化衍生数据	着色/映射后的数数组、切片/系列列表（使用 `useMemo` ，依赖项： `dataSeed` + 影响颜色的设计字段）
记忆化motion入场属性	不要内联调用 `getStudioMotionEnterProps` ；使用仅与motion相关的依赖项（而非完整 `state` ）通过 `useMemo` 处理
记忆化图例悬停	在 `useMemo` 中处理 `{ hoveredIndex, setHoveredIndex }` —— `studio-legend-hover.tsx` 中已实现
记忆化图表主体	使用 `memo()` 包装；传递原始类型值（ `chartKey` 、 `chartSize` 、 `data` ）而非完整 `ctx` ，这样平移/外壳重新渲染时会跳过重建
在Studio中禁用发光效果	在系列组件上设置 `showGlow={false}`

参考实现：

pie-studio-preview.tsx

、

ring-studio-preview.tsx

5. Compare against a “fast” sibling in Studio

5. 与Studio中“性能优异”的同类图表对比

Diff the slow chart against one that feels smooth in the same editor (usually pie-chart):

Check	Slow chart often has	Fast chart often has
Shell	Inline render, extra defs	`StudioChartShell` + conditional patterns
Series count	Many animated paths	Fewer paths or simpler geometry
Hover	Context + full tree re-render	Stable subscribers; hover on `motion.g` / translate
Enter	Path `d` wipe per series	Static `d` after enter; transform-only hover
Pan	Chart tree rebuilds every frame	`StudioChartRender` memo boundary

将卡顿的图表与同一编辑器中运行流畅的图表（通常是饼图）进行对比：

检查项	卡顿图表通常存在的问题	流畅图表通常具备的特征
外壳	内联渲染、冗余定义	`StudioChartShell` + 条件式图案
系列数量	大量带动画的路径	路径更少或几何形状更简单
悬停	上下文触发整树重新渲染	稳定的订阅者；在 `motion.g` / 平移上实现悬停
入场动画	每个系列都有路径 `d` 擦除动画	入场后使用静态 `d` ；仅通过变换实现悬停
平移	图表树每帧都重建	`StudioChartRender` 记忆化边界

6. Validation bar

6. 验证标准

Before opening a PR:

bash

pnpm lint
pnpm --filter @bklitui/ui check-types
pnpm --filter @bklitui/studio check-types

提交PR前需执行：

bash

pnpm lint
pnpm --filter @bklitui/ui check-types
pnpm --filter @bklitui/studio check-types

scoped production build when touching studio/web

当修改studio/web时，执行限定范围的生产构建


Manual `/studio?chart=<slug>`:

- [ ] Enter animation
- [ ] Hover / legend sync
- [ ] Drag geometry sliders (no unnecessary remount)
- [ ] Canvas pan (space + drag) after enter — FPS near pie-chart baseline
- [ ] Pattern/gradient mode if supported

---


手动访问`/studio?chart=<slug>`验证：

- [ ] 入场动画正常
- [ ] 悬停/图例同步正常
- [ ] 拖动几何形状滑块（无不必要的重新挂载）
- [ ] 入场完成后画布平移（空格+拖动）—— FPS接近饼图基准
- [ ] 若支持图案/渐变模式，需验证该模式正常

---

Chart status (bklit-ui)

图表状态（bklit-ui）

Chart	Slug	Status
Pie	`pie-chart`	✅ Reference (#120)
Ring	`ring-chart`	✅ Aligned to checklist (context split, static paths, `StudioChartRender` , preview memo)
Radar / Funnel / Choropleth	various	Partial — run checklist
Cartesian / scatter / live-line	various	✅ #91 decimation + hover batching
Sankey	`sankey-chart`	`useTransform` on link stroke — candidate for `useEnterComplete`
Gauge	`gauge-chart`	Low priority (single arc)

图表	Slug	状态
饼图	`pie-chart`	✅ 参考实现（#120）
环形图	`ring-chart`	✅ 符合检查清单（上下文拆分、静态路径、 `StudioChartRender` 、预览记忆化）
雷达图/漏斗图/分级统计图	多种	部分完成 —— 执行检查清单
笛卡尔图/散点图/实时折线图	多种	✅ #91 降采样 + 悬停批处理
桑基图	`sankey-chart`	在链接描边上使用 `useTransform` —— 适合应用 `useEnterComplete`
仪表盘	`gauge-chart`	低优先级（仅单个圆弧）

Key files

关键文件

Area	Path
Enter-complete hook	`packages/ui/src/charts/use-enter-complete.ts`
Pie reference	`packages/ui/src/charts/pie-slice.tsx` , `pie-context.tsx` , `pie-studio-preview.tsx`
Ring	`packages/ui/src/charts/ring.tsx` , `ring-chart.tsx` , `ring-studio-preview.tsx`
Pan isolation	`packages/studio/src/components/studio-chart-render.tsx`
Registry	`packages/studio/src/lib/registry.tsx`

领域	路径
入场完成钩子	`packages/ui/src/charts/use-enter-complete.ts`
饼图参考实现	`packages/ui/src/charts/pie-slice.tsx` , `pie-context.tsx` , `pie-studio-preview.tsx`
环形图	`packages/ui/src/charts/ring.tsx` , `ring-chart.tsx` , `ring-studio-preview.tsx`
平移隔离	`packages/studio/src/components/studio-chart-render.tsx`
注册表	`packages/studio/src/lib/registry.tsx`

bklit-studio-chart-performance

Original

Translation

Studio chart performance

Studio 图表性能

One-line rule

一句话准则

1. Find what re-renders on every interaction

1. 找出每次交互时会重新渲染的内容

2. Treat SVG path
`d`
animation as expensive

2. 视SVG路径
`d`
动画为高开销操作

3. Memoize chart shell context

3. 记忆化图表外壳上下文

4. Studio preview–specific wins

4. Studio预览专属优化技巧

5. Compare against a “fast” sibling in Studio

5. 与Studio中“性能优异”的同类图表对比

6. Validation bar

6. 验证标准

scoped production build when touching studio/web

当修改studio/web时，执行限定范围的生产构建

Chart status (bklit-ui)

图表状态（bklit-ui）

Key files

关键文件

bklit-studio-chart-performance

Original

Translation

Studio chart performance

Studio 图表性能

One-line rule

一句话准则

1. Find what re-renders on every interaction

1. 找出每次交互时会重新渲染的内容

2. Treat SVG path d animation as expensive

2. 视SVG路径d动画为高开销操作

3. Memoize chart shell context

3. 记忆化图表外壳上下文

4. Studio preview–specific wins

4. Studio预览专属优化技巧

5. Compare against a “fast” sibling in Studio

5. 与Studio中“性能优异”的同类图表对比

6. Validation bar

6. 验证标准

scoped production build when touching studio/web

当修改studio/web时，执行限定范围的生产构建

Chart status (bklit-ui)

图表状态（bklit-ui）

Key files

关键文件

2. Treat SVG path
`d`
animation as expensive

2. 视SVG路径
`d`
动画为高开销操作