CircularChart 使用手册

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

组件介绍

用圆环或饼图展示数据占比，支持分段、圆角、环厚与悬停强调，适合构成分析和比例概览。

使用选择

用于展示占比、环形或饼图数据。目标完成度可按语义选择 GaugeChart 或 Progress；颜色与标签使用公开配置。

• data 使用 name 与有限正 value；只显示前 maxItems 个有效项，占比分母为这些显示项之和。显式空数组展示空图。

• 推荐用数字 size；字符串几何只取数值部分，不能依赖百分比或 CSS 变量完成自适应。中心内容用公开 center-label / segment-value / segment-name 角色。

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

快速开始

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

<script lang="ts">	import { Button, Frame, Icon, Text } from '@snowui-design-system/components';	import { DotCircle } from '@snowui-design-system/resource-svelte';	import { CircularChart } from '@snowui-design-system/components';	// Illustrative SnowUI site visits over the last 30 days; these are not actual statistics.	const channels = [	    { name: 'Search', value: 12840, color: 'var(--primary)' },	    { name: 'Direct', value: 8560, color: 'var(--secondary-purple)' },	    { name: 'GitHub', value: 5350, color: 'var(--secondary-cyan)' },	    { name: 'Figma', value: 4280, color: 'var(--secondary-mint)' },	    { name: 'Community', value: 3210, color: 'var(--secondary-green)' }	];	const total = channels.reduce((sum, item) => sum + item.value, 0);	let trafficChart: { replay: () => void; reverseAppearance: () => void } | undefined;</script> <div style="display: flex; flex-direction: column; align-items: center; width: var(--size-full); gap: var(--gap-4) var(--gap-3);">    <div style="display: flex; align-items: center; justify-content: center; flex-wrap: wrap; min-width: 0; max-width: var(--size-full); gap: var(--gap-4) var(--gap-7);">        <CircularChart bind:this={trafficChart} data={channels} ringThickness={48} appearOnView defaultAppearanceProgress={0} role="group" aria-label="SnowUI website visits by source, sample last 30 days" />        <div style="display: flex; flex-direction: column; gap: var(--gap-3);">            <div style="display: flex; flex-direction: column; gap: var(--gap-0);">                <Text style="font-size: var(--text-18); line-height: var(--leading-18); color: var(--black-100); font-weight: 600;">Website traffic</Text>                <Text style="font-size: var(--text-12); line-height: var(--leading-12); color: var(--black-40);">Sample · last 30 days · {total.toLocaleString('en-US')} visits</Text>            </div>            <div style="display: grid; grid-template-columns: auto auto; align-items: center; gap: var(--gap-2) var(--gap-6);">    {#each channels as item}        <Frame singleLine gap={0}><Icon as="leading" size={12} style={`color: ${item.color};`}><DotCircle weight="fill" /></Icon><Text lines={1} style="font-size: var(--text-14); line-height: var(--leading-14); color: var(--black-100);">{item.name}</Text></Frame>        <Text style="font-size: var(--text-14); line-height: var(--leading-14); color: var(--black-100); text-align: right; font-variant-numeric: tabular-nums;">{item.value.toLocaleString('en-US')}</Text>    {/each}</div>        </div>    </div>    <div style="display: flex; align-items: center; justify-content: center; flex-wrap: wrap; gap: var(--gap-4) var(--gap-3);">        <Button onclick={() => trafficChart?.replay()}>Replay animation</Button>        <Button onclick={() => trafficChart?.reverseAppearance()}>Reverse animation</Button>    </div></div>

API

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

使用边界与详细说明

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

设计原则

• 专业图表组件：当前维护位置为 components/src/components/；该目录是迁移期技术位置。全部组件的运行包与原始源码均可免费获取；用途、项目、席位及生产使用权益按 LICENSE 执行，不按高级功能划分组件。

• 最多 10 项:默认 maxItems=10。颜色只使用 primary 与 9 个 secondary-* token，10 项后颜色会重复且图表辨识度下降，因此组件默认截断到 10 项。

• 颜色模式:默认 colorMode="sequence" 按 primary → secondary-purple → secondary-cyan → secondary-mint → secondary-green → secondary-indigo → secondary-blue → secondary-yellow → secondary-orange → secondary-red 循环；monochromeFade 使用 Primary 从 100% 均匀递减到最后一项 20%；monochrome 默认所有扇区使用 Black4。每个数据项可通过 color 单独定义扇区颜色；colors 可作为按 index 的调色板覆盖入口，留空项回退当前颜色模式。

