✍️ 笔顺演示功能介绍

一、功能概述

新增v2.9.8 起字帖支持离线汉字笔画笔顺动态演示。点击字帖中任意汉字方格，即弹出标准窗口式演示弹窗，逐笔演示笔顺动画。

• 开启默认开启，可由工具栏"笔顺演示"按钮切换
• 离线内置 9574 个汉字的笔画数据，完全离线可用
• 多弹窗最多同时弹出 4 个不同汉字的演示窗口
• 自适应多弹窗自动排列为网格并自动缩放，触屏 / 平板优化（v3.0.4）；单窗口总在可视区正中央、末行孤窗精确居中（v3.0.6，见 3.8）
• 标准窗口支持最小化 / 最大化 / 关闭 / 拖拽
• 主题适配light / dark 模式自动切换

二、入口位置与开关

"笔顺演示"控件位于字体下拉菜单下方的快捷工具栏，与"刷新""打印"按钮平齐：

• 按钮显示"笔顺演示"文字 + 小图标
• 开启btn-primary 橙色高亮（默认状态）
• 关闭btn-secondary 灰色暗淡
• 鼠标悬停（桌面端）或长按（移动端）显示功能说明："点击单字动态演示笔画笔顺"

三、弹窗使用说明

3.1 演示舞台

弹窗中央的方形区域为演示舞台，背景始终为白色（即使 dark 模式也保持白色，确保黑色笔画清晰可读）。

↑ 未点击"播放"时：汉字以 0.25 不透明度黑色轮廓显示

3.2 播放控制（v2.9.8 暂停/恢复 + v2.9.8 双图层架构）

v2.9.8 播放按钮支持播放/暂停两态切换：

• ▶ 播放按钮：点击开始逐笔演示笔画笔顺，按钮切换为 ‖ 暂停状态（粉色背景）
• ‖ 暂停按钮：播放中点击可暂停动画，笔画停在当前位置；按钮切回 ▶ 播放状态
• 暂停后再次点击 ▶ 播放：从暂停位置恢复动画，继续演示剩余笔画
• 播放完成后：按钮自动切回 ▶ 播放状态，可再次点击重新演示
• 关闭弹窗后状态不保留，新弹窗默认为 ▶ 播放状态

v2.9.8 采用双图层架构，确保 0.25 不透明度的汉字轮廓在演示过程中始终显示（位于底层，被笔画遮挡而非消失）：

• 不点击播放按钮不会自动开始演示，舞台始终显示 0.25 不透明度的汉字轮廓
• 底层（.sd-stage-bg）：始终以 0.25 不透明度显示完整汉字（黑色 + 偏旁红色），不参与动画
• 顶层（.sd-stage-fg）：初始不可见，点击播放后逐笔绘制完全不透明笔画
• 播放过程中：顶层笔画逐笔覆盖底层对应位置（底层轮廓仍存在，仅被遮挡）
• 播放完成后：顶层完整显示，完全遮挡底层
• 重新点击"▶ 播放"：顶层先清除笔画（底层 0.25 轮廓再次显现），再重新逐笔绘制

3.3 速度调节

速度滑块位于播放按钮下方：

• 范围：1x ～ 5x，步长 1x（v2.9.8 调整：5 档清晰可辨）
• 默认值：1x（v2.9.8 调整：原 5x 过快，1x 更易观察笔画走向）
• 调整后立即生效，下次播放按新速度演示
• v2.9.8 速度调整后持久化到 localStorage，后续新弹窗默认采用此速度（跨会话保留）

3.4 颜色规则

偏旁部首的笔画索引由数据中的 radStrokes 字段自动识别。如该字段缺失，则所有笔画统一为黑色。

3.5 窗口操作（v2.9.8 修复最小化/最大化）

3.6 多弹窗管理

• 最多同时弹出 4 个不同汉字的演示弹窗（MAX_WINDOWS = 4）
• 超过 4 个时弹出 toast 提示："最多同时演示 4 个汉字，请先关闭部分弹窗"
• 点击相同汉字的字格：聚焦已有弹窗（置顶 + 闪烁高亮，不自动播放）
• 自动排列：多弹窗由布局求解器自动排成网格，并自动缩放以适配屏幕（v3.0.4）；整个网格锚定在可视视口正中心，末行孤窗精确居中（v3.0.6，见 3.8）
• 桌面端：优先 1×N 水平排列，缩放恒为 1，布局与旧版逐像素一致
• 移动端：自动选择列数并缩放；屏幕过小时最旧的弹窗自动收为最小化药丸

