做 Blazor 图表开发时，你是否也厌倦了手写冗长的 ECharts option 配置？Blazor Blueprint 是受 shadcn/ui 启发的 Blazor 可访问组件库，内置 14 种声明式组合的 ECharts 图表组件——把几个子组件嵌套在一起，就能做出支持暗色模式、自动响应的生产级 Blazor 数据可视化。

为什么选择声明式组合 API？

传统做法是把 ECharts 的 JSON option 拼成一个巨大的字符串，轴、提示框、系列全部手工配置，代码既难读又难维护。Blazor Blueprint 采用Recharts 风格的组合模式（composition pattern）：图表是一个容器，坐标轴、提示框、图例、系列都是"子组件"，嵌套即可生效。

<BbLineChart Data="@data" Height="300px"> <BbXAxis DataKey="month" /> <BbYAxis /> <BbChartTooltip /> <BbLine DataKey="desktop" Name="Desktop" Color="var(--chart-1)" Curve="CurveType.Smooth" /> </BbLineChart>

它的背后机制很清晰（可阅读 BbChartBase.razor.cs 了解实现）：

• 反射式数据绑定：Data传入任意IEnumerable，用DataKey按属性名取值，无需手动映射
• 主题集成：系列默认使用 CSS 变量--chart-1~--chart-5，暗色/亮色切换自动重绘
• 自动响应式：每个图表实例都挂载ResizeObserver，窗口缩放时自动 resize
• 零外部依赖：ECharts 5.5.x 已作为静态资源打包在wwwroot/lib/echarts/echarts.min.js，不需要 CDN 或额外 NuGet 包

完整 API 文档见 Chart/README.md。

14 种 ECharts 图表组件速查表

类型定义都在 Types/ 目录，可逐文件查看参数。此外还有一个"隐藏的第 15 种"——综合图容器BbChart，允许在一张图里自由混搭 Bar、Line、Area、Scatter 系列：

<BbChart Data="@data" Height="350px"> <BbXAxis DataKey="month" /> <BbYAxis /> <BbChartTooltip /> <BbBar DataKey="revenue" Name="Revenue" Color="var(--chart-1)" /> <BbLine DataKey="profit" Name="Profit" Color="var(--chart-2)" Curve="CurveType.Smooth" /> </BbChart>

实现见 BbChart.cs。

快速上手：30 秒画出第一张折线图

所有图表容器共享同一组基础参数：Data（数据源）、Height、Width、Title、EnableAnimations。以月度访问数据为例：

@code { private record MonthlyData(string Month, int Desktop, int Mobile); private List<MonthlyData> data = [ new("Jan", 186, 80), new("Feb", 305, 200), new("Mar", 237, 120), new("Apr", 73, 190), new("May", 209, 130), new("Jun", 214, 140) ]; }

<BbLineChart Data="@data" Height="300px"> <BbXAxis DataKey="month" /> <BbYAxis /> <BbChartTooltip /> <BbChartLegend /> <BbLine DataKey="desktop" Name="Desktop" Color="var(--chart-1)" /> <BbLine DataKey="mobile" Name="Mobile" Color="var(--chart-2)" /> </BbLineChart>

注意数据只声明了一次，两条线分别用DataKey="desktop"和DataKey="mobile"指向不同属性——这正是"声明式"的含义：你描述结构，而不是拼配置。

更完整的可交互示例参考 LineChartDemo.razor，可折叠代码片段在 CodeExamples/Charts/LineChart/ 目录（default.txt、stacked.txt、step.txt等 8 种变体）。

常用子组件：坐标轴、提示框与图例

所有图表都可以嵌套这组"基础设施"子组件，它们通过CascadingValue自动注册到父图表：

完整参数表见 README 参数章节。

进阶技巧：堆叠、环形中心标签与渐变填充

📊 堆叠柱状图：系列上加Stacked="true"即可，多个BbBar自动按StackGroup归组：

