定价

Progress 使用手册

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

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

组件介绍

以条形或圆形反馈任务进度，支持明确进度与不确定状态，适合上传、处理和加载过程。

使用选择

用于已知或未知完成度的进度反馈；未知进度使用 isIndeterminate。纯等待指示也可用 Spinner，业务数值仪表可选 GaugeChart。

  • value 是 0–100 的百分比；未知进度使用 isIndeterminate，不能用虚构百分比代替。

  • variant 选择 line / circle；circle 的 showLabel 生成标签，显式 children 替换默认标签。

快速开始

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

<script lang="ts">	import { Button, Frame, Progress, Text } from '@snowui-design-system/components';	let progress = $state(38);	const status = $derived(progress === 100 ? 'Documentation ready' : 'Generating documentation');	function advance() { progress = Math.min(100, progress + 16); }</script> <div style="display: flex; flex-direction: column; align-items: stretch; gap: var(--gap-4); width: min(100%, 32rem); min-width: 0;">	<Progress value={progress} aria-label="Documentation generation progress">		<Frame as="label" singleLine style="justify-content: space-between;">			<Text lines={1}>{status}</Text>			<Text as="trailing" lines={1}>{progress}%</Text>		</Frame>	</Progress>	<div style="display: flex; justify-content: center; gap: var(--gap-2);">		<Button onclick={advance} disabled={progress === 100}>Advance</Button>		<Button onclick={() => progress = 0}>Reset</Button>	</div></div>

API

关键字 类型 默认值 描述
value number 0 百分比进度，自动 clamp 到 0–100
variant ProgressVariant "line" 长条形或圆形
size number | string 16 圆形宽高；与 Spinner 默认一致
thickness number | string — 长条形高度或圆环粗细；circle / 不确定态对齐 Spinner 环宽 默认行为：line 确定态 4；circle 与不确定态为 size 的 15%（size=16 时 2.4px）。
background SnowUIColor | string "Black4" 轨道底色
color SnowUIColor | string "Primary" 填充颜色
isIndeterminate boolean false 不确定态
showLabel boolean false 仅 circle 生效；确定态下生成显示实时 value 的内置 Text
loopMotion LoopMotionConfig — 覆盖不确定态循环时序
children Snippet — 显式 label 组合；存在时替换 circle 内置 label
parts ComponentPartsOf<{ Text: typeof Text }> — 配置 circle 的内置 Text label

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

使用边界与详细说明

布局模型

主布局模型：复合管理布局。

  • variant="line"：label 保持显式组合模式，与长条轨道纵向排列，默认 gap 为 4px；label 区域横向占满 Progress 可用宽度。

  • variant="circle"：showLabel=true 时内置生成 Text，与 SVG 圆环重叠并默认居中；默认不显示。

  • 空的直系 as="label" 自动显示实时 value；显式 label 内容保持不变。

  • label 默认排版为 12px / 16px，不限制外部自定义文字、字号和颜色。

  • line 不提供内置 label：其常见结构是标题、状态与百分比的横向信息区，单一内置文本无法确定内容和对齐语义。

示例

<Progress value={60}>  <Frame as="label" singleLine class="justify-between">    <Text lines={1}>Loading</Text>    <Text as="trailing" lines={1}>60%</Text>  </Frame></Progress> <Progress variant="circle" value={50} size={32} showLabel /> <Progress value={60}>  <Text as="label">60%</Text></Progress>

Progress 样式覆盖

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

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

变量 用途与默认参考
--snowui-progress-background-override 轨道底色（默认 var(--black-4)）
--snowui-progress-color-override 填充颜色（默认 var(--primary)）
--snowui-progress-gap-override line label 与轨道间距（默认 var(--gap-1) = 4px）
--snowui-progress-thickness-override line 高度 / circle 圆环粗细（line 确定态默认 4px；circle / 不确定态默认 size × 15%）

设计指南 · Token · 组合边界

Progress 类型与状态

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

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

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

共享 Frame API · 返回 API

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

ProgressVariant

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

type ProgressVariant = "line" | "circle";

SnowUIColor

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

export type SnowUIColor = keyof typeof SNOWUI_COLOR_TOKENS;

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;}

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 & {});

ComponentPartsOf

来源：components/src/logic/component-parts.svelte.ts

export type ComponentPartsOf<    T extends Record<string, Component<any>>,> = {    [K in keyof T]?: ConfigurableComponentPartProps<T[K]>;};

ConfigurableComponentPartProps

来源：components/src/logic/component-parts.svelte.ts

export type ConfigurableComponentPartProps<C extends Component<any>> = Partial<    Omit<ComponentProps<C>, ComponentPartControlledKey>>;

ComponentPartControlledKey

来源：components/src/logic/component-parts.svelte.ts

export type ComponentPartControlledKey =    | "children"    | "as"    | "value"    | "defaultValue"    | "open"    | "selected"    | "checked"    | "disabled"    | "readonly"    | "id"    | `on${string}`    | `aria-${string}`;