shadcn-vue 面积图组件 AreaChart 使用指南：从 API 配置到自定义 Tooltip 实战

UI组件前端【免费下载链接】shadcn-vueVue port of shadcn-ui项目地址https://gitcode.com/gh_mirrors/sh/shadcn-vue点击查看免费下载本文围绕 shadcn-vue 仓库中图表体系deprecated/www目录下基于 Unovis 构建的 Charts 模块里的AreaChart面积图组件展开完整梳理其全部 Props/Emit API、安装与 CSS 变量前置配置并结合仓库内的 Demo 与源码实现讲解基础面积图、Sparkline 迷你图、自定义 Tooltip 三类实战用法。读完本文你将能够在自己的 Vue 3 项目中独立接入并深度定制 AreaChart包括控制坐标轴、图例、渐变与曲线类型以及注入自定义提示框组件。一、AreaChart 是什么AreaChart面积图通过在折线下方填充区域来展示数据随时间变化的趋势与模式适合表达总量走势实际值与预测值对比等场景。在 shadcn-vue 仓库中它属于 Charts 图表模块 下的四种图表类型Area / Line / Bar / Donut之一官方文档对它的定位是An area chart visually represents data over time, displaying trends and patterns through filled-in areas under a line graph.需要说明的是该组件处于Legacy / Alpha状态官方文档明确标注 Component will be moved to extended repo with Tailwind v4 support且仅支持 Vue 3.3。当前仓库中的实现位于 deprecated/www/src/registry/new-york/ui/chart-area/底层构建于 Unovis模块化数据可视化框架之上设计上参考了 Tremor。组件对外暴露的 API 文档为自动生成的 AreaChart.md它被include到 面积图文档页 的 API 章节中下方所有参数说明均与该文件及 源码类型定义 保持一致。二、安装与前置配置1. 添加组件在项目根目录执行npx shadcn-vuelatest add chart-area该命令会向项目注入chart-area组件即 AreaChart.vue 及其导出同时还需要随附的chart相关子组件ChartLegend、ChartCrosshair等见 chart 目录。2. 全局 CSS 变量配置图表组件依赖 Unovis 的 CSS 变量来渲染 Tooltip 与坐标轴颜色。官方文档要求向tailwind.css的layer base中追加以下样式layer base { :root { /* ... */ --vis-tooltip-background-color: none !important; --vis-tooltip-border-color: none !important; --vis-tooltip-text-color: none !important; --vis-tooltip-shadow-color: none !important; --vis-tooltip-backdrop-filter: none !important; --vis-tooltip-padding: none !important; --vis-primary-color: var(--primary); /* change to any hsl value you want */ --vis-secondary-color: 160 81% 40%; --vis-text-color: var(--muted-foreground); } }要点--vis-tooltip-*系列变量统一置为none !important是为了让 Unovis 原生 Tooltip 样式失效从而使用 shadcn-vue 自绘的 ChartTooltip.vue / ChartCrosshair.vue--vis-primary-color建议映射到你的主题主色var(--primary)--vis-secondary-color默认为示例中的绿色可按需改成任意 hsl 值--vis-text-color用于坐标轴刻度文字颜色源码中两个VisAxis均通过tick-text-colorhsl(var(--vis-text-color))读取它见 AreaChart.vue。如果你的组件没有使用 CSS 变量体系则需要把--vis-primary-color与--vis-text-color替换为你想要的固定 hsl 值并且记得一并提供暗色模式下的取值。三、API 完整参考Props 与 Emits以下参数表完整继承了 AreaChart.md 的内容并与 index.ts 中的BaseChartProps泛型定义逐一对应T extends Recordstring, any表示数据项为字典对象。Props名称类型必填默认值说明dataRecordstring, any[]是—源数据每一项是一个字典对象categoriesstring[]是—从数据中挑选出的分类字段用于填充图例与 Tooltipindexstring是—设置映射到坐标轴的键X 轴分类键colorsstring[]否—自定义图表颜色默认由defaultColors按分类数量生成marginSpacing否{ top: 0, bottom: 0, left: 0, right: 0 }容器四周的边距filterOpacitynumber否0.2非选中图例中置灰字段的透明度xFormatter(tick: number \| Date, i: number, ticks: number[] \| Date[]) string否—格式化 X 轴标签的函数yFormatter(tick: number \| Date, i: number, ticks: number[] \| Date[]) string否—格式化 Y 轴标签的函数showXAxisboolean否true控制 X 轴显隐showYAxisboolean否true控制 Y 轴显隐showTooltipboolean否true控制 Tooltip 显隐showLegendboolean否true控制图例显隐showGridLineboolean否true控制网格线显隐customTooltipComponent否—传入自定义 Tooltip 组件curveTypeCurveType否CurveType.MonotoneX曲线类型来自unovis/tsshowGradientboolean否true控制面积渐变填充的显隐从源码实现看所有带默认值的 Props 都由withDefaults集中声明AreaChart.vue其中margin使用工厂函数返回新对象以避免共享引用。Emits名称载荷类型说明legendItemClick[d: BulletLegendItemInterface, i: number]点击图例某一项时触发参数为图例项对象与索引legendItemClick由内部的handleLegendItemClick转发见 AreaChart.vue可用于监听用户对图例项的交互例如联动外部筛选器。四、基础用法双分类面积图以官方 AreaChartDemo.vue 为例展示实际值 total 预测值 predicted双曲线面积图script setup langts import { AreaChart } from /registry/new-york/ui/chart-area const data [ { name: Jan, total: Math.floor(Math.random() * 2000) 500, predicted: Math.floor(Math.random() * 2000) 500 }, { name: Feb, total: Math.floor(Math.random() * 2000) 500, predicted: Math.floor(Math.random() * 2000) 500 }, { name: Mar, total: Math.floor(Math.random() * 2000) 500, predicted: Math.floor(Math.random() * 2000) 500 }, { name: Apr, total: Math.floor(Math.random() * 2000) 500, predicted: Math.floor(Math.random() * 2000) 500 }, { name: May, total: Math.floor(Math.random() * 2000) 500, predicted: Math.floor(Math.random() * 2000) 500 }, { name: Jun, total: Math.floor(Math.random() * 2000) 500, predicted: Math.floor(Math.random() * 2000) 500 }, { name: Jul, total: Math.floor(Math.random() * 2000) 500, predicted: Math.floor(Math.random() * 2000) 500 }, ] /script template AreaChart :datadata indexname :categories[total, predicted] / /template关键点indexname把数据中的name字段映射为 X 轴分类键categories传入两个字段名图例与 Tooltip 会按这两个分类渲染不传colors时源码通过defaultColors(props.categories.length)见 AreaChart.vue按分类数量生成默认配色。也可以显式传colors覆盖默认色template AreaChart :datadata indexname :categories[total, predicted] :colors[blue, pink, orange, red] / /template五、Sparkline 迷你走势图把面积图变成极简的 Sparkline只需隐藏坐标轴、网格线与图例。官方 AreaChartSparkline.vue 给出了完整示例script setup langts import { CurveType } from unovis/ts import { AreaChart } from /registry/new-york/ui/chart-area const data [ { name: Jan, total: Math.floor(Math.random() * 2000) 1000 }, { name: Feb, total: Math.floor(Math.random() * 2000) 1000 }, { name: Mar, total: Math.floor(Math.random() * 2000) 1000 }, { name: Apr, total: Math.floor(Math.random() * 2000) 1000 }, { name: May, total: Math.floor(Math.random() * 2000) 1000 }, { name: Jun, total: Math.floor(Math.random() * 2000) 1000 }, { name: Jul, total: Math.floor(Math.random() * 2000) 1000 }, { name: Aug, total: Math.floor(Math.random() * 2000) 1000 }, { name: Sep, total: Math.floor(Math.random() * 2000) 1000 }, { name: Oct, total: Math.floor(Math.random() * 2000) 1000 }, { name: Nov, total: Math.floor(Math.random() * 2000) 1000 }, { name: Dec, total: Math.floor(Math.random() * 2000) 1000 }, ] /script template AreaChart classh-[100px] w-[400px] indexname :datadata :categories[total] :show-grid-linefalse :show-legendfalse :show-x-axisfalse :show-y-axisfalse :curve-typeCurveType.Linear / /template要点通过:show-x-axisfalse、:show-y-axisfalse、:show-grid-linefalse、:show-legendfalse关闭所有辅助元素组件根节点是w-full h-[400px]的容器通过class覆盖为h-[100px] w-[400px]控制尺寸源码在根节点使用cn(w-full h-[400px] flex flex-col items-end, $attrs.class ?? )合并类名见 AreaChart.vueCurveType.Linear换成直线曲线视觉效果更干脆。六、自定义 Tooltip如果默认 Tooltip 不满足需求可通过customTooltip传入一个自定义 Vue 组件。官方 AreaChartCustomTooltip.vue 示例script setup langts import { AreaChart } from /registry/new-york/ui/chart-area import CustomChartTooltip from ./CustomChartTooltip.vue const data [ { name: Jan, total: Math.floor(Math.random() * 2000) 500, predicted: Math.floor(Math.random() * 2000) 500 }, { name: Feb, total: Math.floor(Math.random() * 2000) 500, predicted: Math.floor(Math.random() * 2000) 500 }, { name: Mar, total: Math.floor(Math.random() * 2000) 500, predicted: Math.floor(Math.random() * 2000) 500 }, { name: Apr, total: Math.floor(Math.random() * 2000) 500, predicted: Math.floor(Math.random() * 2000) 500 }, { name: May, total: Math.floor(Math.random() * 2000) 500, predicted: Math.floor(Math.random() * 2000) 500 }, { name: Jun, total: Math.floor(Math.random() * 2000) 500, predicted: Math.floor(Math.random() * 2000) 500 }, { name: Jul, total: Math.floor(Math.random() * 2000) 500, predicted: Math.floor(Math.random() * 2000) 500 }, ] /script template AreaChart indexname :datadata :categories[total, predicted] :custom-tooltipCustomChartTooltip / /template自定义组件接收固定的 Props 结构见 CustomChartTooltip.vuedefineProps{ title?: string data: { name: string color: string value: any }[] }()其中data数组的每一项对应一个分类name为分类名color为该分类在图中的颜色value为当前悬停点的数值。仓库自带的默认实现是 ChartTooltip.vue你可以参考它来编写自己的样式例如用Card组件把每项渲染成色条 名称 数值的布局script setup langts import { Card, CardContent } from /registry/new-york/ui/card defineProps{ title?: string data: { name: string color: string value: any }[] }() /script template Card classtext-sm CardContent classp-3 min-w-[180px] flex flex-col gap-2 div v-for(item, key) in data :keykey classflex justify-between items-center div classflex items-center span classw-1 h-7 mr-4 rounded-full :style{ background: item.color } / span{{ item.name }}/span /div span classfont-semibold ml-4{{ item.value }}/span /div /CardContent /Card /template注意customTooltip仅在showTooltip为true时生效源码中ChartCrosshair只有在showTooltip为真时才渲染并把custom-tooltip透传给它见 AreaChart.vue。七、源码实现剖析理解 AreaChart.vue 的实现有助于判断各 Props 的真实行为图层结构根容器下依次是ChartLegend图例受showLegend控制、VisXYContainerUnovis 坐标系容器内部通过v-for按categories分别渲染一组VisArea面积VisLine描边折线图层渐变填充组件使用useId()生成唯一 IDchartRef在defs中为每个颜色定义linearGradient。当showGradient为true时渐变从stop-opacity 0.45%过渡到095%关闭时则用纯色stop见 AreaChart.vue图例联动置灰面积与折线的透明度都读取legendItems中对应项的inactive状态被置灰的分类透明度降为filterOpacity默认0.2这是filterOpacity参数的真实作用点AreaChart.vue 与 L109坐标轴X 轴默认grid-linefalse且tick-linefalsetick 文案默认由data[v]?.[index]取回原始分类名Y 轴网格线由showGridLine控制并给网格线附加了text-muted样式类挂载时序通过useMounted()延迟设置容器高度为100%避免 SSR/首屏时 Unovis 容器高度计算异常响应式类型组件使用 Vue 3.3 的genericT extends Recordstring, any泛型语法这也是文档强调仅支持 Vue 3.3的直接原因。八、注意事项与局限Legacy 状态Charts 模块整体标注为 Legacy官方计划将其迁移到独立扩展仓库并适配 Tailwind v4当前仓库内实现对应 Tailwind v3 时代版本要求必须使用 Vue 3.3泛型 SFC 与useId依赖前置样式不可省略未配置--vis-tooltip-*与--vis-primary-color等变量会导致 Tooltip 样式异常或颜色缺失随机数据示例官方 Demo 使用Math.random()生成演示数据实际使用时应替换为稳定、真实的数据源避免每次渲染数值跳变尺寸控制组件默认高度400px通过class覆盖如需精确控制图表绘制区域可配合marginProp 调整容器边距。九、相关参考文件API 元数据自动生成AreaChart.md官方文档页area.md、charts.md组件实现AreaChart.vue、index.ts官方示例AreaChartDemo.vue、AreaChartSparkline.vue、AreaChartCustomTooltip.vue、CustomChartTooltip.vue配套子组件chart 目录赞分享UI组件前端【免费下载链接】shadcn-vueVue port of shadcn-ui项目地址https://gitcode.com/gh_mirrors/sh/shadcn-vue点击查看免费下载相关推荐ToolJet 表格组件服务端分页实战指南基于 limit/offset 实现大数据量表格的高性能加载ToolJet 表格组件服务端分页实战指南基于 limit/offset 实现大数据量表格的高性能加载 导读 当表格数据量达到数万甚至数十万行时把全部数据一UI组件前端p5.js WebGL 模式架构深度解析RendererGL、Shader、Texture 与 Geometry 四大核心对象p5.js WebGL 模式架构深度解析RendererGL、Shader、Texture 与 Geometry 四大核心对象 本文面向 p5.js 的贡献者UI组件前端shadcn-vue 组件注册表 FAQ 实战指南复杂组件结构、自定义 Tailwind 颜色与动画配置shadcn vue 组件注册表 FAQ 实战指南复杂组件结构、自定义 Tailwind 颜色与动画配置 组件注册表registry是 shadcn vuUI组件前端上一篇Ktor应用逆向实战android-reverse-engineering-skill如何抓出字符串路径与Auth插件下一篇Kubernetes AI控制台实战指南企业级K8M深度解析与最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考