# @apigo.cc/base - AI 逻辑操作说明书 (示例驱动)
本库是基于 `@apigo.cc/state` 增强的 UI 原子库，提供遵循 Bootstrap 5.3 规范的高阶业务组件。本包采用完全的全局注入模式。
---
## 全局变量与核心 API 清单
引入 `base.js` 后，以下对象将直接挂载到 `window` / `globalThis` 上，可随时随地调用：
| 全局变量名 | 用途说明 |
| :--- | :--- |
| **`HTTP`** | 异步请求工具 (`HTTP.get`, `HTTP.post`, `HTTP.request` 等)。 |
| **`UI`** | 交互组件触发器 (`UI.toast`, `UI.alert`, `UI.confirm`, `UI.showDialog`)。 |
| **`AutoForm`** | 表单组件扩展注册器 (`AutoForm.register`) 和自定义控件库 (`AutoForm.customTypes`)。 |
| **`MouseMover`** | 拖拽辅助工具 (`MouseMover.start`)。 |
| **`VirtualScroll`** / **`List`** | 虚拟滚动列表核心算法类。 |
*(注意：底层状态库 `@apigo.cc/state` 暴露的 `NewState`, `Hash`, `LocalStorage`, `State`, `$`, `$$`, `Component` 以及危险的高级 API `_unsafeRefreshState` 也在全局可用。严禁随意调用 `_unsafeRefreshState`。)*
---
## 1. 快速集成 (Quick Start)
将脚本放置在 `` 中，确保地基在 DOM 解析前就绪：
```html
```
---
## 2. 组件超能力示例 (Mega Examples)
### 2.1 声明式数据组件 (``)
```html
```
* **AI 核心要点**：
* **请求响应结构 (ResponseObject)**：
`{ ok: Boolean, status: Number, headers: Object, responseType: 'json'|'binary'|'text', result: Any, error: String|null }`
* 深度监听 `request` 任何字段的改变自动触发请求（微任务防抖）。`response` 事件为 `bubbles: false`，`error` 为 `bubbles: true`。
---
### 2.2 万能表单与内嵌控件 (``)
```html
```
* **AI 核心要点**：
* 容器属性：`vertical` (垂直排列)、`inline` (无边框流式行内布局)、`nobutton` (隐藏底部默认按钮)。
* **表单数据操作红线**：禁止对 `form.state.data` 或 `form.data` 执行覆盖式重新赋值，必须使用 `Object.assign`。
---
### 2.3 增强列表组件 (``)
列表有三类布局模式，分别有不同的数据结构关联，均推荐在 HTML 中声明绑定：
#### 模式一：普通扁平列表 (`mode="normal"`)
* **关联逻辑**：直接渲染一维数组项。
* **数据结构**：
```javascript
const userList = [
{ id: '1', label: '小明', summary: '前端开发' },
{ id: '2', label: '小红', summary: '产品经理' }
];
```
* **HTML 写法**：
```html
```
#### 模式二：分组列表 (`mode="group"`)
* **关联逻辑**：`list` 的项通过 `group` 字段去匹配 `groups` 数组中的 `id` 字段。
* **数据结构**：
```javascript
const deptGroups = [
{ id: 'devGroup', label: '研发中心', summary: '共 5 人' },
{ id: 'hrGroup', label: '人力资源', summary: '共 2 人' }
];
const groupUserList = [
{ id: '1', label: '小明', group: 'devGroup' },
{ id: '2', label: '小红', group: 'hrGroup' }
];
```
* **HTML 写法**：
```html
```
#### 模式三：树形可折叠列表 (`mode="tree"`) —— 超级示例
* **关联逻辑**：通过每项的 `parent` 关联父项的 `id` 属性，根项的 `parent` 设为空字符串 `''`。
* **数据结构**（内置 `_itemHeight` 优化虚拟滚动高度测量）：
```javascript
const deptTreeList = [
{ id: '1', label: '总经办', parent: '', _itemHeight: 40 },
{ id: '2', label: '研发部', parent: '1', _itemHeight: 40 },
{ id: '3', label: '开发组', parent: '2', _itemHeight: 40 }
];
```
* **HTML 写法**：
```html
```
* **AI 核心要点**：
* **属性默认值**：当数据结构符合默认字段命名（`id`, `label`, `summary`, `parent`, `group`）时，**无须填写**任何映射属性（如 `idfield`, `labelfield`, `parentfield` 等），实际编写代码时应当将其省略。
* 虚拟滚动 (`fast`) 强制容器必须声明为 `overflow-auto` 类。
---
### 2.4 导航组件 (`