ScrambleText 使用手册

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

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

组件介绍

通过字符扰动逐步呈现目标文字，适合标题、短句与状态文案的动态揭示。

使用选择

用于文本更新时的字符扰动效果。静态文字用 Text，连续文本位移用 FlowText；减少动效环境保留可读内容。

text 提供目标文字，mode / charset / customSequence 选择字符变化方式。
需要遵循系统减少动效偏好时启用 respectMotionPreference；关键信息应始终以最终可读文本表达。

快速开始

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

<script lang="ts">	import { Button, Text } from '@snowui-design-system/components';	import { ScrambleText, chromatic } from '@snowui-design-system/components';	const statuses = ['Preparing docs', 'Checking APIs', 'Ready to publish'];	let statusIndex = $state(0);</script> <div style="display: flex; flex-direction: column; align-items: center; gap: var(--gap-4);">	<ScrambleText text={statuses[statusIndex]} mode="cascade" charset="glyphs" motionColor={chromatic()} size="--text-32" lineHeight="--leading-32" weight={600} />	<Button onclick={() => statusIndex = (statusIndex + 1) % statuses.length}>Update status</Button></div>

API

关键字	类型	默认值	描述
text	`string \| number`	`""`	最终文字
charset	`ScrambleTextCharset`	`"glyphs"`	预设替换字符集
customSequence	`string`	—	自定义替换序列，最多 64 个 grapheme
mode	`ScrambleTextMode`	`"cascade"`	离散动效模式
respectMotionPreference	`boolean`	`false`	显式开启后才遵循系统减少动效设置
font	`string`	—	字体
size	`string \| number`	—	字号
weight	`string \| number`	—	字重
color	`SnowUIColor \| string`	—	最终文字颜色
lineHeight	`string \| number`	—	行高
align	`TextMotionAlign`	—	对齐；默认继承父级
motionColor	`TextMotionColor`	—	全部目标字符从左到右依次回落的临时颜色；支持语义色、CSS 色与逐字 resolver，默认不改变颜色

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

使用边界与详细说明

关键字

<script lang="ts">    import { ScrambleText, chromatic } from "@snowui-design-system/components";</script> <ScrambleText    text="DEPLOY READY"    charset="glyphs"    font="--font-mono"    size="--text-24"    weight={600}    color="Primary"    motionColor={chromatic()}/>

ScrambleText 样式覆盖

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

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

本组件源文件没有直接消费已登记的专属 override。组合子组件的样式通过公开 parts 或显式 child 配置；不要凭名称猜测变量。

设计指南 · Token · 组合边界

ScrambleText 类型与状态

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

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

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

共享 Frame API · 返回 API

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

ScrambleTextCharset

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

export type ScrambleTextCharset = "glyphs" | "symbols" | "numbers";

ScrambleTextMode

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

export type ScrambleTextMode = "scramble" | "cascade";

SnowUIColor

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

export type SnowUIColor = keyof typeof SNOWUI_COLOR_TOKENS;

TextMotionAlign

来源：components/src/lib/text-motion/types.ts

export type TextMotionAlign = "left" | "center" | "right" | "justify";

TextMotionColor

来源：components/src/lib/text-motion/types.ts

export type TextMotionColor = SnowUIColor | string | TextMotionColorResolver;

TextMotionColorResolver

来源：components/src/lib/text-motion/types.ts

export type TextMotionColorResolver = (index: number, total: number) => string;