BarChart 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

用柱状图比较不同类别的数据，支持横向、纵向、分组与堆叠展示，以及坐标轴和交互提示。

使用选择

用于比较类别数据。连续时间趋势可选 LineChart，占比可选 CircularChart；数值轴和颜色使用图表公开 API，不手写页面 SVG。

• 传入业务 data；省略 data 会显示内置示例数据。mode 控制单柱、分组、堆叠等形态，具体结构见 API 与数据结构。

• loading 保留图表占位并暂停数据交互；HoverPanel 默认开启。图表颜色通过 colors / colorMode 配置。

• 根默认可访问名称随 LocaleProvider 切换，使用 barChart.name；显式 aria-label 优先。数据单元格组使用 barChart.cells。业务名称、数据值与数字格式保持调用方内容。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { Button, Frame } from '@snowui-design-system/components';	import { BarChart } from '@snowui-design-system/components';	let monthlyCoverageChart: any;</script> <Frame column style="align-items: center; gap: var(--gap-5); width: 100%;">	<BarChart		bind:this={monthlyCoverageChart}		width="100%"		barWidth={32}		groupGap={4}		showYAxis		showGrid		hoverMode="cell"		showHoverLabel={true}		showHoverPanel={true}		alwaysShowHoverLabel={true}		hoverPanelPlacement="pointer"		hoverPanelVariant="dark"		data={[			{ name: 'Jan', value: 82.6 },			{ name: 'Feb', value: 84.1 },			{ name: 'Mar', value: 83.4 },			{ name: 'Apr', value: 85.7 },			{ name: 'May', value: 86.2 },			{ name: 'Jun', value: 84.9 },			{ name: 'Jul', value: 87.3 },			{ name: 'Aug', value: 86.8 },			{ name: 'Sep', value: 88.1 },			{ name: 'Oct', value: 87.6 },			{ name: 'Nov', value: 89.2 },			{ name: 'Dec', value: 88.7 }		]}	/>	<div style="display: flex; justify-content: center; gap: var(--gap-2); width: 100%;">		<Button onclick={() => monthlyCoverageChart?.replay?.()}>Replay animation</Button>		<Button onclick={() => monthlyCoverageChart?.reverseAppearance?.()}>Reverse animation</Button>	</div></Frame>

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

设计原则

• Chart 原子组件: BarChart 只负责柱状图本体，不内置标题、卡片背景、legend 或 toolbar。

• 单元模型: 一个分类项是一个 bar unit。单元统一控制柱粗细、圆角、方向和分类坐标；单元内部可以渲染单柱、多段、相叠柱或多根并排柱。

• 多段式统一规则: 三段式是多段式的特例。mode="stack" 使用 segments 渲染任意段数；segmentGap={0} 表示中间无间隔，segmentGap>0 表示分段之间有透明间隔且每段独立圆角。hover / focus / 常显数值只在最顶段上方显示一次，值为全部分段之和。

• 相叠规则: mode="overlay" 使用 bars 的前两项有效数据，第一项为后层、第二项为前层；两层各自独立命名和取值，共享零基线同轴相叠，不累加。后层为 10% 不透明度、前层为 100%；前层可高于后层。

• 并排规则: mode="group" 使用 bars 在同一单元内并排。默认柱间距 barGap=4，颜色使用 Chart 默认色序，可扩展为多柱。

• 方向规则: orientation="vertical" 为纵向柱状图，分类轴在横向；orientation="horizontal" 为横向条形图，分类轴在纵向。所有柱模式都支持两个方向。

• 坐标轴内建: 坐标轴、刻度、网格线属于 BarChart 形态能力，放在组件内。

• 响应式密度: BarChart 直接观察根层最终显示尺寸并以实测宽高重算 SVG 几何，不要求页面自行创建 ResizeObserver。柱粗细可随分类 cell 收窄，但不得小于 2px；同一分类内并排柱和相邻分类柱的视觉间距不得小于 4px。

• 横向密度: 横向柱高沿用柱粗细下限 2px，上下相邻柱间距沿用 4px；分类 Y label 按最终绘图区高度、16px 行高与 4px 上下间距抽稀，首尾仍放不下时全部隐藏。

• 标签抽稀: xLabelAutoCull 只减少纵向图的分类轴 label，不删除柱体、坐标轴、命中 cell 或数据；横向图的底部数值刻度按绘图区实际宽度自动抽稀。空字符串 label 不参与候选数量和首尾判定，稀疏月份等标签按非空项等步抽稀。可见 label 必须完整显示且相邻文字至少保留 4px；空间不足时保留首尾非空项并等步抽稀，若首尾两个完整 label 仍放不下则隐藏全部横轴 label。常驻顶部数值使用独立的 valueLabelAutoCull / valueMaxLabelCount，按最终数值文本宽度抽稀；被省略的数值仍会在对应柱 hover / focus 时显示。

