shadcn-svelte Chart 组件完全指南：基于 LayerChart 的组合式图表开发实战

shadcn-svelte Chart 组件完全指南基于 LayerChart 的组合式图表开发实战【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelte本文以 shadcn-svelte 官方文档 docs/content/components/chart.md 为主体系统讲解其 Chart 组件集合的设计理念、安装方式与完整实战流程。读者将掌握如何用Chart.Container与Chart.Tooltip两个自定义组件配合 LayerChart 的简化图表Simplified Charts在几分钟内搭建出带坐标轴、网格、提示框与图例的数据可视化并理解 chartConfig、主题色令牌与 Tooltip 的底层实现机制从而在真实项目中自由组合、按需定制。LayerChart v2 预览版使用前必须知晓的前提当前仓库文档在 Chart 章节开头给出了一个重要提醒LayerChart v2 仍处于预发布阶段正在积极演进中。官方文档明确建议只有在你能够接受 v2 稳定版发布前可能出现的破坏性变更breaking changes时才使用它。这也解释了为什么仓库在安装环节使用layerchartnext标签——从 docs/package.json 可以看到项目本身依赖的是layerchart: ^2.0.0。这意味着在接入图表前你应当评估团队对版本迭代的容忍度并关注 LayerChart v2 的发布进度。好消息是由于 shadcn-svelte 的 Chart 组件设计上不封装 LayerChart下文会详细说明当 LayerChart 发布新版本时你可以直接遵循其官方升级路径完成迁移而不会被困在第三方抽象层里。核心设计理念组件是你的而不是封装品Chart组件最与众不同的设计在于——它没有包装 LayerChart。官方文档的原话是We do not wrap LayerChart. This means youre not locked into an abstraction.从 docs/src/lib/registry/ui/chart/index.ts 的源码可以看到整个 Chart 集合只导出两个自定义组件与若干工具函数import ChartContainer from ./chart-container.svelte; import ChartTooltip from ./chart-tooltip.svelte; export { getPayloadConfigFromPayload, type ChartConfig } from ./chart-utils.js; export { ChartContainer, ChartTooltip, ChartContainer as Container, ChartTooltip as Tooltip };也就是说你的图表本体完全由 LayerChart 组件构建shadcn-svelte 只在你需要的地方提供两个粘合剂Chart.Container即ChartContainer外层容器负责注入 chartConfig、生成主题 CSS 变量、统一默认样式Chart.Tooltip即ChartTooltip自定义提示框与 LayerChart 的 Tooltip 上下文无缝衔接。文档给出的最小组合示例script langts import * as Chart from $lib/components/ui/chart/index.js; import { BarChart } from layerchart; const data [ // ... ]; /script Chart.Container BarChart {data} xdate yvalue {#snippet tooltip()} Chart.Tooltip / {/snippet} /BarChart /Chart.ContainerThe components are yours组件是你的是这套设计的核心理念代码复制进你的项目后归你所有你可以任意修改不会被上游抽象绑架。安装 Chart 组件方式一CLI 一键添加在终端执行 shadcn-svelte CLI 的 add 命令即可对应文档中的PMAddComp namechart /其底层执行命令可参考 pm-add-comp.svelteshadcn-sveltelatest add chartCLI 会自动完成依赖安装与文件复制是最省事的方式。方式二手动安装手动安装分三步适合需要完全掌控或离线环境的情况第一步安装 LayerChart 运行时依赖npm install layerchartnext -D注意使用-D并锁定next标签与 v2 预发布状态保持一致使用 pnpm 或 bun 时替换为对应命令。第二步在 CSS 文件中添加图表颜色变量文档提供了开箱即用的浅色/深色两套 chart 色板写入你的src/app.css:root { --chart-1: oklch(0.646 0.222 41.116); --chart-2: oklch(0.6 0.118 184.704); --chart-3: oklch(0.398 0.07 227.392); --chart-4: oklch(0.828 0.189 84.429); --chart-5: oklch(0.769 0.188 70.08); } .dark { --chart-1: oklch(0.488 0.243 264.376); --chart-2: oklch(0.696 0.17 162.48); --chart-3: oklch(0.769 0.188 70.08); --chart-4: oklch(0.627 0.265 303.9); --chart-5: oklch(0.645 0.246 16.439); } theme inline { --color-chart-1: var(--chart-1); --color-chart-2: var(--chart-2); --color-chart-3: var(--chart-3); --color-chart-4: var(--chart-4); --color-chart-5: var(--chart-5); }theme inline的作用是把 CSS 变量桥接为 Tailwind v4 的主题色让你可以在类名中直接使用text-chart-1、fill-chart-2等工具类。第三步复制组件源码将 docs/src/lib/registry/ui/chart 目录下的五个文件chart-container.svelte、chart-tooltip.svelte、chart-style.svelte、chart-utils.ts、index.ts复制到项目src/lib/components/ui/chart/下即可。由于组件只依赖 LayerChart 与项目内已有的cn/WithElementRef等工具函数复制成本很低。你的第一个图表带轴、网格、提示框与图例的分组柱状图文档用完整的四步走流程带你从零构建第一个图表。仓库中对应的完整成品位于 chart-bar-demo.svelte下面是逐步拆解。第一步定义数据数据代表每个月桌面端与移动端的用户数script langts const chartData [ { month: January, desktop: 186, mobile: 80 }, { month: February, desktop: 305, mobile: 200 }, { month: March, desktop: 237, mobile: 120 }, { month: April, desktop: 73, mobile: 190 }, { month: May, desktop: 209, mobile: 130 }, { month: June, desktop: 214, mobile: 140 }, ]; /script官方文档特别强调你的数据可以是任何形状不必拘泥于上述结构。数据到图表的映射完全由 LayerChart 的x、y、dataKey等属性控制数据与展示是解耦的。第二步定义 chartConfigchartConfig 存放图表的展示配置——人类可读的标签、图标以及用于主题化的颜色令牌script langts import * as Chart from $lib/components/ui/chart/index.js; const chartConfig { desktop: { label: Desktop, color: #2563eb, }, mobile: { label: Mobile, color: #60a5fa, }, } satisfies Chart.ChartConfig; /scriptsatisfies Chart.ChartConfig是关键的类型约束。从 chart-utils.ts 可以看到ChartConfig的完整类型定义export type ChartConfig { [k in string]: { label?: string; icon?: Component; } ( | { color?: string; theme?: never } | { color?: never; theme: Recordkeyof typeof THEMES, string } ); };它约束每个系列series必须提供color任意 CSS 颜色字符串或theme包含light/dark两个键的对象二者互斥通过theme?: never实现可选提供label与iconSvelte 组件。第三步用 LayerChart 组件构建图表这里使用 LayerChart 的简化图表之一BarChart。这类组件替你处理了大量通用的图表脚手架坐标轴、网格、缩放等同时保留完全定制能力。核心代码script langts import { scaleBand } from d3-scale; import { BarChart } from layerchart; import * as Chart from $lib/components/ui/chart/index.js; // chartData 与 chartConfig 见前两步 /script Chart.Container config{chartConfig} classmin-h-[200px] w-full BarChart data{chartData} xScale{scaleBand().padding(0.25)} xmonth axisx seriesLayoutgroup tooltipContext{false} series{[ { key: desktop, label: chartConfig.desktop.label, color: chartConfig.desktop.color, }, { key: mobile, label: chartConfig.mobile.label, color: chartConfig.mobile.color, }, ]} / /Chart.Container要点解析xScale{scaleBand().padding(0.25)}使用 d3-scale 的 band 比例尺padding(0.25)控制柱间留白比例seriesLayoutgroup按月份分组并列展示两个系列series数组逐一声明系列与 chartConfig 中标签、颜色的映射关系tooltipContext{false}本阶段暂时关闭默认 tooltip 上下文后续会替换为自定义提示框。至此你已经得到一个带 x 轴与网格的分组柱状图。Chart.Container的默认类名中aspect-video保证了图表容器为 16:9 宽高比。第四步调整坐标轴刻度当前 x 轴每个刻度显示完整月份名如 January文档教你通过props属性向图表内部组件透传自定义参数。props正是 LayerChart 简化图表向底层组件如 xAxis传参的通道Chart.Container config{chartConfig} classmin-h-[200px] w-full BarChart data{chartData} xScale{scaleBand().padding(0.25)} xmonth axisx tooltipContext{false} seriesLayoutgroup series{[ { key: desktop, label: chartConfig.desktop.label, color: chartConfig.desktop.color }, { key: mobile, label: chartConfig.mobile.label, color: chartConfig.mobile.color }, ]} props{{ xAxis: { format: (d) d.slice(0, 3), }, }} / /Chart.Containerprops.xAxis.format是一个格式化函数(d) d.slice(0, 3)会把月份名截断为前三个字母Jan、Feb、Mar…。完整的可运行版本见 chart-bar-axis-tick-demo.svelte。第五步添加 TooltipLayerChart 简化图表开箱即用的外观已经不错但要获得 shadcn-svelte 风格的提示框需要引入自定义的Chart.Tooltip。做法是把第四步的tooltipContext{false}替换为tooltipsnippetChart.Container config{chartConfig} classmin-h-[200px] w-full BarChart data{chartData} xScale{scaleBand().padding(0.25)} xmonth axisx seriesLayoutgroup series{[ { key: desktop, label: chartConfig.desktop.label, color: chartConfig.desktop.color }, { key: mobile, label: chartConfig.mobile.label, color: chartConfig.mobile.color }, ]} props{{ xAxis: { format: (d) d.slice(0, 3), }, }} {#snippet tooltip()} Chart.Tooltip / {/snippet} /BarChart /Chart.Containersnippet是 Svelte 5 的插槽机制tooltipsnippet 会在图表渲染提示框的位置插入Chart.Tooltip组件提示框的标签、系列名与颜色会自动从 chartConfig 中读取。完整示例见 chart-bar-tooltip-demo.svelte。第六步添加 Legend图例更简单——只需给BarChart加上legend布尔属性Chart.Container config{chartConfig} classmin-h-[200px] w-full BarChart data{chartData} xScale{scaleBand().padding(0.25)} xmonth axisx seriesLayoutgroup legend series{[ { key: desktop, label: chartConfig.desktop.label, color: chartConfig.desktop.color }, { key: mobile, label: chartConfig.mobile.label, color: chartConfig.mobile.color }, ]} props{{ xAxis: { format: (d) d.slice(0, 3), }, }} {#snippet tooltip()} Chart.Tooltip / {/snippet} /BarChart /Chart.Container文档同时透露项目正在与 LayerChart 合作为 legend 增加类似 tooltip 的 payload 机制以便未来更容易实现完全自定义的图例。完整示例见 chart-bar-legend-demo.svelte。至此你的第一个图表完成了带 x 轴、网格、分组柱、格式化刻度、自定义提示框与图例的柱状图。Chart Config 深入配置与数据的解耦chartConfig 是图表的配置中枢存放标签、图标与颜色且刻意与图表数据解耦。这种设计的实际收益有两点配置与颜色令牌可以在多个图表间共享——同一个 chartConfig 可以被柱状图、折线图复用可以独立工作——当你的数据或颜色令牌来自远程接口或异构格式时配置与数据分离让接入变得简单。chartConfig 支持三种配置能力label人类可读标签、iconlucide 等图标组件、color/theme颜色或明暗主题对象script langts import MonitorIcon from lucide/svelte/icons/monitor; import * as Chart from $lib/components/ui/chart/index.js; const chartConfig { desktop: { label: Desktop, icon: MonitorIcon, // A color like hsl(220, 98%, 61%) or var(--color-name) color: #2563eb, // OR a theme object with light and dark keys theme: { light: #2563eb, dark: #dc2626, }, }, } satisfies Chart.ChartConfig; /script配置中的icon会被 Tooltip 渲染为系列前的图标theme对象允许浅色/深色主题使用不同颜色比单一color更灵活。配置的底层消费机制在运行时chartConfig 通过 Svelte 5 的 Context API 向下传递。源码 chart-utils.ts 中的实现非常清晰const chartContextKey Symbol(chart-context); export function setChartContext(value: ChartContextValue) { return setContext(chartContextKey, value); } export function useChart() { return getContextChartContextValue(chartContextKey); }ChartContainer在渲染时调用setChartContext({ get config() { return config; } })注入配置而ChartTooltip通过useChart()取回配置再结合getPayloadConfigFromPayload()工具函数从 LayerChart 的 tooltip payload 中反查出对应系列的 label、icon 与颜色。这条配置注入 → 上下文读取 → payload 反查的链路是理解整个图表数据流的关键。主题与颜色CSS 变量优先Chart 内置完整的主题支持。你可以使用 CSS 变量官方推荐也可以直接使用 hex、hsl、oklch 等任意 CSS 颜色格式。方式一CSS 变量推荐第 1 步在 CSS 文件中定义颜色:root { --background: oklch(1 0 0); --foreground: oklch(0.145 0 0); /* ... */ --chart-1: oklch(0.646 0.222 41.116); --chart-2: oklch(0.6 0.118 184.704); } .dark { --background: oklch(0.145 0 0); --foreground: oklch(0.985 0 0); /* ... */ --chart-1: oklch(0.488 0.243 264.376); --chart-2: oklch(0.696 0.17 162.48); }第 2 步在 chartConfig 中引用变量script langts const chartConfig { desktop: { label: Desktop, color: var(--chart-1), }, mobile: { label: Mobile, color: var(--chart-2), }, } satisfies Chart.ChartConfig; /script方式二直接写颜色值不依赖 CSS 变量直接在 chartConfig 中写色值格式任选script langts const chartConfig { desktop: { label: Desktop, color: #2563eb, }, } satisfies Chart.ChartConfig; /script使用主题色var(--color-KEY)约定要在图表内部使用主题色统一通过var(--color-KEY)格式引用其中KEY是 chartConfig 中的系列键名。这套变量由 chart-style.svelte 在运行时动态生成它遍历 chartConfig 中定义了color或theme的项为当前图表实例以data-chart{chartId}为作用域注入style块声明形如--color-desktop: #2563eb;的局部变量并在 light/dark 两套主题下分别生成因此颜色会自动随主题切换。在组件中使用Bar fillvar(--color-desktop) /在数据中使用const chartData [ { browser: chrome, visitors: 275, color: var(--color-chrome) }, { browser: safari, visitors: 200, color: var(--color-safari) }, ];在 Tailwind 类名中使用Label classfill-(--color-desktop) /Tailwind v4 的fill-(...)语法会读取--color-desktop变量作为填充色。Tooltip 详解标签、名称、指示器与值一个完整的 Chart 提示框由四部分构成标签Label、名称Name、指示器Indicator与值Value你可以通过组合 props 自由定制。Props 一览Chart.Tooltip支持以下 props完整继承自官方文档Prop类型描述labelKeystring用于标签的 config 或 data keynameKeystring用于名称的 config 或 data keyindicatordotline或dashed提示框的指示器样式hideLabelboolean是否隐藏标签hideIndicatorboolean是否隐藏指示器labelstring提示框的自定义标签labelFormatterfunction格式化标签的函数formatterSnippet提供提示框灵活渲染的 Snippet从 chart-tooltip.svelte 的源码可以确认这些 props 的默认值与实现细节hideLabel默认falseindicator默认dothideIndicator默认falselabelFormatter默认是一个把值转成字符串的defaultFormatter颜色自动引用提示框中每个系列的指示器颜色通过color || item.config?.color || item.color三级回退获取最终落回 chartConfig 中定义的颜色因此无需手动传色自动过滤无效系列组件内部通过chartCtx.tooltip.series.filter((s) s.value ! undefined)过滤出有值的系列这对饼图/环形图Arc/Pie这类只有悬停项有值的场景尤其重要formatterSnippet 收到{ value, name, item, index, payload }参数用于完全自定义某一行提示内容的渲染indicator为line时指示器会拉伸到与内容同高dashed时则渲染为虚线。自定义标签与名称键默认情况下Tooltip 从数据与配置中自动推断标签和名称。当你的数据键不是常规命名时用labelKey和nameKey指定script langts const chartData [ { browser: chrome, visitors: 187, color: var(--color-chrome) }, { browser: safari, visitors: 200, color: var(--color-safari) }, ]; const chartConfig { visitors: { label: Total Visitors, }, chrome: { label: Chrome, color: var(--chart-1), }, safari: { label: Safari, color: var(--chart-2), }, } satisfies ChartConfig; /script Chart.Tooltip labelKeyvisitors nameKeybrowser /上面的配置会让提示框的标签显示为Total Visitors来自visitors.label名称分别显示为Chrome和Safari来自browser键对应的配置 label。这一查找逻辑由getPayloadConfigFromPayload()实现它会依次尝试 payload 的config、key、label以及原始数据字段最终在 chartConfig 中命中对应的配置项。扩展更多图表类型与组合方式除了文档正文演示的BarChart仓库的 create 示例目录 docs/src/lib/registry/examples/create/chart 展示了同一套Chart.Container LayerChart 组件架构下的更多图表类型折线图chart-line-example.svelte使用LineChart与curveMonotoneX曲线通过props.spline配置curve、strokeWidth、motion: tween动画props.highlight.points控制悬停高亮点面积图chart-area-example.svelteAreaChartscaleBand()配套 Cards 组件形成卡片 图表的仪表盘布局柱状图进阶chart-bar-example.svelte使用x1Scale{scaleBand().paddingInner(0.2)}实现双比例尺的堆叠/分组效果雷达图与径向图chart-radar-example.svelte、chart-radial-example.svelte展示环形进度等场景径向图通过maxValue控制刻度上限。这些示例印证了文档的核心观点你始终在使用 LayerChart 的原生能力构建图表Chart 组件只负责提供一致的主题与提示框体验。此外打包好的静态 registry 条目位于 docs/static/registry如chart.json、chart-area-default.json、chart-bar-interactive.json、chart-pie-simple.json、chart-radar-grid-circle.json、chart-radial-simple.json等记录了每个图表示例的完整源码与依赖清单可作为离线参考。小结本文完整梳理了 shadcn-svelte Chart 组件的设计哲学与实战路径组合式设计不封装 LayerChartChart.Container负责配置注入与主题Chart.Tooltip负责提示框其余全部交给 LayerChart 简化图表配置与数据解耦chartConfig集中管理标签、图标与颜色令牌可跨图表共享并通过 Context API 与getPayloadConfigFromPayload实现运行时解析主题体系CSS 变量优先var(--color-KEY)令牌由ChartStyle动态生成浅色/深色自动切换工具提示可深度定制labelKey/nameKey/indicator/hideLabel/formatter等 props 覆盖从简单显示到完全自定义渲染的全部需求。最后再次提醒LayerChart v2 当前处于 pre-release 阶段API 可能变化。选择这套方案时请确认你的项目可以接受 v2 稳定版落地前的破坏性变更并持续关注 LayerChart v2 的发布动态。【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelte创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考