Inicio Explorar Axuda
Rexistro Iniciar sesión
robert
/
xjs
1
0
Fork 0
Ficheiros Incidencias 0 Pull Requests 0 Wiki
Rama: main
Ramas Etiquetas
xjs
/
doc
/
module.md

module.md 10 KB
Permalink Histórico Raw

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)，用于跟随第三列自动高亮

  • 第三列（右侧）

    • 每个示例是一个独立 HTML 页面（例如 doc/targets/test_css_selector.html）
    • 内容页在加载时会调用 window.parent.setMiddleActive('xxx.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（统一走父窗口的全局路由表）

内容页必须做两件事（保证三列联动）：

  1. 同步第二列高亮

    try { window.parent?.setMiddleActive?.('group/test_xxx.html'); } catch {}

  2. 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.html
  • group 用于 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（从“硬编码跳转”迁移到全局路由表）