BarChart

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

我们正在让 SnowUI 组件成为 AI 对话中可直接操作的界面。目前对话交互能力仍在建设中；本页展示网站用法，支持的对话平台与组件版本将在验证后公布。 AI 对话内生成和使用 SnowUI 界面完全免费，不属于项目，不占项目或开发者席位额度，无需 SnowUI 注册、激活或付费证明。

如何使用

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

传入业务 data；省略 data 会显示内置示例数据。mode 控制单柱、分组、堆叠等形态，具体结构见 API 与数据结构。
loading 保留图表占位并暂停数据交互；HoverPanel 默认开启。图表颜色通过 colors / colorMode 配置。
根默认可访问名称随 LocaleProvider 切换，使用 barChart.name；显式 aria-label 优先。数据单元格组使用 barChart.cells。业务名称、数据值与数字格式保持调用方内容。

导入

import { BarChart } from '@snowui-design-system/components';

用法

细分段柱形

紧凑的月度分布图，内嵌图例。

顶部锚定 HoverPanel

HoverPanel 锚定在选中柱形上方。

圆角堆叠柱形

HoverPanel 跟随指针。

季度流量对比

按来源展示网站访问量：上季度在后，本季度在前。adaptiveContrast 使重叠柱形上的数值保持可读；面板固定在右上角。

分组柱形

HoverPanel 锚定在选中组旁边。

水平分组柱形

HoverPanel 固定在绘图区右上角向内 8px 处。

表面样式 HoverPanel

HoverPanel 跟随指针。

API 参考