• Y 轴自适应宽度: Y 轴不使用固定预留宽度；标签区宽度等于当前最宽可见标签的实际渲染宽度，标签右边缘与绘图区起点固定保留 12px。纵向数值轴和横向分类轴使用同一 Chart 共享测量入口；标签变宽时仅按实际增加的宽度压缩绘图区。

• 动态顶部安全区: 普通柱距组件顶部至少 8px；纵向图显示 Y 轴时最小为 16px；顶部数值 label 不额外增加安全区，仍保持在柱顶上方 4px，必要时可溢出绘图区顶边。显示 X 轴时底部仅保留 8px 标签间距和 16px 标签高度，标签底边与组件底部对齐；隐藏 X 轴时绘图区延伸到组件底部。

• hover 规则: 柱体 hover 使用 StyleSpec.md §2.4 的 overlay 机制，不改写柱体本身颜色。视觉透明度为 40% 及以上的实心柱按 filled Button hover 规则叠加 StaticWhite/20%；视觉透明度低于 40% 的浅透明柱按浅黑 hover 档位叠加 Black/4%。overlay 后层 10% 与多段式浅色段都会走 Black/4% overlay。

• hover label: 默认 hover / focus 柱体时在柱体上方 4px 显示数值 label，不因触及绘图区顶边改变位置。字号 12px、常规体，颜色默认为 Black/100%。stack 只在最顶段显示整根堆叠柱的总值，hover 任意分段都指向这一份总值；其他模式仍显示对应柱值。数字格式消费 NumberFormats.md，默认非整数显示 2 位小数。alwaysShowHoverLabel 可让数值 label 常显；出现动效播放时，label 数值跟随当前整柱高度比例实时变化，从 80% 对应值变化到完整值。

• hover panel: 面板 label 与下方数值行区域保留既有 2px 设计基准间距。HoverPanel 使用共享三列布局；圆点—名称优先 --gap-1，名称—数值优先 --gap-2，两处均至少保留 4 CSS px，并跟随 LTR / RTL 逻辑方向。默认 16px 根字号下仍为 4px / 8px，较大 Token 保留；面板纵向分区和图表中心注释不套用此下限。

• 出现动效: 所有分类单元共享一条 BarChart 出现动效时间轴；柱体初始显示为目标高度 / 宽度的 80%，再从左到右依次升高到 100%。相邻分类单元的启动间隔固定；整条时间轴应用 easeOut 缓动；单柱升高使用 Frame 默认 morph 时长 300ms 作为基准，每个分类单元的变高进度单独应用 easeOut 缓动，并且越靠右的单元升高时长越长。stack 模式把一个分类单元内的所有分段看作同一个动效整体：同一单元内的所有分段共享同一局部进度，从各自 80% 高度一起升高到 100%，不分别启动独立变高动效；segmentGap 在动效过程中保持固定像素间距，segmentGap=0 时始终无间距。

2.1 Props

其余未声明属性会透传给根层 Frame。

2.2 组件方法

2.3 数据结构

type BarChartOrientation = "vertical" | "horizontal";type BarChartMode = "single" | "stack" | "overlay" | "group"; interface BarChartSegment {  name?: string;  value: number;  color?: BarChartColor;  valueFormat?: NumberFormatOptions;} interface BarChartBar {  name?: string;  value: number;  color?: BarChartColor;  valueFormat?: NumberFormatOptions;} interface BarChartItem {  name: string;  value?: number;  color?: BarChartColor;  valueFormat?: NumberFormatOptions;  segments?: BarChartSegment[];  bars?: BarChartBar[];  backgroundValue?: number;  backgroundName?: string;}

mode="overlay" 的推荐数据是 data[].bars，每个分类传入两项真实数据柱：

旧字段 value/backgroundValue/backgroundName 仅在未传 bars 时生效：backgroundValue 指定真实后层值，名称使用 backgroundName ?? name；value 指定前层值，名称使用 name。未传 backgroundValue 时只渲染前层，不再复制前层值生成一根虚构后层。新代码应使用 bars；其他模式忽略 backgroundValue/backgroundName。

<BarChart mode="overlay" data={[  { name: 'Organic search', bars: [{ name: 'Previous quarter', value: 8400 }, { name: 'Current quarter', value: 10200 }] },  { name: 'Direct traffic', bars: [{ name: 'Previous quarter', value: 7600 }, { name: 'Current quarter', value: 6800 }] },  { name: 'Referrals', bars: [{ name: 'Previous quarter', value: 4200 }, { name: 'Current quarter', value: 5100 }] }]} />

数值格式优先级：labelFormatter → segment/bar.valueFormat → item.valueFormat → 组件 valueFormat → NumberFormatContext → NumberFormats 默认值。

颜色优先级：

• single: data[i].color → colors[i] → colorMode。

• stack: segments[j].color → data[i].color → monochromeFade；未自定义时使用同一颜色的透明度梯度。

• overlay: 后层和前层默认使用同一颜色，后层透明度固定为 0.1。

