定价

FlowText 使用手册

v2.0.5 · @snowui-design-system/components

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

组件介绍

以流动过渡展示文字和数字变化，适合动态文案、计数、计时与倒计时。

使用选择

用于文本内容更新时的流动过渡。普通静态文字用 Text；数字专属变化先比较 NumericText 与 NumberFlow。

  • value 是目标文本或数值；数值格式用 locales / format，附加内容通过 children 提供。

  • motionColor、transition 等控制公开动效；需要遵循系统减少动效偏好时显式启用 respectMotionPreference。

快速开始

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

<script lang="ts">	import { Button } from '@snowui-design-system/components';	import { FlowText, chromatic } from '@snowui-design-system/components';	const headlines = ['Build with SnowUI', 'Ship components', 'Write better docs'];	let headlineIndex = $state(0);</script> <div style="display: flex; flex-direction: column; align-items: center; gap: var(--gap-4);">	<FlowText value={headlines[headlineIndex]} motionRole="text" motionColor={chromatic()} size="--text-32" lineHeight="--leading-32" weight={600} />	<Button onclick={() => headlineIndex = (headlineIndex + 1) % headlines.length}>Next headline</Button></div>

API

关键字 类型 默认值 描述
value FlowTextValue — 目标文本或数值
locales string "en-US" 数字格式化区域
format Intl.NumberFormatOptions — 数字格式化选项
trend FlowTextTrend 0 数值趋势；0 使用公共分类能力自动判断
motionRole TextMotionRole "auto" 内容语义定性
transition FlowTextTransition — 可覆盖时序；默认主动画与布局 550ms，逐位间隔与 NumericText 一致
digits Record<number, { max?: number }> — 分段计时器的 modulo 定义，仅参与公共趋势判断
textPosition "left" | "right" "right" FlowText 内容相对 children 的位置
rollDirection FlowTextRollDirection "normal" 控制统一字符纵向流动语义；normal 使用公共趋势方向，reverse 完整取反
loading boolean — 加载状态；与 skeleton 同时开启时显示骨架，未设置时遵循容器状态
skeleton boolean — 控制骨架显示，未设置时遵循容器骨架状态
renderHints RenderHints — 骨架形状与尺寸提示
respectMotionPreference boolean false 显式开启后遵循系统减少动效设置
font string — 字体；未设置时继承容器
size string | number — 字号；未设置时继承容器
weight string | number — 字重；未设置时继承容器
lineHeight string | number — 行高；未设置时继承容器
color SnowUIColor | string — 文字最终颜色；未设置时继承容器
align TextMotionAlign — 文字对齐方式
motionColor TextMotionColor — 内容变化时全部目标字符的临时颜色，包括保留字符；resolver 的 index / total 对应目标全文的 grapheme 索引与总数，动效结束后回到文字颜色
children Snippet — 文本前后缀内容

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

使用边界与详细说明

具体组合、默认行为与限制见上方使用选择和 API；可运行代码见快速开始。

FlowText 样式覆盖

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

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

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

设计指南 · Token · 组合边界

FlowText 类型与状态

必填属性：value。

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

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

共享 Frame API · 返回 API

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

FlowTextValue

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

export type FlowTextValue = string | number;

FlowTextTrend

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

export type FlowTextTrend = TextMotionTrend;

TextMotionTrend

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

export type TextMotionTrend = -1 | 0 | 1;

TextMotionRole

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

export type TextMotionRole = "auto" | "text" | "number" | "timer" | "countdown";

FlowTextTransition

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

export interface FlowTextTransition {        duration?: number;        layoutDuration?: number;        opacityDuration?: number;        deformDuration?: number;        stagger?: number;        easing?: string;        deformEasing?: string;    }

FlowTextRollDirection

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

export type FlowTextRollDirection = "normal" | "reverse";

RenderHints

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

export interface RenderHints {    variant?: SkeletonRenderVariant;    width?: string | number;    height?: string | number;    radius?: string | number;    rows?: number;}

SkeletonRenderVariant

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

export type SkeletonRenderVariant = "line" | "circle" | "rect";

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;