<BbBarChart Data="@data" Height="200px"> <BbXAxis DataKey="month" /> <BbChartTooltip /> <BbChartLegend /> <BbBar DataKey="desktop" Name="Desktop" Color="var(--chart-1)" Stacked="true" /> <BbBar DataKey="mobile" Name="Mobile" Color="var(--chart-2)" Stacked="true" BorderRadius="4" /> </BbBarChart>

参考示例：stacked-legend.txt。

🍩 环形图 + 中心标签：InnerRadius="60"变环形，嵌套<BbCenterLabel>显示汇总值：

<BbPieChart Data="@data" Height="250px"> <BbChartTooltip /> <BbPie DataKey="visitors" NameKey="browser" InnerRadius="60"> <BbCenterLabel Title="Total" Value="1,234" /> </BbPie> </BbPieChart>

🎨 渐变填充：系列内部可嵌套Fill → LinearGradient → GradientStop，实现从主题色淡出的高级效果：

<BbArea DataKey="desktop" Name="Desktop" Color="var(--chart-1)" Curve="CurveType.Smooth"> <BbFill> <BbLinearGradient Direction="GradientDirection.Vertical"> <BbGradientStop Offset="0" Color="var(--chart-1)" Opacity="0.8" /> <BbGradientStop Offset="1" Color="var(--chart-1)" Opacity="0.1" /> </BbLinearGradient> </BbFill> </BbArea>

值得尝试的三种特色图表

🗺️ MapChart：开箱即用的世界地图。内置 Natural Earth 数据集的 241 个国家边界，无需 API Key、无需外部地图服务：

<BbMapChart Data="@visitors" Height="420px" OnDataPointClick="SelectCountry"> <BbChartTooltip /> <BbMap CountryKey="Country" DataKey="Visitors" Name="Visitors" /> </BbMapChart>

配合<BbVisualMap>可固定颜色区间，让多张地图跨期可比；Roam="true"开启缩放平移。地图资源说明见 maps/README.md。

🌊 SankeyChart：桑基流向图。直接绑定"链接"集合（源、目标、值三列），节点列表自动从名称派生：

<BbSankeyChart Data="@flows" Height="320px"> <BbChartTooltip /> <BbSankey SourceKey="from" TargetKey="to" DataKey="value" /> </BbSankeyChart>

它还做了贴心防护：若链接构成环（ECharts 会直接抛错导致整图空白），会自动丢弃成环的那条链接并正常绘制其余部分。

📈 CandlestickChart：金融 K 线图。内置涨跌配色与网格样式，适合行情类看板，示例见 CandlestickChartDemo.razor。

暗色模式与响应式：完全零配置

这是整套图表最"省心"的地方，你几乎不需要写任何额外代码：

1. 主题色自动解析：ECharts 原生不支持 CSSvar()，chart-theme.js会在运行时通过getComputedStyle()把--chart-1~--chart-5解析为具体色值（连 OKLCH 颜色也能正确转换）
2. 主题切换自动重绘：MutationObserver监听<html>类名变化，切换暗色/亮色时所有图表即时重渲染
3. 窗口缩放自适应：每个图表实例独立挂载ResizeObserver
4. 统一卡片容器：BbChartContainer提供 Card 风格的标题 + 副标题 + 图表布局，整页观感一致

系列未显式指定Color时，会按出现顺序自动分配--chart-1~--chart-5，因此多系列图表开箱就配色协调。

相关目录与文件资料

小结

Blazor Blueprint 把 ECharts 封装成了一套"嵌套子组件即配置"的 Blazor 图表 API：14 种常用图表类型全覆盖，数据绑定靠DataKey一行搞定，主题、暗色模式、响应式全部自动化。对于需要 Blazor 数据可视化方案的团队，这套声明式组合 API 是少见的"学习成本低、视觉产出高"的选择——先跑通 LineChartDemo.razor 里的第一个折线图，剩下的就是按需挑组件了。