GradientMotion 使用手册

v4.0.1 · @snowui-design-system/components

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

组件介绍

以流动扫光呈现动态渐变，可用于背景、头像占位或可裁切的媒体区域。

使用选择

用于装饰性渐变动效背景。普通背景优先主题 Token；专业艺术色范围仅限该图形，不能推广为任意 UI 颜色。

用 variant 选择图形、paused 暂停，speed / intensity 等调整效果。
为静态身份使用稳定 seed；decorative 默认开启。动效颜色不替代主题色系统。

快速开始

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

<script lang="ts">	import { GradientMotion } from '@snowui-design-system/components';</script> <section style="position: relative; isolation: isolate; overflow: hidden; width: min(100%, 34rem); min-height: 220px; border-radius: var(--radius-5); background: var(--background-1);">	<GradientMotion variant="azure" speed={0.55} width="100%" height="100%" style="position: absolute; inset: 0; opacity: 0.3;" />	<div style="position: relative; display: flex; flex-direction: column; align-items: flex-start; gap: var(--gap-3); padding: var(--padding-6); max-width: 24rem;">		<p style="font-size: var(--text-14); color: var(--black-40);">SnowUI documentation</p>		<h2 style="font-size: var(--text-24); line-height: var(--leading-24);">Build your next interface with a living visual identity.</h2>		<p>Use GradientMotion as a decorative media surface while content and actions remain readable above it.</p>		<a href="/components/quick-start" target="_top" style="color: var(--black-40);">Read the Quick Start</a>	</div></section>

API

关键字	类型	默认值	描述
variant	`GradientMotionVariant`	`"prism"`	glimm palette。`avatar` 为头像默认图专用慢速无空白变体；旧值 `cosmic` / `matrix` / `electric` / `inferno` / `mystic` / `cyber` / `neon` / `plasma` / `neatBlob` 会映射到 glimm palette
seed	`string \| number`	—	随机预设种子；传入后同一 seed 稳定命中同一 palette
speed	`number`	`1`	动效速度倍率
duration	`number`	`800`	glimm sweep 基准时长，单位 ms
size	`number \| string`	—	同时设置宽高
width	`number \| string`	—	宽度
height	`number \| string`	—	高度
radius	`number \| string`	`"inherit"`	圆角；默认继承外部容器，便于 Avatar 裁切
intensity	`number`	`1`	对应 glimm `peakAlpha`，范围限制为 `0` 到 `20`
paused	`boolean`	`false`	是否暂停动效
decorative	`boolean`	`true`	是否作为装饰图；为 `true` 时输出 `aria-hidden="true"`
direction	`GradientMotionDirection`	`"ltr"`	扫光方向
bandTight	`number`	`14`	glimm band gaussian tightness，值越大扫光带越窄
waveAmount	`number`	`1`	glimm edge wave 与头像整体晃动强度，范围 `0–20`
rippleAmount	`number`	`1`	细密波纹强度，范围 `0–20`
brightness	`number`	`1`	glimm band RGB 亮度倍率，范围 `0–20`
colorSpeed	`number`	`1`	自定义颜色的时间相位速度倍率，范围 `0–20`；`0` 时颜色停止流动
highlightIntensity	`number`	`1`	Fresnel 与镜面高光强度倍率，范围 `0–20`；`0` 时关闭高光
colors	`GradientMotionColors`	—	周期上的四个 HEX 采样色；组件提取均值、正弦项与余弦项生成 glimm 风格连续 palette，并沿时间相位流动
loopMotion	`LoopMotionConfig`	—	覆盖 Frame loop bridge 配置；paused=true 始终优先暂停。shader 的时序仍由 speed、duration 和 paused 控制。默认行为：基于 duration 的线性无限循环。

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

使用边界与详细说明

功能概览

