graphy-charts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

graphy-charts

Graphy图表

Build charts with @graphysdk/react
— one package carrying the whole stack: the spec builders,

<GraphProvider>

<GraphRenderer>

, and the hooks. Under the hood it composes

@graphysdk/viz-engine

(a grammar-of-graphics compiler, framework-agnostic) and

@graphysdk/react-renderer

(paints the compiled output to SVG/DOM in React); install those two directly only for advanced embedding — see "Related packages" in

reference/react-api.md

使用**

@graphysdk/react

**构建图表——这是一个集成了完整技术栈的包：规范构建器、

<GraphProvider>

<GraphRenderer>

以及钩子函数。其底层由

@graphysdk/viz-engine

（一款与框架无关的图形语法编译器）和

@graphysdk/react-renderer

（在React中将编译结果渲染为SVG/DOM）组成；仅在需要高级嵌入场景时才直接安装这两个包——详见

reference/react-api.md

中的“相关包”部分。

Mental model

核心思路

The engine is a grammar of graphics in the ggplot2 / Vega-Lite tradition. You do not pick a chart type from a menu; you compose one from orthogonal primitives:

A layer = a geom (mark kind:
```
point
```
,
```
line
```
,
```
area
```
,
```
bar
```
,
```
rule
```
,
```
tile
```
) + an aesthetic mapping (data variable → visual channel) + a stat (per-layer reshape:
```
count
```
,
```
sum
```
,
```
mean
```
,
```
smooth
```
) + a position adjuster (
```
identity
```
,
```
stack
```
,
```
dodge
```
,
```
fill
```
).
Chart types are compositions: a pie chart is
```
bar
```
+
```
position: 'fill'
```
+
```
coord.polar({ theta: 'y' })
```
; a donut adds
```
innerRadius
```
; a horizontal bar chart is
```
coord.flip()
```
; a radar chart is
```
line
```
/
```
area
```
+
```
coord.polar({ theta: 'x' })
```
.
A reference line is
```
geom.rule()
```
. A trendline is
```
stat.smooth
```
. An average line is
```
stat.mean
```
.
Transforms reshape data declaratively inside the spec:
```
transform.filter
```
,
```
transform.sort
```
,
```
transform.aggregate
```
,
```
transform.reshape
```
(wide→long),
```
transform.constant
```
. Prefer them over preprocessing
```
rows
```
with vanilla JS. Full option tables in
```
reference/spec-api.md
```
.
Scales map data to visual values; guides (axes, legends, headline numbers) make scales legible. Calling
```
scale.x()
```
/
```
scale.y()
```
with no arguments infers the scale type from the data. Add a scale for every mapped positional aesthetic;
```
color
```
gets a default palette scale automatically.
A stylesheet (
```
styles({ tokens, defaults, overrides })
```
) is a spec item like any other and owns all paint: mark fill/border/stroke/size, grid and tick lines, panel border, graph background, label typography (
```
reference/styling.md
```
).
Highlights (predicate-driven emphasis) and annotations (arrows, text, shapes, images, …) are spec-level and serializable — the storytelling layer.

Data flows one way: raw

Data

→ resolved

Spec

(defaults applied, types inferred, the authored stylesheet folded onto the built-in one) →

CompiledSpec

(render-ready, paint resolved per observation) → painted React output. You author the first step; the rest is automatic.

该引擎遵循ggplot2 / Vega-Lite传统的图形语法。你无需从菜单中选择图表类型，而是通过独立的基础元素组合出所需图表：

