查看“︁模块:抖动/doc”︁的源代码

[[模板:抖动]]的底层生成器，负责把模板参数转换为最终的 HTML 结构。

== 工作原理 ==

模块按以下步骤工作：

# 读取参数：从调用中取得「内容、模式、逐字、速度、延迟」以及各模式对应的数值幅度参数。
# 解析模式：把 <code>模式=平移+旋转+跳动</code> 这类字符串拆分成模式列表。
# 解析数值：把用户传入的纯数字幅度值规整为合法数值，空值或非数字时回退为程序内置默认值。
# 生成变量：把各模式的幅度数值转换为行内 CSS 自定义属性（CSS 变量），如 <code>--dk-amp:0.05em</code>。
# 生成结构：为每个模式各包一层 <code>&lt;span&gt;</code> 并依次嵌套；逐字模式下把文字按单个字符拆开。
# 输出 HTML：模块只生成 class 名、行内 CSS 变量和必要的内联样式，动画本身由[[模板:抖动/styles.css]]提供。

== 模式叠加的原理 ==

CSS 中同一元素只能运行一个 transform 动画，无法直接叠加。因此模块让每种模式各占一层 <code>&lt;span&gt;</code>：

<pre>
&lt;span class="dk-translate" style="--dk-amp:0.11em"&gt;    ← 平移层
  &lt;span class="dk-rotate" style="--dk-angle:9deg"&gt;     ← 旋转层
    &lt;span class="dk-bounce" style="--dk-amp:-0.17em"&gt;  ← 跳动层
      文字
    &lt;/span&gt;
  &lt;/span&gt;
&lt;/span&gt;
</pre>

各层动画独立运行，视觉上自然叠加：外层负责整体平移，内层负责局部抖动。

== 逐字与整段 ==

* '''整段模式'''：内容作为整体被包裹，先经 <code>frame:preprocess()</code> 处理，支持 wikitext 语法。
* '''逐字模式'''：用 <code>mw.ustring.gmatch(text, '.')</code> 将文字按字符拆开，每个字符成为独立抖动单元，并配以递增的负值动画延迟，使各字错位、不同步。逐字模式仅适用于纯文本。

== 与样式表的关系 ==

模块不包含任何动画定义，只负责产出：

* 形如 <code>dk-模式</code> 的 class（如 <code>dk-translate</code>）；
* 各模式幅度对应的行内 CSS 自定义属性（如 <code>style="--dk-amp:0.05em"</code>）；
* 用户显式设置的速度 / 延迟内联样式（如 <code>style="animation-duration:0.3s"</code>）。

实际动画（keyframes、位移、旋转角度等）全部定义在[[模板:抖动/styles.css]]，二者通过 class 名和 CSS 变量对应。模块输出的 class 与 CSS 变量对应关系：

{| class="wikitable"
! 模式 !! 类名 !! 行内 CSS 变量
|-
| 平移 || <code>dk-translate</code> || <code>--dk-amp: &lt;幅度&gt;em</code>
|-
| 旋转 || <code>dk-rotate</code> || <code>--dk-angle: &lt;角度&gt;deg</code>
|-
| 跳动 || <code>dk-bounce</code> || <code>--dk-amp: -&lt;高度&gt;em</code>
|-
| 摇摆 || <code>dk-swing</code> || <code>--dk-angle: &lt;角度&gt;deg</code>
|-
| 颤抖 || <code>dk-jitter</code> || <code>--dk-amp: &lt;幅度&gt;em; --dk-angle: &lt;角度&gt;deg</code>
|-
| 缩放 || <code>dk-pulse</code> || <code>--dk-scale: &lt;倍数&gt;</code>
|}

== 参数与默认值 ==

以下为模块读取的全部参数及其'''程序内置默认值'''。模式专属参数只在对应模式被启用时生效。

