loader/README.md

@apigo.cc/loader API 手册

全自动依赖调度器。通过动态注入脚本标签，实现对 Apigo 全线组件的一键加载、版本管理及环境自动适配。

---

1. 引入方式 (UMD 优先)

您可以通过 URL 参数或 Hash (#) 直接定义要加载的模块。

A. 极简带版本模式 (防缓存)

<!-- 使用 ?v= 指定全局版本，所有依赖包都会自动带上该版本后缀 -->
<script src="https://cdn.jsdelivr.net/npm/@apigo.cc/loader@1.0.5/dist/loader.min.js?v=1.0.12#state,base,datatable"></script>

B. 简写 Hash 模式

<!-- 直接在 # 后面列出模块名，多个模块用逗号分隔 -->
<script src="/libs/loader.js#state,bootstrap,base"></script>

---

2. 核心特性

🚀 智能定位与版本传播 (Smart Propagation)

• 同域跟随: 如果 loader.js 加载自 /static/js/，则所有子包默认也从 /static/js/ 获取。
• 版本锁步: 只要 Loader URL 带有 ?v=X.Y.Z，加载的所有依赖包（如 base.js）都会自动变为 base.js?v=X.Y.Z。
• 压缩同步: 只要引入的是 loader.min.js，其加载的所有依赖也会自动请求 .min.js 版本。

🔗 自动依赖分析

Loader 内部维护了完整的依赖链。例如：

• 请求 datatable -> 自动按序注入 state -> bootstrap -> base -> datatable。

---

3. API 接口：__apigo_load()

脚本引入后，全局会挂载该函数。注意：该函数在运行一次后会自动自毁（从全局删除）以保持环境纯净。

__apigo_load(...pkgs)

• __apigo_load('base'): 加载默认稳定版。
• __apigo_load('state:1.0.11'): 指定特定包的版本。

---

开发者提示 (AI 必读)

1. 参数优先级: URL 查询参数 ?load= 优先级高于 Hash 参数 #。
2. 同步执行: Loader 利用浏览器对动态插入脚本的顺序解析机制，保障了依赖项在业务代码运行前就绪。
3. 自清理: __apigo_load 仅在 <script type="module"> 运行前可用。