更新记录

1.0.0（2026-07-23）

• 新增 uni-app Vue3 与 uni-app x 双组件实现。
• 支持逐字、逐词、逐行以及打字机、乱码、渐入、模糊、弹跳、波浪、抖动、变色效果。
• 支持流式文本追加、暂停、继续、重播、跳过、倒放、循环和动态速度控制。
• 支持 Markdown 分段、常用行内标记、关键词高亮与下划线动画。
• 支持中文、英文、数字、组合字符和 ZWJ emoji 安全切分。

平台兼容性

uni-app(3.7.11)

uni-app x(3.7.11)

其他

kongbai-text-motion

适用于流式文本、欢迎语、剧情字幕和内容阅读的文字交互动画组件。插件同时提供 .uvue 与 .vue 组件，共享 UTS 文本解析模块，不依赖原生 SDK、网络请求或第三方 UI 库。

平台

• uni-app x：Web、Android App、iOS App
• uni-app Vue3：H5、Android App、iOS App
• 不支持 uni-app Vue2、nvue 和小程序

uni-app x App 动画依赖 HBuilderX 4.53+ 的 UniElement.animate()；Web 与 uni-app Vue3 使用 CSS 关键帧。

功能

• 支持逐字、逐词、逐行三种播放粒度。
• 提供打字机、乱码、渐入、模糊、弹跳、波浪、抖动、变色八种效果。
• 支持流式文本追加、暂停、继续、重播、倒放、跳过、循环和动态调速。
• 支持轻量 Markdown 分段、关键词高亮、背景色和下划线。
• 支持组合音标、肤色修饰、国旗和 ZWJ emoji 的完整显示。

基础使用

安装到项目的 uni_modules 后，通过 easycom 直接使用：

<kongbai-text-motion
  text="你好，欢迎使用文字动画 👨‍💻✨"
  effect="bounce"
  unit="char"
  :speed="52"
  :keywords="['文字动画']"
  :underline-keywords="true"
/>

uni-app x 与 uni-app Vue3 组件的控制逻辑均由 shared/useTextMotion.uts 提供，组件脚本统一使用 <script setup lang="uts">。两个版本的属性、事件和实例方法保持一致。

流式文本

可以通过 text 属性持续传入完整累计文本，也可以直接调用实例的 append()。流结束后调用 finishStream()，组件才会发出最终 complete 事件。

<template>
  <kongbai-text-motion ref="motionRef" stream effect="typewriter" :speed="30" />
</template>

<script setup>
import { ref } from 'vue'

const motionRef = ref(null)

function onMessageChunk(chunk) {
  motionRef.value.append(chunk)
}

function onMessageEnd() {
  motionRef.value.finishStream()
}
</script>

stream 模式显示完当前内容后会进入 waiting 状态，不会提前触发 complete。下一段内容到达时自动继续。

动画与粒度

unit 支持 char、word、line。word 会合并连续英文、数字和空白，中文与 emoji 按完整字素推进；line 按 Markdown/普通文本行推进。

Markdown 分段

设置 markdown 后，组件会识别以下内容并按块播放，不使用 v-html：

• 一级到三级标题
• 无序列表、数字列表
• 引用、分隔线、围栏代码块
• **粗体**、*斜体*、行内代码和链接文本

<kongbai-text-motion
  :text="markdownText"
  markdown
  unit="word"
  effect="fade"
/>

这是轻量展示解析器，不负责表格、图片、任务列表或 HTML 标签。复杂 Markdown 可先用业务侧解析器拆成多个组件实例。

关键词样式

简单场景使用 keywords，高级场景传入 keywordRules：

const keywordRules = [
  { keyword: '重点', color: '#175CD3', backgroundColor: '#D1E9FF', underline: true },
  { keyword: '重要', color: '#B42318', backgroundColor: '#FEE4E2' }
]

关键词跨多个字符或词时，命中的动画 token 会依次显示颜色、背景与下划线，形成随文字展开的高亮动画。

属性

事件与方法

事件：start、progress、pause、resume、waiting、complete、skip、reverse、append、clear。

progress 回传 { visible, total, progress, direction }；start、resume、complete、skip、reverse 回传当前数量、总数和方向；pause、waiting 回传当前数量和总数；append 回传 chunk、累计 text 和总数；clear 不带事件数据。

实例方法：

字符处理与性能

字符模式会保留 UTF-16 代理对、组合音标、肤色修饰、国旗和 ZWJ 家庭/职业 emoji，避免把一个可见符号拆成半个字符。组件只挂载已经显示的 token；长文建议使用 word 或 line，并按消息/段落拆分实例，避免一次创建数千个文字节点。