# @apigo.cc/loader API 手册

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

---

## 1. 引入方式 (UMD 优先)

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

### A. 极简带版本模式 (防缓存)
```html
<!-- 使用 ?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 模式
```html
<!-- 直接在 # 后面列出模块名，多个模块用逗号分隔 -->
<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">` 运行前可用。