组件/TextMorph 文本形变

TextMorph 文本形变

只让变化的字符段动起来的文本形变

Verified自 0.6.0

用法

基础

只有真正变化的字符段会动,容器宽高与字符同曲线过渡。

Loading demo...

数字位值

数字按位值而非从左到右匹配:1,204 → 1,318 只滚百位和十位,千位不动。

Loading demo...

弹簧

spring 接预设名或物理系数,同时决定曲线与时长;设了之后忽略 durationMs 与 easing。

Loading demo...

最佳实践

  • 计数器、金额、百分比这类「同一个量在变」的值优先用它。
  • 输入框里跟随键入的数字要传 cursorIndex,否则在 20 前插一位会被当成整列重新编号。
  • 需要软换行或省略号截断时用 TxTextTransformer 的 mode="fade";这里只有 \n 会换行。
  • 同一屏不要放太多高频实例:每个字符段都是一个元素,形变期间各自提升为合成层。
  • 不要再套 TxAutoSizer,引擎自己动画容器宽高。

API 参考

属性

属性名类型默认值说明
textstring | number-要渲染的值;数字先按 locale 与 decimals 格式化。
tagstringspan根节点标签。
durationMsnumber400形变时长(ms);设了 spring 时忽略。
easingstringcubic-bezier(0.19, 1, 0.22, 1)CSS 缓动函数;设了 spring 时忽略。
spring'snappy' | 'smooth' | 'bouncy' | { stiffness?, damping?, mass? }-弹簧物理,同时决定曲线与时长。
scalebooleantrue离场段是否带缩放。
numbersbooleantrue数字按位值滚动;关闭后退回字符级形变。
decimalsnumber-小数位数,仅当 text 是数字时生效。
localestringen用于分段与数字格式化。
cursorIndexnumber-光标位置;值里恰好一个数字时改用光标匹配。
disabledbooleanfalse跳过动画,直接写入值。
respectReducedMotionbooleantrue把减少动态效果当作 disabled。
debugbooleanfalse给根节点和每个段描边,便于排查。

事件

事件名参数说明
animation-start-一次形变开始;首帧渲染不触发。
animation-complete-形变走完;每次形变与 animation-cancel 恰好触发其一。
animation-cancel-形变被下一次更新打断。

暴露方法

名称类型说明
rootRefHTMLElement | 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