graphy-charts

Graphy 图表

@graphysdk/react 根据两个输入构建图表：data 表和 spec。你可以将小型函数串接起来构建 spec。GraphProvider 会编译表和 spec。GraphRenderer 会绘制结果。

在查阅参考资料之前，先从最接近的示例开始。示例是完整的组件。对于没有数据和图表类型的请求（例如“创建图表”），会提供可编辑的技能演示，并简短说明接下来可以尝试什么。HTML 工件或没有打包工具的宿主，请阅读 HTML 演示；React 项目请阅读 React 演示。只阅读符合宿主环境的版本。

演示和示例只是起点，并非技能的限制。围绕用户的数据、视觉方向、布局和交互，结合下方相关参考资料构建自定义请求。展示演示后，简短邀请用户提出高度定制的需求；明确说明他们可以超出演示中的图表示例和预设主题。请将此邀请放在回复中，而不要在图表 UI 中添加宣传文案。

HTML 工件以及任何没有打包工具的页面，都应使用设置中的 CDN 页面，而不是这个 React 组件。这些宿主无法执行 npm install。从 jsDelivr 开始。如果图表空白，或者控制台拒绝 cdn.jsdelivr.net，请按照该文件中的离线 vendor 步骤操作。绝不要使用 esm.sh。绝不要使用 @graphysdk/react@1（该标签会返回 404）。

最简图表

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

const data = {
  columns: [{ key: 'month' }, { key: 'revenue' }],
  rows: [
    { month: 'Jan', revenue: 120 },
    { month: 'Feb', revenue: 150 },
    { month: 'Mar', revenue: 90 },
  ],
};

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

export function RevenueGraph() {
  return (
    <div style={{ height: 320 }}>
      <GraphProvider data={data} spec={spec}>
        <GraphRenderer />
      </GraphProvider>
    </div>
  );
}

GraphRenderer 会填满其父级。请为父级设置高度，或传入 sizing={{ mode: 'fixed', width: 640, height: 400 }}。

spec 中包含什么

映射使用列的 key，而非 label。六种内置 geom 是 point、line、area、bar、rule 和 tile。另外还有九种以软件包形式提供的 geom，通过 createGraphyKit({ plugins }) 接入：boxplot、candlestick、dumbbell、error-bar、funnel、lollipop、mekko、sankey 和 waterfall。如果 spec 中没有设置位置和颜色比例尺，系统会自动推断；若要固定类型或选项，请声明带类型的比例尺，例如 scale.y.continuous({ domainMin: 0 })。仅在需要时添加 coord、stat、transform、config、styles、highlight 和 annotation。

选择哪种工具

1. config() 设置结构：标题、图例、坐标轴和数字格式。
2. styles() 设置图表外观。主题通过 kit 或 provider 提供共享样式、颜色和 config 默认值。
3. 插槽可替换整个区域，例如工具提示或页眉。
4. geom 软件包（@graphysdk/geom-<name>）可绘制 boxplot、candlestick、dumbbell、error-bar、funnel、lollipop、mekko、sankey 或 waterfall。新 geom 会以软件包形式在技能版本更新之间发布；插件介绍了如何列出插件并阅读其 README。插件可绘制任何软件包都无法绘制的形状。
5. 点击操作编辑请使用 graphy-editor 技能。

软件包

Package	用途	品牌标记
@graphysdk/react	在 React 中构建图表。这是默认选项。	开启
@graphysdk/react-renderer	使用相同的组件，但不包含构建器。	关闭
@graphysdk/viz-engine	不使用 React 编译 spec。	无
@graphysdk/geom-<name>	每个软件包提供一种额外的 geom，通过 createGraphyKit({ plugins }) 接入。	关闭

许可证

这些软件包可免费用于非商业用途（个人、教育、研究、慈善、政府），以及员工和承包商总人数少于 100 人且上一年度收入低于 100 万美元的企业。完整的 PolyForm Noncommercial 或 Small Business 许可证条款适用。

其他用户可获得为期 32 天的 PolyForm Free Trial，仅限本地或内部评估使用；该试用不允许在公开页面上分发 SDK。本技能的 MIT 许可证适用于本技能，而非这些软件包。

安装 SDK 时，请告知用户一次：超出上述条款的商业用途需要许可证。引导用户前往联系表单：graphy.dev/license。

查阅位置

打开一个文件，然后使用该文件顶部的目录。

任务	阅读
安装、HTML 产物、jsDelivr CDN、浅色和深色模式、离线供应商、品牌标识	setup
数据、日期、CSV	data
映射、几何对象、比例尺、配置	spec
Provider、尺寸、实时数据、深色模式	React
颜色、字体、条件	styling
安装主题、编写自己的主题	themes
高亮、标签、注释	storytelling
替换工具提示、图例或坐标轴	slots
箱线图、蜡烛图、哑铃图、误差线图、漏斗图、棒棒糖图、马赛克图、桑基图、瀑布图	recipes/geoms
此技能没有对应示例的几何对象包	plugins，以包形式发布的几何对象
新几何对象	plugins
精确的选项名称	types
用户表示图表有误，或图表没有绘制任何内容	troubleshooting
编辑现有图表	graphy-editor 技能
人类可读文档	graphy.dev · docs.graphy.dev

