Astryx Vega/Vega-Lite集成指南：声明式图表与Astryx主题联动-平芜编程栈

Astryx Vega/Vega-Lite集成指南：声明式图表与Astryx主题联动

【免费下载链接】astryxAn open source design system that's fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx

Astryx 是一个开源、完全可定制的设计系统。本文聚焦其@astryxdesign/vega包，完整讲解Astryx Vega/Vega-Lite 集成：如何用单个VegaChart组件渲染声明式图表，以及如何通过主题令牌实现图表与 Astryx 主题的无缝联动——坐标轴、图例、配色自动跟随明暗模式与多主题切换。

🎯 一个组件搞定两类图表：VegaChart 核心原理

Astryx 的 Vega 集成围绕 VegaChart 组件展开。你不需要分别学习两个图表库的渲染管线，组件会自动判断规格类型并走对应流程：

你传入的 spec	`$schema`指向	组件行为
Vega-Lite 规格	`vega-lite/v5.json`	自动编译成 Vega 规格，再渲染
Vega 规格	`vega/v5.json`	跳过编译，直接渲染
缺失或非法	—	调用`onError`，不渲染任何内容

这套判断逻辑在 VegaChart.tsx 中实现：先校验$schemaURL，再决定走compile()还是直接parse()。

一个声明式柱状图长这样：

import {VegaChart} from '@astryxdesign/vega'; <VegaChart spec={{ $schema: 'https://vega.github.io/schema/vega-lite/v5.json', mark: 'bar', data: {values: [{a: 'A', b: 28}, {a: 'B', b: 55}]}, encoding: { x: {field: 'a', type: 'ordinal'}, y: {field: 'b', type: 'quantitative'}, }, }} />;

对新手来说，这意味着：只描述"数据是什么、怎么编码"，不用手写坐标轴、比例尺和渲染代码——这正是 Vega-Lite 声明式范式的价值，而 Astryx 帮你把它封装成了一个开箱即用的 React 组件。

🎨 Astryx主题联动：buildVegaLiteConfig 让图表自动换装

这是 Astryx 集成最有价值的部分。包内导出了 buildVegaLiteConfig 工具函数，它读取当前主题的令牌，一次性生成整套 Vega-Lite 配置：

const {token} = useTheme(); const config = buildVegaLiteConfig(token); // 通过 compileOptions={{config}} 传给 VegaChart

它覆盖了图表的"骨架"样式——坐标轴颜色与网格、图例字体与布局、标题排版、背景色、折线圆角、圆点标记等。而数据配色则来自 Astryx 的专属数据令牌（见 dataTokens.ts）：

分类色板（10 色）：蓝、橙、紫、绿、粉、青、红、青蓝、棕、靛蓝——用于区分不同数据系列
顺序色阶（5 级深浅）：蓝色、 Shamrock、橙色、粉色等，用于热力图、有序量表

由于令牌使用light-dark()语法定义，切换明暗模式时图表配色无需任何额外代码即可自动适配。想看看真实效果，可以参考 Storybook 中的完整示例 VegaLiteRanges.stories.tsx（含股票走势线图等交互案例）。

🚀 快速开始：三步装好 Astryx Vega 图表

第一步：安装。注意该包目前以@canary标签发布（README 有详细说明），需要显式指定标签，并一并装上运行时依赖：

npm install @astryxdesign/vega@canary vega vega-lite

第二步：渲染。就像上面声明式图表示例那样，把 spec 交给<VegaChart>即可。

第三步（可选）：接入主题。传入compileOptions={{config: buildVegaLiteConfig(token)}}，图表即刻与 Astryx 主题联动。

💡 提示：如需稳定版本，可在项目中锁定确切的 canary 版本号（形如0.x.y-canary.<sha>）。

📋 常用 Props 速查表

Prop	作用	新手提示
`spec`	Vega 或 Vega-Lite 规格（必填，含`$schema`）	核心输入，声明式描述图表
`data`	初始数据集`{名称: 行数组}`	仅在初始化时加载一次，非响应式
`compileOptions`	Vega-Lite 编译选项	在此注入主题 config
`parseConfig`/`parseOptions`	直接透传给 Vega`parse()`	如设置`background`
`viewOptions`	透传给 Vega`View`	可设`renderer: 'canvas'`、自定义 tooltip
`onReady`	拿到运行中的 View 实例	动态更新数据用它
`onError`	错误回调	schema 校验失败时触发

组件对 props 做值比较而非引用比较（viewInputs.ts 实现），所以每次渲染内联新建的 spec 对象不会导致图表反复重建，无需useMemo。需要动态改数据时，通过onReady拿到 View 后调用view.data('表名', 新行)+view.runAsync()即可。

⚠️安全提醒：Vega 规格本质是"程序"而非纯数据，可能执行表达式与加载远程 URL。官方建议只渲染自己编写或审核过的 spec；若来源不可信，可通过parseOptions+viewOptions接入解释执行模式，详见 README 的 Untrusted specs 章节。