3.7 触屏 / 平板自适应（v3.0.4）

v3.0.4 重构了弹窗的排列与触屏交互，桌面端行为刻意保持不变：

• 自动排列 + 自动放缩：弹窗容器改为 CSS Grid，新增纯函数求解器 solveLayout(n, availW, availH, sMax) —— 对每种列数计算缩放 s 并取最大值，多弹窗自动排成网格并整体缩放以适配屏幕
• 桌面端零退化：桌面缩放上限 sMax = 1.0，只要 1×N 横排放得下，s 恒为 1，与旧版逐像素一致
• 平板可用更多空间：粗略指针（触摸 / 笔）下缩放上限提高到 1.6，单个弹窗可放大到 1.6 倍，充分利用平板屏幕
• 手机自动收纳：当最优缩放 s 低于可读下限 0.72 时，自动把最旧的展开弹窗收为最小化药丸，直到放得下或只剩一个；药丸可点击恢复（按 LRU 顺序）
• 触摸目标放大：粗略指针下窗口按钮 26 → 34px、播放按钮 36 → 44px、速度滑块拇指 14 → 22px（并按当前缩放反向补偿，保证实际触摸尺寸达标）
• 拖拽不会丢失窗口：拖拽增加视口边界约束，并在视口 / 屏幕方向变化时重新约束，窗口不可能被拖出屏幕外
• 双击标题栏复位：把自由拖拽的窗口复位回自动排列
• 聚焦有可见反馈：点击已打开的同一汉字会置顶并闪烁高亮（补齐了此前缺失的闪烁样式，触摸端点按不再"没反应"）
• 平板断点：新增 769–1280px 平板区间规则（此前该区间完全空白）

3.8 「总在可视区正中央」+ 多窗口优雅排布（v3.0.6）

v3.0.6 修掉了 pad / 手机上两类长期存在的排布缺陷。根因不在 CSS 写得对不对，而在"以哪个视口为基准"：

• 根因：position:fixed + left/top:50% 的百分比基准是布局视口（初始包含块），而用户真正看到的是 visualViewport（可视视口）。二者在这些场景并不重合——软键盘弹出（可视高度骤减、布局视口不变 → 弹窗中心落到键盘后面）、双指缩放后平移（offsetLeft/offsetTop 非 0）、移动端地址栏收放、无头浏览器 isMobile 模拟。这正是"单窗口不在正中央"的成因
• 修法（居中）：布局求解器按 visualViewport 计算可用区，并无条件把 overlay 锚到可视视口正中心（left = offsetLeft + width/2，top 同理）。之所以不做"发现跑出去了才纠偏"：诉求是总在正中央，"在可视区内但偏心"同样是缺陷。该式在两视口重合时与 CSS 基线逐像素等价（桌面 left:50% = clientWidth/2 = visualViewport.width/2 + offsetLeft(0)），因此桌面端零回归
• 修法（尺寸基准）：max-width/max-height 与"最大化"尺寸从 100vw/100vh 改为 --sd-avail-w/--sd-avail-h（由 JS 按可视视口写入）。移动端的 100vh 是"大视口"高度，比真正可见的区域高出一截
• 修法（末行居中）：网格自动放置会把不满一行的"孤行"贴到最左列（实测 iPad 竖屏 3 窗口时孤行偏离视口中心 198px）。单个孤行条目改为 grid-column: 1 / -1 + justify-self: center —— 这是精确居中；仅靠整数列起点做不到（列起点只能对齐整条轨道，奇数条目放进偶数列必然偏半格）
• 可用区下界：取 40px 而非"恰好放得下一个窗口"——极端小视口下宁可把窗口缩得很小，也不让它溢出屏幕（任何情况下都必须可触达）
• 缩放取整方向：求解出的 s 向下取整到 1e-4，宁可略小也不因浮点误差溢出可用区

实测取证（scripts/measure-popup-layout.cjs，只读测量、不改产品代码）：7 种设备（桌面 1920×1080 / 笔记本 1280×800 / 平板横竖 1180×820、820×1180 / 手机 390×844、844×390、360×640）× 1–4 窗口，另加 2× 页面缩放场景（用 CDP Emulation.setDeviceMetricsOverride 造出稳定的"布局视口 ≠ 可视视口"稳态），并在同一页面里做 A/B 对照：

