@krsmt0113/letters-effect

把「手写描边文字动画」封装成可复用包，适合在任意前端项目中直接使用。
字形素材来自你复制站点中的同一套小写字母路径数据（a-z）。

安装

npm install @krsmt0113/letters-effect

如果你当前是本仓库本地开发，可直接从 packages/letters-effect 引用源码。

快速开始

1) HTML

<div id="letters" style="width:320px;height:160px"></div>

2) JavaScript

import { createLettersEffect } from "@krsmt0113/letters-effect";

const effect = createLettersEffect("#letters", {
  text: "hello",
  stroke: "#ffffff",
  strokeWidth: 2,
  duration: 3200,
  loop: true,
  autoplay: true,
});

API

createLettersEffect(target, options)

• target: HTMLElement | string，容器元素或选择器
• options:
  • text 文本内容（默认 hello，仅支持 a-z 和空格，其他字符会被过滤）
  • stroke 描边颜色（默认 #ffffff）
  • strokeWidth 描边粗细（默认 2）
  • duration 单次动画时长 ms（默认 3200）
  • loop 是否循环（默认 false）
  • autoplay 是否自动播放（默认 true）
  • svgClassName 给内部 svg 附加 class
  • svgDefs 注入 <defs> 内容（可自定义渐变）
  • ariaLabel 无障碍标签
  • padding SVG 内边距（默认 4）
  • letterSpacing 字母间距（默认 1.8）
  • wordSpacing 空格宽度（默认 6）

返回 LettersEffect 实例。

实例方法

• play() 开始/继续播放
• pause() 暂停播放
• restart() 从头播放
• setText(text) 更新文字并重绘
• setProgress(value) 手动设置进度（0 ~ 1）
• setOptions(options) 批量更新参数并重绘
• destroy() 销毁实例并移除 SVG

渐变描边示例

const defs = `
  <linearGradient id="rainbow" gradientUnits="userSpaceOnUse" x1="0" y1="0" x2="120" y2="0">
    <stop offset="0%" stop-color="#007AFF" />
    <stop offset="20%" stop-color="#AF52DE" />
    <stop offset="40%" stop-color="#FF3B30" />
    <stop offset="60%" stop-color="#FF9500" />
    <stop offset="80%" stop-color="#FFCC00" />
    <stop offset="100%" stop-color="#34C759" />
  </linearGradient>
`;

createLettersEffect("#letters", {
  text: "apple",
  stroke: "url(#rainbow)",
  svgDefs: defs,
});