{| class="wikitable"
! 参数 !! 作用模式 !! 默认值 !! 单位 !! 说明
|-
| <code>内容</code> || 全局 || 空（必填） || — || 要抖动的文字；也可作为第 1 个匿名参数
|-
| <code>模式</code> || 全局 || 颤抖 || — || 抖动模式：<code>平移/旋转/跳动/摇摆/颤抖/缩放</code>，用 <code>+</code> 叠加
|-
| <code>逐字</code> || 全局 || 否 || — || 设为 <code>是</code> 时逐字独立抖动
|-
| <code>速度</code> || 全局 || 各模式自带周期<br>（平移 0.5s / 旋转 0.6s / 跳动 0.7s / 摇摆 0.8s / 颤抖 0.18s / 缩放 0.8s） || 秒 || 全局动画周期，越小越快；被模式专属速度覆盖
|-
| <code>延迟</code> || 全局 || 0 || 秒 || 全局动画延迟；被模式专属延迟覆盖
|-
| <code>平移幅度</code> || 平移 || 0.11 || em || 水平位移幅度
|-
| <code>平移速度</code> || 平移 || 继承全局 <code>速度</code>；否则 0.5 || 秒 || 平移层动画周期
|-
| <code>平移延迟</code> || 平移 || 继承全局 <code>延迟</code>；否则 0 || 秒 || 平移层延迟
|-
| <code>旋转角度</code> || 旋转 || 9 || deg || 旋转角度
|-
| <code>旋转速度</code> || 旋转 || 继承全局 <code>速度</code>；否则 0.6 || 秒 || 旋转层动画周期
|-
| <code>旋转延迟</code> || 旋转 || 继承全局 <code>延迟</code>；否则 0 || 秒 || 旋转层延迟
|-
| <code>跳动高度</code> || 跳动 || 0.17 || em || 向上跳动高度
|-
| <code>跳动速度</code> || 跳动 || 继承全局 <code>速度</code>；否则 0.7 || 秒 || 跳动层动画周期
|-
| <code>跳动延迟</code> || 跳动 || 继承全局 <code>延迟</code>；否则 0 || 秒 || 跳动层延迟
|-
| <code>摇摆角度</code> || 摇摆 || 9 || deg || 摇摆角度
|-
| <code>摇摆速度</code> || 摇摆 || 继承全局 <code>速度</code>；否则 0.8 || 秒 || 摇摆层动画周期
|-
| <code>摇摆延迟</code> || 摇摆 || 继承全局 <code>延迟</code>；否则 0 || 秒 || 摇摆层延迟
|-
| <code>颤抖幅度</code> || 颤抖 || 0.09 || em || 颤抖位移幅度
|-
| <code>颤抖角度</code> || 颤抖 || 6 || deg || 颤抖旋转角度
|-
| <code>颤抖速度</code> || 颤抖 || 继承全局 <code>速度</code>；否则 0.18 || 秒 || 颤抖层动画周期
|-
| <code>颤抖延迟</code> || 颤抖 || 继承全局 <code>延迟</code>；否则 0 || 秒 || 颤抖层延迟
|-
| <code>缩放倍数</code> || 缩放 || 1.1 || — || 缩放倍数（无单位）
|-
| <code>缩放速度</code> || 缩放 || 继承全局 <code>速度</code>；否则 0.8 || 秒 || 缩放层动画周期
|-
| <code>缩放延迟</code> || 缩放 || 继承全局 <code>延迟</code>；否则 0 || 秒 || 缩放层延迟
|}

== 数值解析 ==

* 幅度参数仅接受'''纯数字'''；空值或非数字时回退为程序内置默认值（见上表）。
* 单位由模块固定（em / deg / 无），无需（也不应）在数字后追加单位。
* <code>速度</code>/<code>延迟</code> 及模式专属版本单位为秒。

== 错误处理 ==

* 未知模式：被忽略；全部未知时回退为 <code>颤抖</code>。
* 非法数值：回退为该参数的默认值。
* 内容为空：输出空字符串。