定价

Spinner 使用手册

v1.2.3 · @snowui-design-system/components

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

组件介绍

以持续旋转的视觉提示表示加载中，提供圆环、辐条和胶囊三种形式，适合按钮与内容区域。

使用选择

用于等待状态的持续指示。能提供完成度时使用 Progress；已有按钮或表格加载态优先使用宿主内置 Spinner。

  • variant 选择等待图形；size 优先于父级尺寸，无上下文时为 16。

  • 不渲染 children；加载说明文字在外部组合。需要完成比例时改用 Progress。

  • 加载状态默认名称随LocaleProvider更新，显式aria-label优先；不会替调用方翻译外部加载说明。

快速开始

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

<script lang="ts">	import { Spinner, Text, Button } from '@snowui-design-system/components';</script> <div style="display: flex; align-items: center; gap: var(--gap-3);">	<Spinner aria-label="Loading components" />	<Text>Loading components…</Text></div>

API

关键字 类型 默认值 描述
variant SpinnerVariant "circle" 视觉变体风格
size ResourceSize — 尺寸（支持 12、16、20、24、28、32、40、48、80）；省略时优先继承父级 iconSize / size，无上下文时为 16
speed number 1 正数动画速度倍率；circle 基准周期 1000ms，spokes / pills 为 800ms，除以该倍率。非有限值或非正数回退为 1；显式 loopMotion 时序优先。
loopMotion LoopMotionConfig — 覆盖默认循环动画桥接配置；优先级高于 speed 推导出来的默认时长。若传入 preset，Spinner 仅消费其中的时序字段，不让 Frame 根节点重复旋转
children Snippet — 兼容 Frame 的类型声明；Spinner 使用内置动画图形，不渲染子内容。文字请在外部组合。

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

使用边界与详细说明

布局模型

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

  • Spinner 的根节点是由 size 与 variant 决定的内禀盒，作为其他布局子项时表现为 Hug。

  • circle / spokes / pills 的 SVG、mask、spoke、pill 动画层都是 Spinner 私有结构，不对外暴露 Leading / Content / Trailing 槽位。

  • Spinner 不提供 label 排列能力；需要“图标 + 文案”时由外部 Button、Frame 或 Text 组合负责。

  • loopMotion 只覆盖内部循环动效时序，不改变根布局模型。

关键字 (Keywords)

关键字 类型 默认值 描述
class string '' 自定义样式类 (如颜色)

Note on Color & Label

  • Color: Spinner 不提供 color 属性。它默认继承当前文本颜色 (currentColor)。如需修改颜色，请使用工具类：<Spinner class="snowui-text-blue-500" />。

  • Label: Spinner 不提供 label 属性。如需组合文字，请使用外部布局。

变体 (Variants)

变体名 描述
circle (默认) CSS Conic Gradient 实现的圆环，具有头尾透明度渐变效果
spokes 辐射线条，具有拖尾效果
pills 粗线条辐射，具有拖尾效果

1. 基础用法

默认显示 16px 的 circle 变体。

<Spinner />

2. 变体 (Variants)

<div class="flex gap-4">    <Spinner variant="circle" />    <Spinner variant="spokes" />    <Spinner variant="pills" /></div>

Spinner 样式覆盖

先阅读 完整 LICENSE；同任务、同版本、同范围去重。

优先用组件公开 Props 匹配合适样式，尽可能保留原有视觉。确需改写时按 样式选择与改写顺序 使用自己的 class（含项目已有 Tailwind）或实例 style。以下名称来自源码实际消费的公开 override；先核对目标作用域，不修改私有 DOM。采用 SnowUI Token 时选择正确类别，外部应用不被要求安装一方 utilities。

变量 用途与默认参考
--snowui-spinner-size-override 整体尺寸（尺寸 px，默认值见组件源码）

设计指南 · Token · 组合边界

Spinner 类型与状态

必填属性：无具名必填属性。

可双向绑定：本组件未声明具名双向绑定属性；状态更新通过公开回调或所属宿主处理。

继承声明：FrameProps。继承能力以基类公开文档为准；Omit 中的字段已排除，不能按基类原样使用。