• 深色模式通过 Provider 上的 colorScheme 和样式表令牌设置。
• 让 scale.color.discrete() 和 scale.color.continuous() 保持原样；主题或引擎默认值会选择颜色。例外情况：需求中指定了命名调色板、给定颜色（scale.color.discrete({ range }) 或 scale.color.continuous({ range })），或数值跨越零（domainMid）。
• 货币和百分比通过列的 valueFormat 设置格式。config({ numberFormat }) 会为整个图表设置格式。
• CSV 导入会生成 c1 等键。请映射这些键。
• 行按日优先的顺序解析。显示区域设置通过 Provider 上的 formattingLocale 设置。
• 目标线见叙事表达。第二坐标轴见 spec config。
• 不支持表格。

配方

图表	文件
无数据请求的技能演示	HTML · React
条形图、分组、堆叠、百分比、水平	bar
折线图、多组、平滑、间隙、日期	line
面积图、堆叠、百分比	area
饼图、圆环图	pie
散点图、气泡图	scatter
热力图	heatmap
组合图、条形图加折线图、副坐标轴	combo
雷达图	radar
极坐标条形图	polar-bar
箱线图	boxplot
K 线图	candlestick
哑铃图	dumbbell
误差线、置信区间	error-bar
漏斗图	funnel
棒棒糖图	lollipop
Mekko 图、Marimekko 图	mekko
桑基图	sankey
瀑布图	waterfall

这 9 个几何图形配方会安装已发布的软件包；每个都是完整组件。插件各自只有一个文件，位于 recipes/plugins，涵盖从小型示例到完整布局。

注意事项

• 映射列 key，绝不要映射标签。
• 没有饼图几何图形。饼图和圆环图属于极坐标条形图。
• 将主题传给 createGraphyKit({ theme })，或传给提供程序的 theme 属性。主题应放在规格之外。
• plugins 和 theme 只会在挂载时读取一次。若要更改其中任一项，请使用新的 key 重新挂载提供程序。
• 日期字符串默认按日优先解析，除非列设置了 dateFormat。
• 只构建一次规格，或对其进行记忆化。新的规格对象会重新编译图表并清除撤销历史。
• 没有父级高度的响应式图表高度为 0 像素。
• 如果规格未设置 config.content.brandMark.enabled，@graphysdk/react 会显示品牌标记。
• 未使用 jsDelivr 导入映射而导入 @graphysdk/react 的 HTML 成品将无法加载。请使用 setup 中的 CDN 页面。如果面板仍为空白，主机可能屏蔽了 CDN：请使用其中的离线供应商步骤。
• 绝不要从 esm.sh 加载 React 或 Graphy。只使用 jsDelivr。
• @graphysdk/react@1 在 jsDelivr 上会返回 404。请按 setup 中的写法使用 Graphy URL。
• 点或气泡上映射的 size 和 label 不会显示在默认提示框中。标题是 x；行是颜色加 y。使用图层的 tooltip 选项添加一行：geom.point({ tooltip: { size: { title: 'Population' } } })。自定义 Tooltip 插槽会替换整个提示框。
• Waterfall、funnel、boxplot、candlestick、dumbbell、error-bar、lollipop、mekko 和 sankey 都是软件包。请安装 @graphysdk/geom-<name>；不要为它们编写插件。
• 这里的图表类型不包括表格。说明这一点后就停止。不要为表格编写插件。

检查规范

validate-spec.mjs 无需浏览器即可将规范与其数据一并编译，并输出错误和警告。编写或修改规范、编写插件、替换示例数据、调查原因不明的故障，或用户要求验证时，请使用它。对于未更改且使用原始数据的演示或配方，无需例行编译。请使用此脚本，而不要自行编写编译循环。在没有 npm 的主机上，请改为检查渲染后的页面。

该脚本会从其运行目录解析 @graphysdk/viz-engine。当 @graphysdk/viz-engine 是直接依赖时，请从项目根目录运行；pnpm 不会从 @graphysdk/react 提升该依赖。否则，请在临时目录中安装页面导入映射或已安装的 @graphysdk/react/package.json 中指定的确切版本；这两个包始终使用相同版本。

mkdir graphy-check && cd graphy-check
npm init -y
npm install @graphysdk/viz-engine@<exact-version>
node <skill-path>/scripts/validate-spec.mjs <path-to-my-spec.mjs>

每个模块都导出 data 和 spec，并可选导出 plugins 和 colorScheme。从 @graphysdk/react 或 @graphysdk/viz-engine 导入构建器；该脚本会将 React 导入重定向到引擎。每个图表使用一个模块。