Gradient 使用手册

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

组件介绍

以柔和的多层渐变丰富背景与占位画面，提供六种配色与可缩放的形变效果。

使用选择

用于已内置的装饰性渐变图形或头像占位。艺术配色不作为普通 UI 的主题颜色；页面表面和文字仍使用语义颜色。

• size 同时设置宽高且优先于 width / height；seed 用于稳定同一对象的图形。

• 作为装饰保持 decorative；配色仅用于该装饰图形，页面文字与表面继续使用语义 Token。

快速开始

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

<script lang="ts">	import { Gradient } from '@snowui-design-system/components';</script> <div style="display: flex; flex-wrap: wrap; justify-content: center; gap: var(--gap-4) var(--gap-3); max-width: 100%;">    <Gradient variant="blue" size={80} radius="50%" aria-label="Blue gradient" />    <Gradient variant="cyan" size={80} radius="50%" aria-label="Cyan gradient" />    <Gradient variant="green" size={80} radius="50%" aria-label="Green gradient" />    <Gradient variant="red" size={80} radius="50%" aria-label="Red gradient" />    <Gradient variant="orange" size={80} radius="50%" aria-label="Orange gradient" />    <Gradient variant="purple" size={80} radius="50%" aria-label="Purple gradient" /></div>

API

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

使用边界与详细说明

布局模型

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

• 根节点为 Frame；普通 Gradient / 开启动效的 Avatar 使用固定底色和四张透明 SVG 图层图片，静态 Avatar 使用六种按 palette 复用的包内完整 SVG 图片资源。

• 组件不接受 children，不使用 Leading / Content / Trailing，不提供 parts。

• 默认画布为 360 × 360，默认无圆角；size 或 width / height 可改变外部几何。

• 可见几何沿用 0 0 360 360 坐标系；静态 SVG 使用该 viewBox，活动图层则在同一坐标系外扩 overscan，并以 preserveAspectRatio="none" 填满画布。

• 四张活动图层图片保留 filterUnits="userSpaceOnUse" 的 feGaussianBlur；普通 Gradient 的 Subtract 2 使用 800 × 800 overscan，其他三层使用 600 × 600，Avatar 的增强幅度分支全部使用 720 × 720。图形随图片 viewport 缩放时，模糊标准差与几何一起按比例缩放，不使用固定屏幕像素模糊，也不需要尺寸观察器。

• 根层使用纯 alpha mask 统一裁切预栅格图层，避免圆角最外圈露出渐变底色毛边。

• 普通 Gradient 默认开启四层 15s 闭环动效；Avatar fallback 常态关闭基础形变，可通过 motion / gradientMotion 显式常驻开启，或在 hover 期间按需运行水波形变。

• 作为 Avatar fallback 渲染时，Gradient 根据 Avatar 传入的 seed 稳定选择六种配色；若 seed 本身是 blue / cyan / green / red / orange / purple，则直接命中对应配色。

• Avatar hover 状态由 Avatar 的统一 .snowui-media-hoverable 协议提供；Gradient 自己排除当前 variant，将其余五种 Gradient 的中心主色按实例稳定打乱，并以双层同色 overlay 持续交叉过渡。

• 头像 hover 以缓存静态图为底，按需创建四个预栅格 SVG 图层和五色 × 两层 HTML 纯色 Overlay；四层采用 6.4s / 7.2s / 8.4s / 6.8s 的独立周期、七段非对称路径和增强幅度持续流动。每次进入从六组相位 / 方向配置中随机选择且不与上次重复，颜色循环仍为 10s。两者以 1s 淡入、0.5s 淡出，离开后完整卸载。

• Gradient 通过模块级共享 IntersectionObserver 在离开视口 128px 预热范围后暂停内部 transform 并释放 will-change；浏览器不支持该能力时保持原有持续动效，不影响视觉与语义。

• prefers-reduced-motion: reduce 下停止内部循环并恢复未经 transform 的静态设计基线。

API

CSS 动效覆盖

motion 只决定基础矢量形变是否运行。Test 的 GD-05 提供 19 条控制条：时长、整体速度、四项缓动坐标以及四层全部 13 项幅度参数；控制条以四列网格排列在图形下方，并以每条控制的可调上限初始化。

六种配色

这些颜色是视觉资产自身的固定填色，不是公开颜色 Prop，也不映射主题语意色。

专业艺术色例外

Gradient 的六组固定 SVG palette、中心色与 Avatar 模式多色 Overlay 已在 StyleSpec §2.1.3（源码参考：specs/maintainers/StyleSpec.md） 单独登记为专业艺术色例外。它们共同构成经设计确认的生成式矢量视觉资产，因此不映射到 SnowUI 语义 Token，也不能作为按钮、文字、状态、表面或其他组件的通用颜色来源。

