Spinner 加载指示器

一个不确定时长的等待标记。

HeadlessStylesVueReactWeb Components

用法

root 是 role=status 的活区，旋转图形由皮肤绘制在伪元素上；label 给出该处在等待什么

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

组件结构

加粗的是必需部件。

data-scope="spinner"：root · label

示例

尺寸

size 只改变直径，默认档 md 不输出 data-size

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

可见文案

label 部件未写内容时显示解析后的 label，屏幕上看到的与读屏朗读的因此是同一段文字

正在加载数据正在提交表单

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

颜色

tone 只更换圆环起始边一段的颜色，轨道保持中性描边，旋转时才能看出差别

brandneutralsuccesswarningdangerinfo

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

覆盖等待中的内容

旋转指示浮在内容上方，容器同时报告 aria-busy，可见的与可朗读的是同一件事

本季新增客户 128 家，环比增长 12%。

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

变体

默认渐隐弧，另有 ring 整圈与 dots 三点

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

延迟露面

delay 让转圈挂载后等一段时间才出现：快请求在这之前就回来，转圈从头到尾不露面，不会闪一下

（还没查询）

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

竖排配文

orientation="vertical" 时转圈在上、配文在下居中，适合整块区域的等待

正在加载数据

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

设计指引

何时使用

• 时长未知且没有版面可占位。
• 局部区域正在获取数据，或按钮上的在途标记。

何时不用

• 版面可预测时，使用骨架屏，它让用户提前看到结构。
• 进度确定时，使用进度条。
• 整页导航时，使用加载条。

特性

• 可以配可见文案，也可以只通过 translations 提供给读屏。
• 可以与宿主遮罩组合，盖住等待中的内容。
• 默认使用渐隐弧；也可显式选择整圈轨道或三点。转圈取品牌色，环档是一段 270° 的弧、不画轨道。
• 配文取品牌色正文字号、中等字重；orientation="vertical" 时转圈在上、配文在下居中，适合整块区域的等待。
• delay 让转圈挂载后等一段时间才露面：请求在这之前回来、转圈被卸掉时它从头到尾不出现，快请求不再闪一下。等待期间整块藏起但保留位置，读屏也读不到。

组合

• 放入按钮的 indicator 部件；覆盖卡片或表格。

最佳实践

• 等待超过几秒时配上文字说明正在做什么。
• 遮罩形态下阻止交互，否则用户会重复点击。

反模式

• 一个页面内同时显示多个加载指示器。
• 用它代替可预测版面的骨架屏。

API 参考

产物

层	值
自定义元素	<xh-spinner>
Vue 组件	XhSpinner XhSpinnerLabel
状态机	spinnerMachine
皮肤	@xihan-ui/styles/spinner.css

Props

属性	类型	必填	说明
delay	number		挂载后等多少毫秒才露面，默认 0 即刻露面。等待期间 root 投影 data-state="hidden"， 皮肤按它把整块藏起、仍占着位置，读屏也读不到；加载在这之前结束、转圈被卸掉时它从头到尾不出现。 露面之后不再回到等待。
label	string		该处的可及名，写在 root 上。 label 部件显示的应当是同一段文案：aria-label 会覆盖节点中的文字，两者不一致时 读屏朗读的与屏幕上看到的不匹配。
orientation	Orientation		转圈与配文的排布，默认 horizontal：horizontal 并排、适合随文与行内； vertical 转圈在上、配文在下居中，适合整块区域的等待。
size	Size		直径档位，默认 md；默认档不输出 data-size。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定使用哪族颜色
translations	Partial<SpinnerTranslations>
variant	SpinnerVariant		形态，默认 arc。

状态

公开状态写入 data-state。

部件	取值
root	'visible' | 'hidden'

以下名称仅用于内部状态机。

状态：waiting · visible

connect API

getXxxProps() 返回对应部件的宿主属性。

成员	类型	说明
label	string	解析后的文案：label → translations.label → en-US 语言包。
visible	boolean	已经露面；等待 delay 期间为 false。
getRootProps	() => T['element']
getLabelProps	() => T['element']

无障碍

键盘

规格出处：W3C APG

无键盘交互（不接收焦点，或焦点行为完全由原生元素提供）。

ARIA

以下属性由 connect 生成。

部件	属性	值
root	aria-label	resolveLabel(props)
root	aria-live	'polite'
root	role	'status'

样式参考

皮肤

@xihan-ui/styles/spinner.css 按 [data-scope="spinner"][data-part="root"] 部件选择器书写，发布产物以挂载类 .xh-scope-spinner 代替其中的 data-scope（特异性相同），位于 xihan.components 与 xihan.motion 层。覆盖样式使用 xihan.overrides，部件选择器照常可用。

forced-colors: active 下另有一套规则：颜色交给系统，边框与状态标记改用系统色关键字。

数据属性

由 connect 生成；条件不成立时不输出无值属性。

部件	属性	值
root	data-orientation	props.orientation
root	data-size	props.size
root	data-state	'visible' | 'hidden'
root	data-tone	props.tone
root	data-variant	props.variant

CSS 变量

本组件公开覆盖槽由独立皮肤的实际消费位生成；默认来源、作用部件和状态均与 CSS 同源。

变量	部件	CSS 属性	状态	默认来源	说明
--xh-spinner-duration	root	animation	default variant=dots	--xh-motion-loop-spin	spinner 的 root 部件 animation 覆盖槽。
--xh-spinner-fg	root	background border border-color	@media (prefers-reduced-motion: reduce) @media print default motion=reduce tone variant=arc variant=dots where([data-motion='reduce'])	--xh-_tone --xh-fg-brand	spinner 的 root 部件 background、border、border-color 覆盖槽。
--xh-spinner-gap	root	gap	default orientation=vertical	--xh-control-gap-md --xh-space-1_5	spinner 的 root 部件 gap 覆盖槽。
--xh-spinner-label-fg	label	color	default	--xh-fg-brand	spinner 的 label 部件 color 覆盖槽。
--xh-spinner-label-size	label	font-size	default	--xh-text-body-size	spinner 的 label 部件 font-size 覆盖槽。
--xh-spinner-label-weight	label	font-weight	default	--xh-font-weight-medium	spinner 的 label 部件 font-weight 覆盖槽。
--xh-spinner-radius	root	border-radius	@media (forced-colors: active) default tone variant=arc variant=dots	--xh-shape-circle	spinner 的 root 部件 border-radius 覆盖槽。
--xh-spinner-size	root	block-size inline-size	default	--xh-glyph-size-md	spinner 的 root 部件 block-size、inline-size 覆盖槽。
--xh-spinner-thickness	root	-webkit-mask border mask	@media (forced-colors: active) default tone variant=arc variant=dots	--xh-stroke-thick	spinner 的 root 部件 -webkit-mask、border、mask 覆盖槽。
--xh-spinner-track	root	border-block-start-color	default tone	transparent	spinner 的 root 部件 border-block-start-color 覆盖槽。

动效

动效角色：状态 · 循环（见动效规范）。

可覆盖的动效槽：--xh-spinner-duration。

关键帧 xh-spinner-dots 随皮肤自带，不引用别处文件里的名字；共享关键帧 xh-spin 由 family/motion.css 提供，皮肤 @import 它，单独引入仍成立；opacity 走 transition 过渡。时长与缓动读动效令牌，改令牌即改全局节奏。

prefers-reduced-motion: reduce 下本组件另有降级规则。

RTL

只认物理方向的量乘 --xh-direction-sign 换向，按就近的 dir 走。