四、离线数据方案

4.1 数据来源

笔画数据来源于 MakeMeAHanzi 数据集，本项目内置 9574 个汉字的完整笔画信息（SVG 路径 + 中心线 + 偏旁索引）。

4.2 数据格式

每个汉字的数据结构：

{
  "strokes": ["M 518 382 Q 572 385 ...", ...],   // SVG path d 字符串数组，长度即笔画数
  "medians": [[[121, 393], [193, 372], ...], ...], // 每笔中心线坐标
  "radStrokes": [0, 1, 2]                          // 可选：偏旁笔画索引
}

4.3 压缩与加载

4.4 查询优先级

当点击字格查询汉字数据时，按以下顺序查找：

1. 自定义数据（_customDataMap）— 用户手动添加的冷僻字 / 新造字，优先级最高
2. 内置数据（_charDataMap）— 9574 汉字离线字典
3. 网络缓存（_networkCache）— 之前从 CDN 加载过的字符（内存缓存）
4. 网络加载（仅 navigator.onLine === true 时）— 从 jsdelivr CDN 在线获取，成功后缓存到 _networkCache

4.5 持久化与清理

自定义数据通过 localStorage 持久化（key: calligraphy_custom_hanzi）：

• 调用 setCharData + persistCustomData 添加冷僻字
• 调用 clearCustomData 清空自定义数据
• 调用 persistNetworkCache 将网络缓存的冷僻字合并到自定义数据并持久化
• 调用 clearNetworkCache 仅清空内存中的网络缓存

五、可扩展性（冷僻字 / 新造字）

支持运行时通过代码插入冷僻字 / 新造字数据：

import { setCharData, persistCustomData, buildCharData } from './src/modules/hanziDataStore.js';

// 构造规范化数据（自动校验）
const data = buildCharData(
    ["M 100 500 L 924 500"],     // SVG path d 字符串数组
    [[[100, 500], [924, 500]]],   // 每笔中心线坐标
    undefined                     // 可选：偏旁笔画索引
);

// 插入并持久化
setCharData('㐀', data);
persistCustomData();

坐标系必须为 MakeMeAHanzi 规范（X 轴 0 ~ 1024，Y 轴 -124 ~ 900，向下为正），否则渲染会错位。

六、键盘快捷键

七、技术实现

• 渲染引擎：hanzi-writer npm 包（^3.5.0），通过自定义 charDataLoader 注入离线数据，脱离 CDN 依赖
• 数据压缩：fflate 纯 JS 库的 gunzipSync 解压 Gzip 二进制
• Web Worker：数据加载与解压在后台线程执行，主线程零阻塞
• 降级策略：Worker 不可用 → 主线程；.bin fetch 失败 → .js 备用
• SVG 自适应：通过手动添加 viewBox + preserveAspectRatio="xMidYMid meet" 实现弹窗大小变化时字体始终居中充满
• PWA 预缓存：数据文件进入 Service Worker 缓存，二次访问秒开

详细数据结构与压缩方案见 离线汉字数据方案_v2.9.8.md。

八、常见问题

Q1：为什么点击字格没有反应？

请检查工具栏"笔顺演示"按钮是否处于开启状态（橙色高亮）。若关闭则点击字格不会弹出弹窗。

Q2：弹窗显示"无'X'的笔画数据"怎么办？

该字不在 9574 内置汉字范围内，且当前处于离线状态或网络备选加载失败。请联网后重试，或通过 setCharData 接口手动添加该字数据。

Q3：弹窗舞台为什么是白色的？

舞台背景始终为白色，确保黑色笔画在任何主题下都清晰可读。dark 模式下仅弹窗边框、标题栏、控件区跟随主题变化。

Q4：为什么未播放时汉字是淡黑色？

这是设计要求：未播放时整个汉字以 0.25 不透明度的黑色轮廓显示，作为预览。点击"▶ 播放"后切换为完全不透明逐笔演示。

Q5：如何同时演示多个汉字？

依次点击不同汉字的字格，最多同时弹出 4 个弹窗。相同汉字的字格点击不会新开弹窗，而是聚焦已有弹窗（置顶 + 闪烁高亮，需手动点击"▶ 播放"才会演示）。

九、版本历史