共享 Frame API · 返回 API

以下为公开属性实际引用的类型声明，来自源码；Svelte Snippet 表示内容片段，ComponentProps 表示对应组件的 Props。

SpinnerVariant

来源：components/src/components/Spinner.svelte

type SpinnerVariant = "circle" | "spokes" | "pills";

ResourceSize

来源：components/src/context.ts

export type ResourceSize = 12 | 16 | 20 | 24 | 28 | 32 | 40 | 48 | 80;

LoopMotionConfig

来源：components/src/logic/frame-types.ts

export interface LoopMotionConfig {    /** 循环默认能力预设（启用 Frame 根节点完整循环动画） */    preset?: LoopMotionPreset;    /** 循环动画持续时间 (毫秒) */    duration?: number;    /** 循环动画缓动函数 */    easing?: MotionConfig["easing"];    /** 循环次数（默认 infinite） */    iterationCount?: number | "infinite" | (string & {});    /** 循环方向（默认 normal） */    direction?:        | "normal"        | "reverse"        | "alternate"        | "alternate-reverse";    /** 播放状态（默认 running） */    playState?: "running" | "paused";}

LoopMotionPreset

来源：components/src/logic/frame-types.ts

export type LoopMotionPreset = "rotateClockwise";

MotionConfig

来源：components/src/logic/motion-config.ts

export interface MotionConfig {    // === 变换属性 ===    /** 缩放比例 (1 = 100%) */    scale?: number | [number, number];    /** 水平位移 (px 或带单位字符串) */    x?: number | string | [number | string, number | string];    /** 垂直位移 (px 或带单位字符串) */    y?: number | string | [number | string, number | string];    /** 旋转角度 (度) */    rotate?: number | [number, number];    /** Y 轴旋转角度 (度)，用于正反面翻转 */    rotateY?: number | [number, number];    /** 透明度 (0-1) */    opacity?: number | [number, number];    /** 模糊半径（数字按 px 处理） */    blur?: number | string | [number | string, number | string];    /** 高度 (支持 "+20px" 增量语法) */    height?: number | string;    /** 宽度 */    width?: number | string;    /** 背景颜色 */    backgroundColor?: SnowUIColor | string;    /** 前景色（文字/图标颜色），用于颜色过渡 */    color?: SnowUIColor | string;     // === 时间参数 ===    /** 延迟 (毫秒) */    delay?: number;    /** 持续时间 (毫秒) */    duration?: number;    /** 缓动函数 */    easing?: EasingFunction;     // === 物理模拟 ===    /** 动效类型 */    type?: 'spring' | 'tween';    /** 弹簧刚度 (越大越硬) */    stiffness?: number;    /** 弹簧阻尼 (越大越快停止) */    damping?: number;    /** 弹簧质量 */    mass?: number;    /** 弹簧速度阈值 (低于此值视为停止) */    velocity?: number;     // === 组件引用 ===    /** 使用自定义组件作为动效载体 (如 FlowText, Spin) */    component?: any;     // === 编排控制 ===    /** 是否参与父组件编排 */    orchestrate?: boolean;}

SnowUIColor

来源：components/src/lib/color.ts

export type SnowUIColor = keyof typeof SNOWUI_COLOR_TOKENS;

EasingFunction

来源：components/src/logic/motion-config.ts

export type EasingFunction =    | 'linear'    | 'easeIn' | 'easeOut' | 'easeInOut'    | 'cubicIn' | 'cubicOut' | 'cubicInOut'    | 'quadIn' | 'quadOut' | 'quadInOut'    | 'quartIn' | 'quartOut' | 'quartInOut'    | 'quintIn' | 'quintOut' | 'quintInOut'    | 'sineIn' | 'sineOut' | 'sineInOut'    | 'expoIn' | 'expoOut' | 'expoInOut'    | 'circIn' | 'circOut' | 'circInOut'    | 'backIn' | 'backOut' | 'backInOut'    | 'elasticIn' | 'elasticOut' | 'elasticInOut'    | 'bounceIn' | 'bounceOut' | 'bounceInOut'    | (string & {});