TextMorph 文本形变
只让变化的字符段动起来的文本形变
用法
基础
只有真正变化的字符段会动,容器宽高与字符同曲线过渡。
Loading demo...
数字位值
数字按位值而非从左到右匹配:1,204 → 1,318 只滚百位和十位,千位不动。
Loading demo...
弹簧
spring 接预设名或物理系数,同时决定曲线与时长;设了之后忽略 durationMs 与 easing。
Loading demo...
最佳实践
- 计数器、金额、百分比这类「同一个量在变」的值优先用它。
- 输入框里跟随键入的数字要传
cursorIndex,否则在20前插一位会被当成整列重新编号。 - 需要软换行或省略号截断时用
TxTextTransformer的mode="fade";这里只有\n会换行。 - 同一屏不要放太多高频实例:每个字符段都是一个元素,形变期间各自提升为合成层。
- 不要再套
TxAutoSizer,引擎自己动画容器宽高。
API 参考
属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
text | string | number | - | 要渲染的值;数字先按 locale 与 decimals 格式化。 |
tag | string | span | 根节点标签。 |
durationMs | number | 400 | 形变时长(ms);设了 spring 时忽略。 |
easing | string | cubic-bezier(0.19, 1, 0.22, 1) | CSS 缓动函数;设了 spring 时忽略。 |
spring | 'snappy' | 'smooth' | 'bouncy' | { stiffness?, damping?, mass? } | - | 弹簧物理,同时决定曲线与时长。 |
scale | boolean | true | 离场段是否带缩放。 |
numbers | boolean | true | 数字按位值滚动;关闭后退回字符级形变。 |
decimals | number | - | 小数位数,仅当 text 是数字时生效。 |
locale | string | en | 用于分段与数字格式化。 |
cursorIndex | number | - | 光标位置;值里恰好一个数字时改用光标匹配。 |
disabled | boolean | false | 跳过动画,直接写入值。 |
respectReducedMotion | boolean | true | 把减少动态效果当作 disabled。 |
debug | boolean | false | 给根节点和每个段描边,便于排查。 |
事件
| 事件名 | 参数 | 说明 |
|---|---|---|
animation-start | - | 一次形变开始;首帧渲染不触发。 |
animation-complete | - | 形变走完;每次形变与 animation-cancel 恰好触发其一。 |
animation-cancel | - | 形变被下一次更新打断。 |
暴露方法
| 名称 | 类型 | 说明 |
|---|---|---|
rootRef | HTMLElement | null | 引擎写入内容的根元素。 |
概述
- 动效单位是字符段而非整串:存活的段 FLIP 到新位置,新增的段从最近的锚点淡入,离场的段脱离文档流后淡出。
- 完整值在视觉隐藏的
[tx-morph-sr]节点里,段元素都是aria-hidden,屏幕阅读器只读一次完整值。 - 可选中的段保留原文空白(NBSP、连续空格、制表符、换行、组合字符);离场段不参与选择,复制不会混入上一轮文本。
- 数字的千分位逗号跟着量级走;量级跳跃达到 3 位及以上时不再携带数字,整体替换。
- 形变中途再次更新会把当前速度带进新曲线,高频更新不会停在起步阶段。
- 减少动态效果或
disabled时直接写入textContent,并清空内部段记录。
技术实现
- 引擎命令式创建并接管段元素(首帧纯文本只为 SSR 水合),所以样式不是 scoped,靠
tx-morph-*属性名隔离。 - 引擎(另导出为
TextMorphEngine/MorphController)移植自 lochie/torph(MIT),弹簧层换成与TxLiquid共用的liquid/src/spring.ts。 - 源码:
packages/tuffex/packages/components/src/text-morph/。
查看源码
packages/tuffex/packages/components/src/text-morph/index.ts