内置 glimm 的 6 种 palette：prism、berry、lagoon、citrus、azure、ember
可选颜色与 glimm.dev 截图中的 6 个底部 swatch 对齐，组件通过 variant 选择颜色
WebGL shader 还原 glimm 的 cosine palette 公式：color(t)=a+b*cos(2π*(c*t+d))
还原 glimm sweep band 的默认参数：bandTight=14、waveAmount=1、rippleAmount=1、brightness=1、duration=800
支持 variant="random"，可按 seed 稳定随机一种 glimm palette
支持 variant="avatar" 作为默认头像专用变体：按 seed 稳定取色，速度为普通 sweep 的 0.2 倍；色带固定在画布中，只让波形与色域缓慢往复晃动，全程不闪白
当组件收到 as="avatar-image" 时会自动启用同样的慢速无空白头像模式，因此 Avatar fallback={GradientMotion} 也不会出现白色空白期
支持 direction="ltr|rtl|ttb|btt" 控制扫光方向
支持 speed、size / width / height / radius、paused
保留旧预设名作为兼容别名，但视觉都会映射到 glimm 的 6 种 palette
支持外部裁切：圆形、圆角、方形、任意父容器 overflow: hidden 或 clip-path
支持 as 角色透传；在 Avatar 里推荐 as="avatar-image"

布局模型

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

GradientMotion 的根节点只输出一个由尺寸、圆角与 shader 算法决定的视觉面。
组件不管理子内容排列，不接入 Leading / Content / Trailing 三槽位。
作为其他组件的子项时表现为 Hug；作为背景时通常配合 class="w-full h-full" 或外部 style 固定尺寸。
as 透传宿主角色；as="avatar-image" 还会启用连续填充头像模式，不改变组件的内禀布局。

API 参考

关键字	类型	默认值	描述
as	`string`	-	Frame 角色声明；Avatar 场景推荐 `as="avatar-image"`

as="avatar-image" 会自动启用头像专用连续填充逻辑；如需直接使用组件，也可显式传 variant="avatar"。

专业艺术色例外

GradientMotion 的内置 glimm cosine palette、WebGL 不可用时的 CSS fallback palette，以及 colors 传入的四个六位 HEX 采样色，已在 StyleSpec §2.1.3（源码参考：specs/maintainers/StyleSpec.md）单独登记为专业艺术色例外。shader 必须将这些颜色转换为数值向量并生成连续色域；它们表达生成式画面，不表达按钮、文字、状态或表面语义，因此不要求映射到 SnowUI 语义 Token。

该例外只覆盖 GradientMotion 专业画面的 palette。colors 不是通用颜色 Prop 协议，不得据此让其他组件跳过 resolveSnowUIColor()；组件根的尺寸、圆角、外部 class / style 覆盖、无障碍、外层 motion 与 reduced-motion 仍遵守现行规范。新增 palette 类型或把这些颜色用于 UI 语义前必须重新登记。

使用示例

<GradientMotion size={80} radius="9999px" />

<GradientMotion variant="berry" class="w-full h-full" radius="24px" speed={0.8} />

<Frame style="width: 44rem; height: 18rem; overflow: hidden; border-radius: 2rem;">    <GradientMotion variant="prism" width="100%" height="100%" radius="2rem" /></Frame>

<Avatar fallback={GradientMotion} data-name="Ada Lovelace" />

<GradientMotion variant="avatar" seed="Ada Lovelace" size={80} radius="9999px" />

<Avatar>    <GradientMotion as="avatar-image" variant="random" seed="profile-42" />    <Badge as="badge" dot /></Avatar>

<script lang="ts">  let motionSpeed = $state(1);  const colors = ["prism", "berry", "lagoon", "citrus", "azure", "ember"] as const;</script> <Slider bind:value={motionSpeed} minValue={0.2} maxValue={2} step={0.1} /> {#each colors as color}  <GradientMotion variant={color} width={200} height={120} radius={20} speed={motionSpeed} />{/each}

GradientMotion 样式覆盖

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

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

变量	用途与默认参考
`--snowui-gradient-motion-radius-override`	圆角 / 裁切半径（默认 inherit）
`--snowui-gradient-motion-size-override`	整体尺寸（默认值见组件源码）

设计指南 · Token · 组合边界

GradientMotion 类型与状态

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

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

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

共享 Frame API · 返回 API

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

GradientMotionVariant

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

export type GradientMotionVariant =        | "prism"        | "berry"        | "lagoon"        | "citrus"        | "azure"        | "ember"        | "avatar"        | "random"        | "cosmic"        | "matrix"        | "electric"        | "inferno"        | "mystic"        | "cyber"        | "neon"        | "plasma"        | "neatBlob";

GradientMotionDirection

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

export type GradientMotionDirection = "ltr" | "rtl" | "ttb" | "btt";

GradientMotionColors

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

export type GradientMotionColors = readonly [string, string, string, string];

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