@readdy/anim 0.0.21

package/shared/text-split.js

@@ -0,0 +1,188 @@
+/**
+ * @readdy/anim/shared/text-split.js
+ *
+ * 文本拆字工具 —— 将元素内的文字拆分为带 stagger delay 的 span，
+ * 用于 text-split 类动效（letter-bounce、split-text、fly-in-chars 等）。
+ *
+ * init(el) 调用此工具，destroy(el) 恢复 el.dataset.originalText。
+ *
+ * 规则：
+ * - 只拆 textNode，保留元素节点（<em>、<strong>、<span class="icon"> 等）不动
+ * - 空白字符不拆，保留为原样
+ * - 超过 maxChars 字符时自动降级为按词拆分（splitTextIntoWords）
+ * - 拆字前保存原始 innerHTML 到 el.dataset.originalText（只在内部保存一次）
+ */
+
+import { buildAnimClass } from './constants.js'
+
+// ─────────────────────────────────────────────────────────
+// 公开 API
+// ─────────────────────────────────────────────────────────
+
+/**
+ * 将元素内的文本拆分为逐字 span，每个 span 带有 animation-delay。
+ *
+ * @param el       目标元素
+ * @param options  配置项
+ * @param options.stagger    每个字符的延迟增量（ms），默认 60
+ * @param options.charClass  span 的 class 名，默认 'readdy-anim-char'
+ * @param options.maxChars   超长文本降级阈值，默认 200
+ */
+export function splitTextIntoChars(el, options = {}) {
+  const {
+    stagger = 60,
+    charClass = buildAnimClass('char'),
+    maxChars = 200,
+  } = options
+
+  // 保存原始内容，供 destroy 恢复（只在内部保存，各动效 init 不重复保存）
+  if (!el.dataset.originalText) {
+    el.dataset.originalText = el.innerHTML
+  }
+
+  const textLength = el.textContent.trim().length
+
+  // 超长文本降级为按词拆分
+  if (textLength > maxChars) {
+    splitTextIntoWords(el, { stagger: stagger * 2, wordClass: charClass })
+    return
+  }
+
+  let charIndex = 0
+  walkAndSplit(el, charClass, stagger, () => charIndex++)
+}
+
+/**
+ * 将元素内的文本按词拆分，每个词包在一个 span 中。
+ *
+ * @param el       目标元素
+ * @param options  配置项
+ * @param options.stagger    每个词的延迟增量（ms），默认 120
+ * @param options.wordClass  span 的 class 名，默认 'readdy-anim-word'
+ */
+export function splitTextIntoWords(el, options = {}) {
+  const {
+    stagger = 120,
+    wordClass = buildAnimClass('word'),
+  } = options
+
+  // 保存原始内容，供 destroy 恢复
+  if (!el.dataset.originalText) {
+    el.dataset.originalText = el.innerHTML
+  }
+
+  let wordIndex = 0
+  walkAndSplitByWord(el, wordClass, stagger, () => wordIndex++)
+}
+
+// ─────────────────────────────────────────────────────────
+// 内部实现
+// ─────────────────────────────────────────────────────────
+
+/**
+ * 不应该拆分的子元素标签 —— 这些标签内的文本保持原样
+ */
+const PRESERVE_TAGS = new Set([
+  'SVG', 'IMG', 'VIDEO', 'IFRAME', 'CANVAS', 'SCRIPT', 'STYLE',
+])
+
+/**
+ * 判断是否为空白字符（不拆）
+ */
+function isWhitespace(char) {
+  return char === ' ' || char === '\n' || char === '\t' || char === ' '
+}
+
+/**
+ * 递归遍历 DOM 树，将所有 textNode 拆成逐字 span。
+ *
+ * @param node          当前遍历的节点
+ * @param charClass     span 的 class 名
+ * @param stagger       每个字符的延迟增量（ms）
+ * @param nextIndex     返回当前字符索引的函数（每次 +1）
+ */
+function walkAndSplit(node, charClass, stagger, nextIndex) {
+  // 要遍历的子节点列表（先快照，因为遍历过程中会修改 DOM）
+  const children = Array.from(node.childNodes)
+
+  for (const child of children) {
+    if (child.nodeType === Node.ELEMENT_NODE) {
+      // 元素节点：保留标签，递归进入
+      if (PRESERVE_TAGS.has(child.tagName.toUpperCase())) {
+        continue // svg/img 等不拆
+      }
+      walkAndSplit(child, charClass, stagger, nextIndex)
+
+    } else if (child.nodeType === Node.TEXT_NODE) {
+      // 文本节点：拆字
+      const text = child.textContent
+      if (!text) continue
+
+      const fragment = document.createDocumentFragment()
+
+      for (let i = 0; i < text.length; i++) {
+        const char = text[i]
+
+        if (isWhitespace(char)) {
+          // 空白字符保留为文本节点，不拆
+          fragment.appendChild(document.createTextNode(char))
+        } else {
+          // 非空白字符 → 包在 span 里
+          const span = document.createElement('span')
+          span.className = charClass
+          span.style.animationDelay = `${nextIndex() * stagger}ms`
+          span.textContent = char
+          fragment.appendChild(span)
+        }
+      }
+
+      // 替换原始文本节点
+      child.parentNode.replaceChild(fragment, child)
+    }
+  }
+}
+
+/**
+ * 递归遍历 DOM 树，将所有 textNode 按词拆分。
+ *
+ * @param node          当前遍历的节点
+ * @param wordClass     span 的 class 名
+ * @param stagger       每个词的延迟增量（ms）
+ * @param nextIndex     返回当前词索引的函数（每次 +1）
+ */
+function walkAndSplitByWord(node, wordClass, stagger, nextIndex) {
+  const children = Array.from(node.childNodes)
+
+  for (const child of children) {
+    if (child.nodeType === Node.ELEMENT_NODE) {
+      if (PRESERVE_TAGS.has(child.tagName.toUpperCase())) {
+        continue
+      }
+      walkAndSplitByWord(child, wordClass, stagger, nextIndex)
+
+    } else if (child.nodeType === Node.TEXT_NODE) {
+      const text = child.textContent
+      if (!text) continue
+
+      // 按空白分词，保留原始空白
+      const words = text.split(/(\s+)/)
+      const fragment = document.createDocumentFragment()
+
+      for (const part of words) {
+        if (/^\s*$/.test(part)) {
+          // 纯空白，保留为文本节点
+          fragment.appendChild(document.createTextNode(part))
+        } else {
+          // 非空白词 → 包在 span 里
+          const span = document.createElement('span')
+          span.className = wordClass
+          span.style.animationDelay = `${nextIndex() * stagger}ms`
+          span.textContent = part
+          fragment.appendChild(span)
+        }
+      }
+
+      child.parentNode.replaceChild(fragment, child)
+    }
+  }
+}