module.md 10 KB
XJS / Animal.js 文档：模块化开发 & 测试总指南（工作流）
目标：把文档拆成可独立开发/测试的“小模块”，每个模块都有：
- 左侧（第一列）：扁平化总菜单（未来会加入 Layer 等 UI 库）
- 中间（第二列）：该模块/分组的「缩略图卡片」导航（像 anime.js 文档那样好玩）
- 右侧（第三列）：每个卡片对应的“完整示例页”（中文说明 + Tabs + Live Demo + Prev/Next）
目录（简体中文）
- 1. 三列架构是怎么工作的？
- 2. 文件/目录命名规范（强烈建议照做）
- 3. 左侧菜单（扁平化）规范：怎么加一个模块？
- 4. 第二列 list 页面规范：缩略图卡片 + 高亮同步
- 5. 第三列内容页面规范：Tabs + Demo + 组内/跨组 Prev/Next
- 6. Prev/Next 规则与路由表维护方式
- 7.
animal.js（xjs）例子与测试规划（分组清单） - 8. 已实现 / 进行中 / 待实现（进度表）
1) 三列架构是怎么工作的？
文档入口是 doc/index.html，它由 3 个区域组成：
左侧菜单（第一列）
- 点击某个菜单项会调用
selectCategory(listUrl, defaultContentUrl) - 它会同时更新：
- 第二列 iframe：加载该模块的 list 页面（卡片列表）
- 第三列 iframe：加载该模块默认的内容页
- 点击某个菜单项会调用
第二列（中列）
- 本质是一个 list 页（例如
doc/targets/list.html） - list 页点击卡片会调用
window.parent.loadContent('xxx.html')来切换第三列内容页 - list 页还实现了
window.setActiveByContentUrl(contentUrl)，用于跟随第三列自动高亮
- 本质是一个 list 页（例如
第三列（右侧）
- 每个示例是一个独立 HTML 页面（例如
doc/targets/test_css_selector.html） - 内容页在加载时会调用
window.parent.setMiddleActive('xxx.html')，让第二列自动高亮对应卡片
- 每个示例是一个独立 HTML 页面（例如
2) 文件/目录命名规范（强烈建议照做）
每个“分组”建议放一个文件夹，结构如下：
doc/
<group_name>/
list.html # 第二列：卡片列表（缩略图导航）
overview.html # 第三列：可选的分组概览页（建议）
test_<topic>.html # 第三列：具体示例页（一个功能点一个页面）
命名建议：
- 分组目录名：英文小写 + 下划线，例如
targets/、tween_value_types/ - 示例页：统一前缀
test_，例如test_css_selector.html - 概览页：统一
overview.html
3) 左侧菜单（扁平化）规范：怎么加一个模块？
原则：一个总菜单，用“分区标题”做视觉分组，但不要折叠树（便于未来加入 Layer/其他 UI 库）。
左侧菜单当前在 doc/index.html 内直接维护。
左侧菜单建议结构（示例）
- Animal.js 动画
- Targets（目标）
- Properties（可动画属性）
- Tween 值（补间值类型）
- Callbacks（回调）
- Examples（示例）
- Layer 弹窗
- Layer + 动画联动示例
- （未来）Layer API / 主题 / 组件化
- 开发者
- 模块开发与测试指南（本文件）
加菜单项时必须同时准备
- 第二列 list 页面：
<group>/list.html - 第三列默认页：
<group>/overview.html或test_xxx.html
否则点击会白屏（找不到页面）。
4) 第二列 list 页面规范：缩略图卡片 + 高亮同步
第二列 list 页的核心要求：
- 卡片元素带
data-content="group/test_xxx.html"，用于与第三列 URL 做匹配 - 暴露函数
window.setActiveByContentUrl(contentUrl)，供父窗口调用进行高亮同步 - 点击卡片时调用：
window.parent.loadContent('group/test_xxx.html')
参考现成实现：
doc/targets/list.html
5) 第三列内容页面规范：Tabs + Demo + Prev/Next
第三列内容页建议统一采用“CSS Selector”同款结构：
- 顶部 breadcrumb + since
- 标题 + 简体中文说明
- Tabs（JavaScript / HTML / CSS）
- Live Demo（尽可能直观、活泼、有趣）
- Prev / Next（统一走父窗口的全局路由表）
内容页必须做两件事（保证三列联动）：
同步第二列高亮
try { window.parent?.setMiddleActive?.('group/test_xxx.html'); } catch {}Prev / Next 走父窗口统一逻辑
const CURRENT = 'group/test_xxx.html'; function goPrev() { window.parent?.docNavigatePrev?.(CURRENT); } function goNext() { window.parent?.docNavigateNext?.(CURRENT); }
好处：不用每个页面手写上一个/下一个链接；组内/跨组顺序统一由父窗口维护。
6) Prev/Next 规则与路由表维护方式
Prev/Next 规则：
- 组内跳转：同一 group 内按页面顺序移动
- 跨组跳转：到上一组的最后一个 / 下一组的第一个（整体顺序不间断）
路由表位置：
- 当前维护在
doc/index.html里的DOC_PAGES数组
维护原则：
- 每新增一个
test_xxx.html，就把它加进DOC_PAGES url使用相对doc/的路径，例如targets/test_css_selector.htmlgroup用于 Nav 中间的“当前分组”显示
7) animal.js（xjs）例子与测试规划（分组清单）
说明：
- ✅ = 已存在页面（可能需要补充中文说明/统一 PrevNext）
- ⬜ = 待新增（本工作流会按顺序逐步补齐）
A. Targets（目标选择）
- ✅
targets/overview.html：概览 - ✅
targets/test_css_selector.html：CSS Selector（字符串） - ✅
targets/test_dom_elements.html：DOM Element / NodeList - ✅
targets/test_js_objects.html：JS 对象作为目标（对象 tween） - ✅
targets/test_array_targets.html：数组 targets（混合目标）
B. Animatable properties（可动画属性 / 引擎分流）
- ✅
animatable_properties/test_transforms.html：Transform（x/y/rotate/scale） - ✅
animatable_properties/test_css_props.html：CSS 属性 - ✅
animatable_properties/test_css_vars.html：CSS 变量--xxx - ✅
animatable_properties/test_js_props.html：JS 属性（非 style）
⬜（建议新增）
- ⬜
animatable_properties/overview.html：本组概览 + “WAAPI vs JS fallback” 解释 +controls.engine展示
C. Tween value types（补间值类型）
- ✅
tween_value_types/test_numerical.html：数字 - ✅
tween_value_types/test_unit.html：单位（px/deg/%/rem…） - ✅
tween_value_types/test_relative.html：相对值（如果支持） - ✅
tween_value_types/test_colors.html：颜色（如果支持）
⬜（建议新增）
- ⬜
tween_value_types/overview.html：本组概览 + “哪些值会走 JS 插值/哪些会离散切换” 说明
D. Tween parameters（补间参数 / 播放参数）
animal.js实际支持的参数（来自源码）：duration / delay / easing / direction / fill / loop / endDelay / autoplay / springFrames / begin / update / complete。
- ⬜
tween_parameters/list.html - ⬜
tween_parameters/overview.html - ⬜
tween_parameters/test_duration_delay.html - ⬜
tween_parameters/test_endDelay_fill.html - ⬜
tween_parameters/test_direction_loop.html - ⬜
tween_parameters/test_easing_named_and_bezier.html - ⬜
tween_parameters/test_easing_spring.html（展示 spring 曲线 + springFrames）
E. Controls（控制器 API）
animate()返回 Controls：play/pause/cancel/finish/seek，并且是 thenable（可await）。
- ⬜
controls/list.html - ⬜
controls/overview.html - ⬜
controls/test_play_pause_resume.html - ⬜
controls/test_seek_slider.html（进度条拖动） - ⬜
controls/test_thenable.html（await xjs(...).animate(...)） - ⬜
controls/test_engine_info.html（展示controls.engine.waapiKeys/jsKeys）
F. Timeline（时间轴）
- ⬜
timeline/list.html - ⬜
timeline/overview.html - ⬜
timeline/test_add_offsets.html（+=、-=、number offset） - ⬜
timeline/test_defaults.html（timeline defaults）
G. SVG（draw）
- ⬜
svg/list.html - ⬜
svg/overview.html - ⬜
svg/test_draw_path.html（xjs('path').draw()） - ⬜
svg/test_svg_attr_js_fallback.html（SVG attribute 动画：哪些走 JS）
H. InView / Scroll（视口触发 / 滚动联动）
- ⬜
scroll/list.html - ⬜
scroll/overview.html - ⬜
scroll/test_inview_once.html（inViewAnimate once:true/false） - ⬜
scroll/test_scroll_linked_element.html（scroll(target)） - ⬜
scroll/test_scroll_container.html（scroll container）
I. Layer 集成（联动展示库特性）
Selection.layer()/Selection.unlayer()+$.run()/$.layer()
- ✅
examples/layer.html（已有示例，但后续会补充“更像产品”的玩法） - ✅
layer/list.html（第二列：Layer 分组卡片导航） - ✅
layer/overview.html（独立分组：弹窗 API + 图标动画概览） - ✅
layer/test_icons_svg_animation.html（SVG icon：ring + mark 描边动画，体验接近 SweetAlert） - ✅
layer/test_confirm_flow.html（确认流程：warning → success/info 串联） - ✅
layer/test_selection_layer_dataset.html（Selection.layer + data-layer-*） - ✅
layer/test_static_fire.html（Layer.run / Layer.$ builder）
说明：Layer 的成功/失败等 icon 已切换为 内联 SVG，并使用
animal.js的draw()技术（strokeDashoffset）做描边动画，同时用 spring easing 做弹性进入。
8) 已实现 / 进行中 / 待实现（进度表）
已实现 ✅
- ✅ 左侧菜单扁平化（
doc/index.html） - ✅ 全局 Prev/Next 路由表与 API（
doc/index.html：DOC_PAGES+docGetPrevNext/docNavigatePrev/docNavigateNext） - ✅ “模块开发与测试指南”查看页（
doc/module.html，读取doc/module.md）
进行中 🛠️
- 🛠️ 补齐
animal.js的缺失分组：Tween parameters / Controls / Timeline / SVG / Scroll / Layer（独立分组）
待实现 ⬜
- ⬜ 为新增分组创建第二列 list 页面（缩略图卡片导航）
- ⬜ 为新增分组创建第三列内容页（中文说明 + Tabs + Demo + Prev/Next）
- ⬜ 统一现有页面的 Prev/Next（从“硬编码跳转”迁移到全局路由表）