# @apigo.cc/base - AI 逻辑操作说明书 (示例驱动)
本库是基于 `@apigo.cc/state` 增强的 UI 原子库，提供遵循 Bootstrap 5.3 规范的高阶业务组件。
---
## 1. 快速集成 (Quick Start)
### 同步 UMD 集成 (推荐：消灭异步时序风险，实现“秒开”渲染)
将脚本放置在 `` 中，确保地基在 DOM 解析前就绪：
```html
```
### ESM 模块引入 (Legacy)
```javascript
import { HTTP, UI, AutoForm, State } from '@apigo.cc/base'
```
---
## 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 导航组件 (`