图层 = geom（标记类型：
```
point
```
、
```
line
```
、
```
area
```
、
```
bar
```
、
```
rule
```
、
```
tile
```
） + 美学映射（数据变量 → 视觉通道） + stat（图层级数据重塑：
```
count
```
、
```
sum
```
、
```
mean
```
、
```
smooth
```
） + 位置调整器（
```
identity
```
、
```
stack
```
、
```
dodge
```
、
```
fill
```
）。
图表类型是组合而来的：饼图是
```
bar
```
+
```
position: 'fill'
```
+
```
coord.polar({ theta: 'y' })
```
；环形图在此基础上添加
```
innerRadius
```
；水平条形图是
```
coord.flip()
```
；雷达图是
```
line
```
/
```
area
```
+
```
coord.polar({ theta: 'x' })
```
。
参考线由
```
geom.rule()
```
实现。趋势线是
```
stat.smooth
```
。平均线是
```
stat.mean
```
。
Transforms在规范中声明式地重塑数据：
```
transform.filter
```
、
```
transform.sort
```
、
```
transform.aggregate
```
、
```
transform.reshape
```
（宽表→长表）、
```
transform.constant
```
。优先使用这些方法，而非通过原生JS预处理
```
rows
```
。完整选项表见
```
reference/spec-api.md
```
。
Scales将数据映射为视觉值；guides（坐标轴、图例、标题数字）让刻度更易读。调用无参数的
```
scale.x()
```
/
```
scale.y()
```
会根据数据自动推断刻度类型。为每个映射的位置美学添加一个刻度；
```
color
```
会自动使用默认调色板刻度。
样式表（
```
styles({ tokens, defaults, overrides })
```
）是规范中的一项内容，负责所有绘制样式：标记的填充/边框/描边/大小、网格和刻度线、面板边框、图表背景、标签排版（详见
```
reference/styling.md
```
）。
高亮（基于断言的强调）和注释（箭头、文本、形状、图像等）属于规范层面且可序列化——这是图表的叙事层。

数据单向流动：原始

Data

→ 解析后的

Spec

（应用默认值、推断类型、将自定义样式表与内置样式表合并） →

CompiledSpec

（可渲染状态，为每个数据点解析绘制样式） → 渲染后的React输出。你只需完成第一步，其余步骤自动执行。

Minimal chart

最简示例

tsx

import { createSpec, pipe, mapping, geom, scale, GraphProvider, GraphRenderer } from '@graphysdk/react';

const data = {
  columns: [{ key: 'month' }, { key: 'revenue' }],
  rows: [
    { month: 'Jan', revenue: 1200 },
    { month: 'Feb', revenue: 1850 },
    { month: 'Mar', revenue: 1600 },
  ],
};

const input = pipe(createSpec(), mapping({ x: 'month', y: 'revenue' }), geom.bar(), scale.x(), scale.y());

export function RevenueChart() {
  return (
    <GraphProvider data={data} input={input}>
      <GraphRenderer />
    </GraphProvider>
  );
}