• group: bars[j].color → data[i].color → colors[j] → colorMode。

颜色支持 SnowUI 语意色、普通 CSS 颜色、CSS 变量、linear-gradient(...) 字符串和渐变对象。

布局模型

主布局模型:内禀原子布局。

• 根层为 Frame，内部为单个 SVG 绘图区。

• 根层 CSS 尺寸由 width / height 决定，SVG 坐标算法使用根层最终实测尺寸；width="100%" 可直接 Fill，无需页面监听容器后回传像素宽度。

• orientation="vertical" 时分类轴为横向 cell，柱位于 cell 中心；orientation="horizontal" 时分类轴为纵向 cell。

• Y 轴标签区宽度由全部可见 Y label 中最宽文本的实际 SVG 渲染宽度决定，不使用固定 bounds 或字符数量估算；label 右边缘与绘图区起点间距固定为 12px。

• 自动 domain 上限直接使用当前数据最大值；nice ticks 只生成到不高于该值的最后一个易读刻度。最高柱可以高于最后一条网格线，顶部仅由 8px / 16px 内容安全区控制。显式 yMax 或 yTicks 不受此自动规则改写。

• 绘图区顶部由共享内容感知规则计算：普通柱 8px，纵向数值 Y 轴 16px；二者取最大值。数值 label 不增加该值，继续保持柱顶上方 4px 的位置，必要时可溢出绘图区顶边。横向柱的数值 label 位于柱右侧，同样不额外增加顶部安全区。有 X 轴时 bottom=24px，只包含 8px label 间距和 16px label 高度；无 X 轴时 bottom=0。

• 单元内部规则：

  • single: 一个单元一根柱。

  • stack: 一个单元一根多段柱；segmentGap=0 时中间段无间隔并只在整体首尾保留圆角；segmentGap>0 时每段独立圆角；数值 label 只属于最顶段，内容为所有分段总和。

  • overlay: 一个单元两层同轴柱，后层 10%，前层 100%。

  • group: 一个单元多根并排柱，粗细统一，颜色可逐根定义。

• 响应式收窄时先压缩柱粗细至 2px；同分类并排柱间距和相邻分类柱间距都保留至少 4px。横坐标和常驻顶部数值分别按自身文本需求抽稀，柱体数量、数据 domain、命中 cell 和动效顺序保持完整。

• 不接入三槽位协议，不承担通用子元素排列。

详见 LayoutProtocol.md §12.7（源码参考：specs/maintainers/LayoutProtocol.md）。

无障碍与 Frame 集成

• 交互根使用 role="group" 和 aria-label="柱状图"（zh-CN 默认，随 locale 切换），让内部命中项保留独立语义。

• 每根柱 / 每个分段有独立透明命中层，使用 role="button"、tabindex="0" 和包含名称与数值的 aria-label。

• 独立使用或接入 ChartGroup 时均支持 hoverMode="cell"；cell 命中区按分类中心左右半格覆盖绘图区，同一分类单元的所有单柱、多段、相叠层或并排柱一起响应 hover。

• loading 保留完整画布与坐标结构，只把柱体恢复到出现动效起点；根 Frame 明确关闭 Skeleton。显式空 data={[]} 不回退默认演示数据，可配合 xLabels、yMin、yMax 先建立最终坐标。

• 显式传入 enableResponsive / enableContext / enableScaleObserver / enableDefaultMotion。

• class、style 与未声明属性透传到根层 Frame。

图层与动效

SVG 图层从下到上为：

1. defs: 颜色渐变。

2. grid / axis layer: 网格线和 x 轴基线。

3. base layer: showBaseLayer=true 时绘制最终尺寸占位柱，fill-opacity=0.04；默认不渲染。

4. series layer: 真实柱体。

5. hit layer: 完整命中区域。

6. axis label layer: X / Y 轴文本。

出现动效 API 与 ChartSpec.md §9 保持一致。所有柱共享同一张图表级时间轴，分类单元按顺序启动；单元内部的并排柱、堆叠段或相叠层使用同一局部进度。柱体出现形式为高度 / 宽度补齐：纵向柱先显示目标高度的 80%，再从顶部向上补齐到 100%；横向柱先显示目标宽度的 80%，再向右补齐到 100%。相邻分类单元的启动间隔固定；整条时间轴先应用 easeOut 缓动；单元升高持续时长按分类顺序逐步拉长，让越靠右的单元升高速度越慢。stack 模式中，一个分类单元内的所有分段共享同一个局部进度，因此 BC-02 / BC-03 不会出现每段分别启动的节奏；在任意时刻，底段 / 中段 / 顶段都按各自目标高度的同一比例同步变高。segmentGap 只作用在相邻分段边界上，动效过程中保持固定像素值；segmentGap=0 时相邻分段始终贴合无间距。appearanceDuration 仍可覆盖整段时间轴的播放速度。常显或 hover label 的数值直接使用当前柱高比例计算；stack 使用整柱总值，从总值的当前比例补到最终总值。