• 几何缩放:cornerRadius 与 separatorWidth 的数值都是 160x160 图表下的设计基准值，组件会按实际 size / 160 等比缩放。auto 使用默认基准值：圆角 4、间隔 2。

• Hover 强调:hover / focus 当前项时，扇区不位移，仅外半径缓动增加 hoverThicknessGrowth，默认向外增厚 4px；中心标签上方显示百分比，下方显示当前项名称。

2.1 数据与形态

• 支持圆环图与实心饼图：ringThickness 小于外半径时为圆环，ringThickness >= outerRadius 时内半径归零并形成实心饼图。

• 支持最多 10 个扇区：maxItems 默认 10，内部上限固定为 10，超出项会被截断。

• 自动过滤无效数据：value <= 0 或非数字项不参与渲染；显式空数组或全部无效时渲染空图表，只有省略 data 时使用内置示例数据。

• 支持尺寸、环厚、圆角、隔断和 hover 外侧增厚调整：数字值按 px 语义写入组件私有 CSS 变量。

• 支持 160x160 基准几何缩放：cornerRadius 与 separatorWidth 的传入数值都是设计基准值，实际渲染按 size / 160 等比放大或缩小。

2.2 扇区绘制

• 扇区路径包含外圆弧、内圆弧和头尾切线圆角，圆角跟随真实扇区形状生成，不依赖后期裁切。

• 扇区之间的透明间隔在 path 几何阶段生成：separatorWidth 会换算为 d3-shape 的 padAngle，并配合 padRadius 收缩内外圆弧。不绘制白色分隔线，也不使用后置 gap mask 挖空扇区。

• 圆角仍由收缩后的扇区 path 生成，因此贯穿环厚的透明间隔与端部圆角可以同时成立。

• showBaseLayer=true 时底层绘制一层同色 4% 透明度占位扇区，默认不绘制，不参与出现动效；真实填充层在其上方播放。

• 最上层使用完整扇区 path 作为透明命中层，保证 hover / focus 的交互范围稳定。

2.3 颜色能力

• 默认颜色顺序为 Primary、Purple、Cyan、Mint、Green、Indigo、Blue、Yellow、Orange、Red。

• 每个扇区可通过 data[i].color 单独定义颜色；未定义颜色的扇区继续使用默认颜色序列。

• colors 可作为整组调色板覆盖入口，并允许数组项为 undefined，空项会回退当前 colorMode 对应颜色。

• 支持 Chart 通用三种颜色模式：sequence 默认色序、monochromeFade 单色渐浅、monochrome 单色。三种模式都支持 data[i].color 与 colors[i] 指定扇区自定义颜色。

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

• 不直接支持 .bg-gradient-blue 这类背景工具类名；SVG 扇区使用 fill，背景类的 background / background-image 不会被 path 消费。

2.4 动效能力

• 支持首次进入视口自动播放出现动效，可通过 appearOnView 关闭。

• 支持 8 个出现起始方向：top / top-right / right / bottom-right / bottom / bottom-left / left / top-left。

• 支持滚动条时间轴：scrollAppearance 开启后，滚动距离直接映射到 appearanceProgress。

• 支持受控时间轴：外部传入 appearanceProgress 后，组件只根据该进度渲染，不自行播放。

• 支持非受控方法：replay() 重新填充，resetAppearance() 重置，reverseAppearance() 反向回退。

• 填充层与透明度层同时启动：填充完成后下一个扇区即可启动，透明度补齐独立继续，不阻塞后续扇区。

• 支持反向时间轴：appearanceProgress 从 1 回到 0 时，填充宽度与透明度按同一公式回退。

2.5 交互与无障碍

• hover / focus 当前扇区时，扇区外半径向外增厚，内半径不变，扇区不发生位移。

• hover / focus 当前扇区时，中心标签显示当前项百分比和名称，默认百分比在上、名称在下。

• labelFormatter 可自定义中心标签内容，并支持用 \n 拆成两行；第一行按数值样式渲染，第二行按名称样式渲染。

• 可传入直接子元素 <Text as="segment-value" /> / <Text as="segment-name" /> 自定义中心标签样式模板；组件会自动写入当前扇区的真实百分比和名称，出现任一角色子元素时不渲染默认中心标签。

• showCenterLabel={false} 可关闭中心标签，同时关闭外部写入的中心标签角色内容。

