Files
marqdo/doc/design/ext-web-customization/07-assets-script-lifecycle.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

2.2 KiB
Executable File
Raw Blame History

解决 7:静态资源与脚本生命周期

问题 研究 §7
优先级 P2 · 波次 C3
触点 web_page_head / web_head · render.rs head 输出 · static 挂载 · web-assets-and-images.md

1. 目标

  1. 默认脚本加载方式不假设作者手写 IIFE 抢在 DOM 前执行成功;提供 defer / module 一等约定。
  2. 静态资源变更可发现:文档化 ?v=,并提供可选自动指纹或 listen 时 mtime 查询参数。

2. 作者 API(草案)

Head 资源表扩展列(向后兼容):

列 说明
rel / 关系 已有;script / module
defer / 推迟 真 → <script defer>(建议默认对 script 为真)
async / 异步 可选
version / 版本 非空则自动追加 ?v=
`头` =
| 关系 | 地址 | 推迟 | 版本 |
|------|------|------|------|
| script | /static/theme.js | 真 | 2026-09-04 |
| module | /static/desk.js | 真 | 3 |

全局:app.asset_version="2026-09-04" 为所有 static 链接统一 bump(可选)。


3. 插件改动点

改动 说明
head 渲染 尊重 defer/async;module → type="module"(已有则核对)
默认 新建 scaffold 的 script 行带 defer
(可选)asset_version listen 时重写 head / 页面内 static URL
文档 「禁止在同步 head 脚本里直接 getElementById 主节点;用 defer 或 DOMContentLoaded」

4. 兼容策略

  • 旧表无 defer 列:保持现网同步行为(或仅对 scaffold/新文档默认 defer,避免静默改变旧站时序)。
  • 更安全:缺省仍同步;Skill 与 scaffold 默认写 defer=真。

5. 验收

场景 期望
defer 脚本读 DOM 登录跳转逻辑在 DOM 就绪后执行
version 列 HTML 中出现 theme.js?v=…
旧示例无新列 仍通过

6. 过渡期 workaround

脚本改 type=module 或放 body 末;手动 ?v= bump;登录逻辑用 DOMContentLoaded。