This assumes the SDK is installed from npm and built by a bundler (

reference/install.md

). The same chart also runs on a plain HTML page with no bundler, loading the SDK from a CDN URL — only the imports change (

reference/cdn.md

Reference and recipe samples import from the underlying packages (

@graphysdk/viz-engine

@graphysdk/react-renderer

). With the standard

@graphysdk/react

install, every one of those names comes from

'@graphysdk/react'

instead — only the specifier changes.

tsx

import { createSpec, pipe, mapping, geom, scale, GraphProvider, GraphRenderer } from '@graphysdk/react';

const data = {
  columns: [{ key: 'month' }, { key: 'revenue' }],
  rows: [
    { month: 'Jan', revenue: 1200 },
    { month: 'Feb', revenue: 1850 },
    { month: 'Mar', revenue: 1600 },
  ],
};

const input = pipe(createSpec(), mapping({ x: 'month', y: 'revenue' }), geom.bar(), scale.x(), scale.y());

export function RevenueChart() {
  return (
    <GraphProvider data={data} input={input}>
      <GraphRenderer />
    </GraphProvider>
  );
}

此示例假设已从npm安装SDK并通过打包工具构建（详见

reference/install.md

）。同样的图表也可以在无打包工具的纯HTML页面上运行，只需从CDN URL加载SDK——仅需修改导入方式（详见

reference/cdn.md

）。

参考文档和示例代码会从底层包（

@graphysdk/viz-engine

、

@graphysdk/react-renderer

）导入内容。在标准

@graphysdk/react

安装方式下，所有这些导出符号都来自

'@graphysdk/react'

——仅需修改导入路径即可。

The expressiveness ladder

表现力层级

Spec +
config()
— chart structure and chart-level options: layers, scales, coords, legend/axes settings, titles, headline numbers, number formats, layout.
Stylesheet — pipe
```
styles({ ... })
```
into the spec to repaint anything the chart itself draws: mark fill/border/stroke/size, grid and tick lines, panel border, graph background, axis/tick/data-label typography. Predicate- and state-aware, serializable. This is the primary restyling tier —
```
reference/styling.md
```
.
Theme tokens — pass
```
themeOverrides
```
to
```
GraphProvider
```
for the HTML chrome around the plot only: legend, tooltip, headline, footer, default font family. React-only, not serializable.
Slots — replace whole regions (header, footer, tooltip, legend, grid, axis ticks, swatch) with your own React components via the
```
slots
```
prop on
```
GraphRenderer
```
.
Plugins — change how marks are painted (render-only override of a built-in geom) or add entirely new geoms/stats/transforms (
```
defineGeomRenderer
```
,
```
createGraphyKit
```
).

See

recipes/themes/

for complete worked examples at each tier.

Spec +
config()
—— 图表结构和图表级选项：图层、刻度、坐标系、图例/坐标轴设置、标题、标题数字、数字格式、布局。
样式表 —— 在规范中引入
```
styles({ ... })
```
以重绘图表绘制的所有元素：标记的填充/边框/描边/大小、网格和刻度线、面板边框、图表背景、坐标轴/刻度/数据标签的排版。支持断言和状态感知，可序列化。这是主要的样式调整层级——详见
```
reference/styling.md
```
。
主题令牌 —— 向
```
GraphProvider
```
传递
```
themeOverrides
```
，仅用于调整图表周围的HTML控件样式：图例、提示框、标题、页脚、默认字体。仅支持React，不可序列化。
插槽 —— 通过
```
GraphRenderer
```
的
```
slots
```
属性，使用自定义React组件替换整个区域（页眉、页脚、提示框、图例、网格、坐标轴刻度、样本块）。
插件 —— 修改标记的绘制方式（仅重写内置geom的渲染逻辑）或添加全新的geom/stat/transform（
```
defineGeomRenderer
```
、
```
createGraphyKit
```
）。

每个层级的完整示例见

recipes/themes/

目录。

Where to look

参考指引

Route by the intent of the request, not only the chart type it names. Comparative and narrative phrasing — "compare this with that", "show the increase", "call out the dip", "what changed since X" — is the storytelling layer (

reference/storytelling.md

I want to…	Read
Install the SDK, or fix a failed install (peer errors, unstyled graph, missing types)	`reference/install.md`
Use the SDK on a page with no bundler or npm ( `<script type="module">` , jsDelivr)	`reference/cdn.md`
See the full spec builder API and every `config()` key	`reference/spec-api.md`
Check the exact signature, option keys, or accepted values of an exported symbol	`reference/types.md`
Filter, sort, aggregate or derive data inside the spec ( `transform.*` )	`reference/spec-api.md`
Understand the `Data` format, parsing, value formats, wide→long reshape	`reference/data.md`
Render in React: provider/renderer props, sizing, locales, error handling	`reference/react-api.md`
Recolor geoms; restyle grid, tick lines, panel border, graph background, label typography	`reference/styling.md`
Restyle the legend, tooltip, headline and footer chrome via theme tokens	`reference/theming.md`
Replace the header, footer, tooltip, legend, grid, or axis ticks	`reference/slots.md`
Annotate, highlight, add reference lines/trendlines/headline numbers/data labels	`reference/storytelling.md`
Compare two values or periods, show a change/gap/drop (difference arrows)	`reference/storytelling.md`
Author plugins: repaint a built-in geom or define a new one	`reference/plugins.md`
Bar or column chart (grouped, stacked, 100%, horizontal, negative)	`recipes/charts/bar.md`
Line chart (multi-series, dash styles, smoothing, missing values)	`recipes/charts/line.md`
Area chart (stacked, flipped)	`recipes/charts/area.md`
Scatter or bubble chart	`recipes/charts/scatter.md`
Pie or donut chart	`recipes/charts/pie-donut.md`
Radar / spider chart	`recipes/charts/radar.md`
Rose or racetrack (polar bars)	`recipes/charts/polar-bar.md`
Combo chart, dual y-axes	`recipes/charts/combo.md`
Heatmap, matrix, cohort grid, waffle	`recipes/charts/heatmap.md`
Apply a complete house style	`recipes/themes/` — see the Themes section below
Repaint a built-in geom's marks	`recipes/plugins/sketchy-bar.md`
Minimal custom geom to model a new one after	`recipes/plugins/lollipop.md`
Custom geom with two marks per observation	`recipes/plugins/dumbbell.md`
Custom positional aesthetics (open/high/low/close)	`recipes/plugins/candlestick.md`
Custom layout + hit-testing geometry	`recipes/plugins/treemap.md` , `recipes/plugins/voronoi.md`
Simulation-driven or pointer-owning geoms	`recipes/plugins/beeswarm.md` , `recipes/plugins/force-directed.md`
Multi-part flow geometry	`recipes/plugins/sankey.md`
Check a spec compiles before rendering	`scripts/validate-spec.mjs` (module shape in its usage header)

根据需求意图查找文档，而非仅按图表类型查找。比较性和叙述性表述——“对比A与B”、“展示增长情况”、“突出下降点”、“自X以来的变化”——属于叙事层内容（详见

reference/storytelling.md

）。

我想要…	阅读文档
安装SDK，或修复安装失败问题（依赖错误、图表样式丢失、类型缺失）	`reference/install.md`
在无打包工具或npm的页面上使用SDK（ `<script type="module">` 、jsDelivr）	`reference/cdn.md`
查看完整的规范构建器API和所有 `config()` 配置项	`reference/spec-api.md`
检查导出符号的精确签名、选项键或接受值	`reference/types.md`
在规范中过滤、排序、聚合或派生数据（ `transform.*` ）	`reference/spec-api.md`
理解 `Data` 格式、解析、值格式、宽表→长表转换	`reference/data.md`
在React中渲染：provider/renderer属性、尺寸、本地化、错误处理	`reference/react-api.md`
重新为geom配色；调整网格、刻度线、面板边框、图表背景、标签排版样式	`reference/styling.md`
通过主题令牌调整图例、提示框、标题和页脚控件的样式	`reference/theming.md`
替换页眉、页脚、提示框、图例、网格或坐标轴刻度	`reference/slots.md`
添加注释、高亮、参考线/趋势线/标题数字/数据标签	`reference/storytelling.md`
比较两个值或时间段，展示变化/差距/下降（差异箭头）	`reference/storytelling.md`
编写插件：重绘内置geom或定义新geom	`reference/plugins.md`
条形图或柱状图（分组、堆叠、100%占比、水平、负值）	`recipes/charts/bar.md`
折线图（多系列、虚线样式、平滑处理、缺失值）	`recipes/charts/line.md`
面积图（堆叠、翻转）	`recipes/charts/area.md`
散点图或气泡图	`recipes/charts/scatter.md`
饼图或环形图	`recipes/charts/pie-donut.md`
雷达图 / 蛛网图	`recipes/charts/radar.md`
玫瑰图或跑道图（极坐标条形图）	`recipes/charts/polar-bar.md`
组合图表、双Y轴	`recipes/charts/combo.md`
热力图、矩阵图、同期群网格图、华夫饼图	`recipes/charts/heatmap.md`
应用完整的内部样式	`recipes/themes/` —— 见下方主题部分
重绘内置geom的标记	`recipes/plugins/sketchy-bar.md`
最简自定义geom（作为新geom的模板）	`recipes/plugins/lollipop.md`
每个数据点包含两个标记的自定义geom	`recipes/plugins/dumbbell.md`
自定义位置美学（开盘价/最高价/最低价/收盘价）	`recipes/plugins/candlestick.md`
自定义布局 + 点击测试几何图形	`recipes/plugins/treemap.md` 、 `recipes/plugins/voronoi.md`
模拟驱动或支持指针交互的geom	`recipes/plugins/beeswarm.md` 、 `recipes/plugins/force-directed.md`
多部分流几何图形	`recipes/plugins/sankey.md`
在渲染前验证规范是否可编译	`scripts/validate-spec.mjs` （使用说明见其头部的模块结构）

Themes

主题

Complete house styles ready to apply or adapt. Each file states its tier, then gives palette/font constants, the spec stylesheet, the

ThemeOverrides

for the surrounding chrome, a shared

config()

builder, and worked example specs. All are stylesheet + tokens + config unless noted.

Theme	Look	File
Braun	Dieter Rams minimalism: warm greys, ink pill bars, no grid, one orange accent	`recipes/themes/braun.md`
Financial Times	FT editorial: salmon paper, claret + Oxford blue, color-keyed headlines	`recipes/themes/financial-times.md`
International	Newspaper style: white plates, ink-and-grey series, one red accent	`recipes/themes/international.md`
Lenny's Newsletter	Warm newsletter: cream grounds, rounded corners, autumn orange ramp	`recipes/themes/lennys-newsletter.md`
Neo Brutalist	Near-black sheets, dashed borders, acid `#C8FF00` for data only	`recipes/themes/neo-brutalist.md`
Mexico 68	Olympic op-art: magenta-led palette, concentric outline marks (plugin tier)	`recipes/themes/mexico-68.md`

可直接应用或修改的完整内部样式。每个文件都会说明其所属层级，然后提供调色板/字体常量、规范样式表、用于周边控件的

ThemeOverrides

、共享的

config()

构建器，以及完整的示例规范。除非另有说明，所有主题均包含样式表 + 令牌 + 配置。

主题	风格	文件
Braun	Dieter Rams极简风格：暖灰色、墨色条形、无网格、橙色强调色	`recipes/themes/braun.md`
Financial Times	FT编辑风格：三文鱼色背景、深红色 + 牛津蓝、标题与颜色关联	`recipes/themes/financial-times.md`
International	报纸风格：白色面板、墨色与灰色系列、红色强调色	`recipes/themes/international.md`
Lenny's Newsletter	暖色调通讯风格：米色背景、圆角、秋橙色渐变	`recipes/themes/lennys-newsletter.md`
Neo Brutalist	近乎黑色背景、虚线边框、仅数据使用亮绿色 `#C8FF00`	`recipes/themes/neo-brutalist.md`
Mexico 68	奥运欧普艺术风格：洋红色主导调色板、同心轮廓标记（插件层级）	`recipes/themes/mexico-68.md`

Validating without rendering

无需渲染即可验证

The engine compiles without a DOM.

scripts/validate-spec.mjs

compiles a

{ data, input }

module headlessly and prints diagnostics — run it to check a spec before wiring it into React:

bash

node scripts/validate-spec.mjs path/to/my-spec.mjs

该引擎无需DOM即可编译。

scripts/validate-spec.mjs

可在无界面环境下编译

{ data, input }

模块并输出诊断信息——在将规范接入React前，可运行该脚本进行检查：

bash

node scripts/validate-spec.mjs path/to/my-spec.mjs

Hard rules

硬性规则

Mappings, transforms and aesthetics reference columns by
```
key
```
, never by
```
label
```
.
Every consumer must wrap
```
GraphRenderer
```
in a
```
GraphProvider
```
; the renderer has no standalone mode.
The
```
plugins
```
array on
```
GraphProvider
```
is frozen at mount — remount with a React
```
key
```
to change it.
Everything the chart draws — geoms, grid, tick lines, panel border, graph background, axis/tick/data-label type — is painted from the spec stylesheet (
```
styles
```
), varying per observation via
```
style.geom(decls, { where })
```
and per series via
```
{ layer }
```
.
```
themeOverrides
```
governs the surrounding HTML chrome: legend, tooltip, headline, footer.
Geom
```
params
```
merge without validation, so a key the geom does not declare is accepted and ignored. A declaration that has no visible effect is usually one the stylesheet should have carried.
Each entry point injects its own CSS; there is nothing to import. Editing lives behind the
```
@graphysdk/react-renderer/editable
```
entry point (
```
EditableGraphRenderer
```
,
```
EditorPanel
```
) —
```
mode="editable"
```
on a plain
```
GraphRenderer
```
renders no editor surface. Making charts editable, editing them programmatically, and the editor panel are the
```
graphy-editor
```
skill.

映射、转换和美学通过
```
key
```
引用列，绝不能通过
```
label
```
引用。
所有使用场景必须将
```
GraphRenderer
```
包裹在
```
GraphProvider
```
中；渲染器无独立模式。
```
GraphProvider
```
上的
```
plugins
```
数组在挂载时冻结——若要修改，需通过React
```
key
```
重新挂载组件。
图表绘制的所有元素——geom、网格、刻度线、面板边框、图表背景、坐标轴/刻度/数据标签样式——均由规范样式表（
```
styles
```
）控制，可通过
```
style.geom(decls, { where })
```
按数据点调整，或通过
```
{ layer }
```
按系列调整。
```
themeOverrides
```
仅控制周边HTML控件：图例、提示框、标题、页脚。
Geom的
```
params
```
会无验证地合并，因此geom未声明的键会被接受但忽略。无可见效果的声明通常应由样式表负责。
每个入口点会自行注入CSS；无需手动导入CSS。编辑功能位于
```
@graphysdk/react-renderer/editable
```
入口点（
```
EditableGraphRenderer
```
、
```
EditorPanel
```
）——普通
```
GraphRenderer
```
的
```
mode="editable"
```
不会渲染编辑界面。实现图表可编辑、程序化编辑以及编辑面板属于
```
graphy-editor
```
技能范畴。