例外只覆盖 Gradient 画面及其 Avatar 视觉分支。组件根的尺寸、圆角、外部 class / style 覆盖、无障碍与 reduced-motion 仍遵守现行 StyleSpec；新增 palette 或将颜色用于新的语义前必须重新登记。

使用示例

<Gradient variant="blue" />

<Gradient variant="purple" size={160} />

<Gradient variant="orange" width={240} height={120} radius={24} />

<Avatar fallback={Gradient} data-name="Gradient avatar" size={80} />  <Avatar gradientMotion data-name="Animated Gradient avatar" size={80} />

Avatar 会向 Gradient fallback 传入 as="avatar-image"、稳定 seed 与 gradientMotion 开关。默认头像常态使用缓存静态图；hover 时 Gradient 在圆形裁切内按需淡入四个预栅格 SVG 图层，并持续过渡到当前 variant 之外的五种颜色。gradientMotion 只决定活动图层是否常驻。

矢量与缩放

• 画布：360 × 360。

• 图层顺序：底色矩形 → Vector 4 → Vector 3 → Subtract → Subtract 2。

• 椭圆模糊：stdDeviation=60 / 60。

• 路径模糊：stdDeviation=40 / 50。

• 模块按 variant + 画布档位 缓存四张透明 SVG data source；相同 variant 的实例复用同一字符串、图片解码与栅格缓存，不创建实例级 filter ID / filter DOM。

• Avatar 常态基础形变关闭时复用六份短 URL 的包内完整 SVG 资源；hover 只为当前头像按需创建四张活动图层图片，离开淡出后释放。

• 静态 Avatar 与活动图层使用同一套 palette、路径和 blur 参数；普通 Gradient 仅将位于最上方、会旋转并暴露裁切边界的 Subtract 2 扩到 800 × 800，其余三层保留 600 × 600；Avatar 的 720 × 720 overscan 覆盖增强幅度。

• Avatar 模式继续使用浏览器原生 content-visibility: auto 与布局 / 绘制 containment，跳过长列表视口外子树绘制，不创建逐实例观察器。

• SVG 图片 viewport 负责统一缩放全部几何与 blur；组件不读取实际像素尺寸，也不重新计算 blur。

• 非正方形宽高按 Figma Fill 行为分别缩放 X / Y 轴。四个 HTML 图层先在 SVG foreignObject 的 360 × 360 设计坐标内运动，再由外层 viewBox 整体 Fill；禁止先拉成长方形再旋转，以免露出预栅格图片的硬裁切边界。

动效与性能

• 底色保持静止；开启 motion 后，单个实例只在四个承载预栅格 SVG 图片的 HTML 图层上运行 CSS transform keyframes。

• 动画只使用 translate3d + rotate + scale / scaleX / scaleY；常驻 Gradient 在每个相邻关键帧区间使用90级更新密度，单步位移在默认 360px 画布中低于约1px；仅在 motion 开启且接近视口时使用 will-change: transform。

• 四个 feGaussianBlur 只在图片解码时执行一次；运行中的 DOM 没有 filter / clipPath / path，循环不触发 SVG filter 重栅格。

• Avatar 未 hover 时由 Avatar 直接使用共享静态图，不创建 Gradient 组件、活动图层或颜色 Overlay；hover 时才挂载一份 Gradient、四张预栅格活动图层与五种候选色 × 两层结构，离开0.5秒淡出后全部卸载。

• 默认 Avatar hover 的四层周期分别为 6.4s / 7.2s / 8.4s / 6.8s，使用原有连续时间函数、七个不等时非镜像途经点、独立负延迟、18% 位移、30deg 旋转与 32% 缩放 / 形变幅度，避免多层同步减速或沿原路返回。

• 原始五层不动画 fill、mix-blend-mode 或 Gaussian Blur；Avatar hover 只在五组双层同色纯色 Overlay 间交叉动画 opacity。每层使用独立 HTML 合成元素执行 overlay，确保 backdrop 是已经完整渲染的 Gradient 图形。

• 颜色顺序仅在组件求值时由 seed 与实例 ID 稳定打乱；每次 hover 只用一次随机数选择与上次不同的六组运动相位 / 方向配置，所有逐帧运动仍由 CSS 完成。JavaScript 只在 hover 边界使用一次 requestAnimationFrame 分离挂载与淡入，并以退出计时器在0.5秒淡出后回收 DOM；不使用 JavaScript 动画循环、Canvas 或 ResizeObserver。

• 0% 与 100% 使用完全相同的 transform，保证持续循环时不跳帧。

• 一个模块级 IntersectionObserver 服务全部实例；离开视口预热范围后暂停 CSS 动画并移除图层提升，重新进入时从暂停位置继续。能力缺失时保持运行，不引入功能退化。

• 图层预栅格画布大于可见画布；动效幅度限制在 overscan 安全范围内并由根 clip-path 统一裁切。