属性	类型	默认值	示例	描述
`data`	`BarChartItem[]`	`DEFAULT_DATA`	`data={data}`	分类数据；overlay 推荐用每类 bars 的前两项表示后层与前层，名称、数值、颜色和数字格式分别配置，详见数据结构。默认行为：内置默认数据。
`orientation`	`BarChartOrientation`	`"vertical"`	`orientation={value}`	图表方向
`mode`	`BarChartMode`	`"single"`	`mode={value}`	单元内部柱模式
`width`	`number \| string`	`800`	`width="Example"`	图表整体宽度；支持 `100%`，内部按最终显示宽度重算几何
`height`	`number \| string`	`400`	`height="Example"`	图表整体高度；内部按最终显示高度重算几何
`barWidth`	`number \| string`	`32`	`barWidth="Example"`	单根柱粗细；纵向时为宽度，横向时为高度；响应式下限 `2px`
`barGap`	`number \| string`	`4`	`barGap="Example"`	`group` 模式中同一单元内相邻柱间距；下限 `4px`
`groupGap`	`number \| string`	`20`	`groupGap="Example"`	分类单元内容与 cell 边缘的预留间距；下限 `4px`
`segmentGap`	`number \| string`	`0`	`segmentGap="Example"`	`stack` 模式中分段间隔；`0` 表示无间隔
`cornerRadius`	`number \| string`	`8`	`cornerRadius="Example"`	柱圆角大小
`roundedStart`	`boolean`	`true`	`roundedStart`	是否保留起点端圆角；纵向为底部，横向为左侧
`roundedEnd`	`boolean`	`true`	`roundedEnd`	是否保留终点端圆角；纵向为顶部，横向为右侧
`xLabels`	`string[]`	`—`	`xLabels={xLabels}`	分类 label 覆盖；未传时使用 `ChartGroup.xLabels` 或 `data[].name`
`yMin`	`number`	`—`	`yMin={42}`	数值轴 domain 最小值默认行为：自动 / 继承 `ChartGroup`。
`yMax`	`number`	`—`	`yMax={42}`	数值轴 domain 最大值；自动时等于实际最大数据值，不向上取整默认行为：自动 / 继承 `ChartGroup`。
`yTicks`	`number[]`	`—`	`yTicks={yTicks}`	数值轴刻度默认行为：自动 nice ticks / 继承 `ChartGroup`。
`yTickCount`	`number`	`—`	`yTickCount={42}`	自动 tick 目标数量
`yTickFormatter`	`(value: number) => string`	`—`	`yTickFormatter={(value) => { /* handle value */ }}`	数值轴 label 格式化默认行为：K 格式 / 继承 `ChartGroup`。
`showXAxis`	`boolean`	`—`	`showXAxis`	是否显示底部轴线与底部 label
`showYAxis`	`boolean`	`—`	`showYAxis`	是否显示左侧 label
`showGrid`	`boolean`	`—`	`showGrid`	是否显示网格线
`showGuides`	`boolean`	`—`	`showGuides`	保留 Chart API 命名；当前不绘制额外 guide
`showHoverLabel`	`boolean`	`—`	`showHoverLabel`	hover / focus 柱体时是否显示数值 label；当 `showHoverPanel=true` 且未显式传入时实际渲染默认关闭默认行为：按 `showHoverPanel` 推导。
`alwaysShowHoverLabel`	`boolean`	`false`	`alwaysShowHoverLabel`	是否让数值 label 一直显示；与 `showHoverPanel` 同时开启时允许同时显示
`adaptiveContrast`	`boolean`	`—`	`adaptiveContrast`	自适应黑白对比：按纯色宿主背景与同原点叠加柱体的明暗切换黑色数值；子图显式值优先，彩色序列与彩色节点不改色。明暗分界为 sRGB 灰度 0.5，随当前柱体形状和透明度变化；不支持背景图片或跨图坐标变换。默认开启，可显式关闭；由 Adaptive Contrast 共享能力实现。默认行为：继承 ChartGroup，否则 `true`。
`showHoverPanel`	`boolean`	`true`	`showHoverPanel`	是否开启 Chart hover 面板，内容按当前柱 / cell 自动生成；默认开启，hover / focus 时显示面板；设为 false 时回到数值 hover label，显式 showHoverLabel 优先
`hoverPanelVariant`	`ChartHoverPanelVariant`	`"light"`	`hoverPanelVariant={value}`	hover 面板视觉样式
`hoverPanelPlacement`	`ChartHoverPanelPlacement`	`"pointer"`	`hoverPanelPlacement={value}`	hover 面板定位；支持 anchor / pointer / pin 位置
`showHoverPanelLabel`	`boolean`	`false`	`showHoverPanelLabel`	是否在 hover 面板顶部显示当前分类 label
`hoverMode`	`ChartGroupHoverMode`	`—`	`hoverMode={value}`	hover 命中模式；`cell` 时按分类中心左右半格生成整格命中区，同一分类单元内的所有柱 / 分段一起响应
`activeCellIndex`	`number \| null`	`—`	`activeCellIndex={42}`	受控当前 hover 分类单元；未传时可继承 `ChartGroup`
`onCellHoverChange`	`(index: number \| null) => void`	`—`	`onCellHoverChange={(value) => { /* handle value */ }}`	分类单元 hover 变化回调
`valueFormat`	`NumberFormatOptions`	`—`	`valueFormat={value}`	柱体数值 label 的组件级数字格式；可设置 `notation: "auto"` / `"compact"` 使用英文 `k/m/b/t` 缩写默认行为：NumberFormats 默认。
`labelFormatter`	`( value: number, context: BarChartValueLabelContext, ) => string`	`—`	`labelFormatter={(value) => { /* handle value */ }}`	柱体数值 label 自定义格式化；优先级高于全局、组件和数据项 `valueFormat`
`xLabelAutoCull`	`boolean`	`—`	`xLabelAutoCull`	按最终显示尺寸减少分类 label；完整文字间距最小 `4px`，首尾仍放不下时全部隐藏；不删除柱体、坐标轴或命中 cell
`xMaxLabelCount`	`number`	`—`	`xMaxLabelCount={42}`	分类 label 最大显示数量默认行为：- / 继承 `ChartGroup`。
`valueLabelAutoCull`	`boolean`	`true`	`valueLabelAutoCull`	`alwaysShowHoverLabel` 常驻数值是否按最终显示尺寸自动抽稀；hover / focus 数值不受影响
`valueMaxLabelCount`	`number`	`—`	`valueMaxLabelCount={42}`	常驻顶部数值最大显示数量
`yLabelAutoCull`	`boolean`	`—`	`yLabelAutoCull`	是否自动减少数值轴 label
`yMaxLabelCount`	`number`	`—`	`yMaxLabelCount={42}`	数值轴 label 最大显示数量默认行为：- / 继承 `ChartGroup`。
`colors`	`(BarChartColor \| undefined)[]`	`—`	`colors={colors}`	调色板；空项回退当前 `colorMode`
`colorMode`	`BarChartColorMode`	`"sequence"`	`colorMode={value}`	Chart 通用颜色模式
`color`	`BarChartColor`	`—`	`color={value}`	单色模式主色
`monochromeColor`	`BarChartColor`	`"Primary"`	`monochromeColor={value}`	单色渐浅来源
`mutedMonochromeColor`	`BarChartColor`	`"Black4"`	`mutedMonochromeColor={value}`	单色来源
`showBaseLayer`	`boolean`	`false`	`showBaseLayer`	是否显示最终尺寸的同色轮廓（影子 / 占位底层），默认不渲染；开启后以 4% 不透明度绘制，不参与出现动效，不改变真实图形、命中区域或时间轴。与 overlay 的后层数据柱无关；横向柱按最终宽度绘制。
`appearMotion`	`boolean`	`true`	`appearMotion`	是否启用出现动效
`appearOnView`	`boolean`	`true`	`appearOnView`	是否进入视口后自动播放；同源 iframe 中按最外层同源页面的真实位置判断
`appearanceProgress`	`number`	`—`	`appearanceProgress={42}`	受控出现进度
`defaultAppearanceProgress`	`number`	`0`	`defaultAppearanceProgress={42}`	非受控初始出现进度
`appearanceDuration`	`number`	`—`	`appearanceDuration={42}`	自动播放总时长覆盖
`appearAnchorId`	`string`	`—`	`appearAnchorId="Example"`	动效触发锚点 ID
`appearAnchorPoint`	`AnchorPoint`	`"top"`	`appearAnchorPoint={value}`	锚点触发位置
`appearViewportPoint`	`number \| "top" \| "center" \| "bottom"`	`0.7`	`appearViewportPoint={42}`	视口触发位置
`scrollAppearance`	`boolean \| { distance?: number \| string }`	`false`	`scrollAppearance={scrollAppearanceOptions}`	是否启用滚动时间轴；同源 iframe 同时响应外层页面滚动
`scrollAppearanceDistance`	`number \| string`	`320`	`scrollAppearanceDistance="Example"`	滚动映射距离
`onAppearanceProgressChange`	`(progress: number) => void`	`—`	`onAppearanceProgressChange={(value) => { /* handle value */ }}`	出现进度变化回调
`loading`	`boolean`	`—`	`loading`	数据等待状态。保持声明的画布尺寸、坐标轴和网格，将柱体固定在出现动效起点并暂停交互；变为 false 后按当前视口条件播放出现动效。图表不渲染 Skeleton，也会读取上层 Frame 的 loading 上下文。
`children`	`Snippet`	`—`	`<BarChart>Content</BarChart>`	图表主体后的自定义内容，无参数；不会替换坐标轴或数据系列。
`class`	`string`	`""`	`class="my-component"`	根层附加 class
`style`	`string`	`""`	`style="width: 100%;"`	根层附加 style
`enableResponsive`	`boolean`	`true`	`enableResponsive`	是否启用 Frame responsive
`enableContext`	`boolean`	`true`	`enableContext`	是否启用 Frame context
`enableScaleObserver`	`boolean`	`false`	`enableScaleObserver`	是否启用 Frame scale observer
`enableDefaultMotion`	`boolean`	`true`	`enableDefaultMotion`	是否启用 Frame 默认动效