• 根使用 role="group" 和 aria-label="圆形图表"（zh-CN 默认，随 locale 切换）；SVG 不隐藏可聚焦扇区，每个扇区命中项以 role="button" 和包含名称、百分比的独立 aria-label 暴露给辅助技术。

• 扇区命中层可获得键盘焦点，focus 行为与 hover 一致；中心标签使用 aria-live="polite"。

2.6 Frame 集成

• 根层使用 Frame；loading 保留声明尺寸和中心内容，将扇区固定在出现动效起点并暂停交互。图表根层明确关闭 Skeleton，也会读取上层 Frame 的 loading 上下文。

• 支持 enableResponsive、enableContext、enableScaleObserver、enableDefaultMotion 透传到 Frame。

• class、style 和其余未声明属性会透传给根层 Frame。

• 图表尺寸由 SVG 几何算法决定，作为外部布局子项时表现为 Hug。

3.1 Props

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

3.2 组件方法

3.3 数据结构

interface CircularChartItem {  name: string;  value: number;  color?: CircularChartColor;  percentFormat?: NumberFormatOptions;}

百分比数字格式优先级：labelFormatter（中心标签）→ item.percentFormat → 组件 percentFormat → NumberFormatContext → NumberFormats 默认值。扇区命中层 aria-label 不使用 labelFormatter，但会消费 percentFormat。

value <= 0 或非数字项会被过滤；显式空数组或全部无效时渲染空图表，省略 data 才使用内置示例数据。

type CircularChartColor = string | CircularChartGradient; interface CircularChartGradient {  type?: "linear";  angle?: number;  stops: (string | { color: string; offset?: number | string; opacity?: number })[];}

颜色优先级：data[i].color → colors[i] → colorMode 对应回退色。未定义颜色的扇区不会受其它扇区自定义颜色影响，继续使用当前颜色模式。渐变字符串支持 linear-gradient(135deg, #111111 0%, #6BE6D3 100%) 形式；渐变对象支持用 angle 和 stops 显式声明。

布局模型

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

• 根层为 Frame，内部本体层统一承载 SVG 绘图区与中心标签，负责等比缩放；HoverPanel 与本体层并列，保持原有尺寸。

• 图表尺寸由 size 与 SVG 几何算法决定；作为外部布局子项时表现为 Hug。

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

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

动效

6.1 出现动效起始方向

startDirection 支持 8 个方向：top / top-right / right / bottom-right / bottom / bottom-left / left / top-left。

判定规则：

1. 从圆心向 startDirection 发出射线。

2. 找到该射线命中的扇区。

3. 不论射线落在该扇区的哪个位置，动效都从该扇区自身起始边界开始。

4. 后续按顺时针方向逐扇区填充，直到所有扇区完成。

使用示例

<CircularChart  data={[    { name: "Search Engine", value: 1048 },    { name: "Direct", value: 735 },    { name: "Email", value: 580 },    { name: "Union Ads", value: 484 },    { name: "Video Ads", value: 300 }  ]}/>

<CircularChart  size={320}  ringThickness={88}  cornerRadius={16}  separatorWidth={4}  hoverThicknessGrowth={4}/>

上例中的 cornerRadius={16} 与 separatorWidth={4} 表示 160x160 图表下的设计基准值。实际尺寸为 320 时，最终呈现为 32px 圆角与 8px 间隔。

<CircularChart  size={220}  ringThickness={64}  data={[    {      name: "Primary Gradient",      value: 42,      color: "linear-gradient(135deg, var(--primary, #111111) 0%, var(--secondary-mint, #6BE6D3) 100%)"    },    { name: "Default Purple", value: 30 },    {      name: "Object Gradient",      value: 18,      color: {        angle: 45,        stops: [          "var(--secondary-purple, #B899EB) 0%",          "var(--secondary-cyan, #A0BCE8) 100%"        ]      }    },    { name: "Default Mint", value: 10 }  ]}/>

<CircularChart  data={[    { name: "Direct", value: 735 },    { name: "Email", value: 580 }  ]}>  <Text as="segment-value" class="text-18 font-bold text-black-100" />  <Text as="segment-name" class="text-14 text-black-40" /></CircularChart>

<CircularChart  bind:this={chart}  startDirection="left"  appearOnView={false}/> <Button onclick={() => chart.replay()}>重新填充</Button><Button onclick={() => chart.reverseAppearance()}>反向回退</Button>

 <CircularChart  size={220}  ringThickness={140}  cornerRadius={8}  separatorWidth={3}/>