poem-text-animator

PoemTextAnimator

一个可直接引用的轻量文字动画库，支持逐字动画与逐行播放，适用于诗词、歌词、Slogan、Banner 文案等场景。

ESM 快速开始

方式一：浏览器（type="module"）

<link rel="stylesheet" href="./index.css" />
<div id="target"></div>

<script type="module">
  import { createTextAnimator } from "./index.js";

  const animator = createTextAnimator("#target", {
    animationClass: "three",
    charDelay: 0.05,
    lineInterval: 700,
  });

  animator.renderLines(["你好，世界", "这是文字动画库"]);
</script>

方式二：React / Vue 项目

import { createTextAnimator, ANIMATION_PRESETS } from "@/libs/poem/index.js";
import "@/libs/poem/index.css";

也支持默认导入：

import PoemTextAnimator from "@/libs/poem/index.js";

const { createTextAnimator, ANIMATION_PRESETS } = PoemTextAnimator;

API

createTextAnimator(container, options)

• container: CSS 选择器字符串或 DOM 元素。
• options:
  • baseClass：基础类名，默认 animate
  • animationClass：动画预设类名，默认 one
  • lineTag：每一行的标签名，默认 p
  • charDelay：字符间延迟（秒），默认 0.05
  • lineInterval：逐行渲染间隔（毫秒），默认 1000
  • clearBeforeRender：渲染前是否清空，默认 false
  • animationClasses：按行循环使用的动画类名数组
  • animationResolver(lineIndex, options)：自定义按行返回动画类名

实例方法

• render(text, overrideOptions)：渲染单行文字。
• renderLines(lines, overrideOptions)：按时间间隔逐行渲染，返回 Promise<HTMLElement[]>。
• updateOptions(nextOptions)：更新默认配置。
• cancel()：取消尚未执行的逐行任务。
• clear()：取消任务并清空容器。
• destroy()：销毁实例。

工具函数

• splitTextToSpans(targetElement, text, charDelay)：把文本拆分为 span 并写入目标元素。

动画预设

库内置 7 种动画：one、two、three、four、five、six、seven。

import { ANIMATION_PRESETS } from "./index.js";

本地示例

使用任意静态服务器打开目录后访问 index.html，即可看到“单卡片逐首切换”示例：共 7 首诗循环播放，并依次使用 one~seven 动画预设。