104 lines
3.6 KiB
Markdown
104 lines
3.6 KiB
Markdown
# @web/base AI 开发指南 (全面版)
|
||
|
||
`@web/base` 是基于 State.js 构建的高性能 Web 基础组件库。它采用**原生 ESM、零打包**架构，深度集成 Bootstrap 5，旨在为 AI 驱动的开发提供极致精简且功能完备的 UI 与逻辑基建。
|
||
|
||
---
|
||
|
||
## 一、 快速开始
|
||
|
||
### 1. 引入依赖
|
||
在 HTML 中配置 `importmap`。推荐使用 `loader.js` 自动管理：
|
||
|
||
```html
|
||
<!-- 依赖 Bootstrap 5 -->
|
||
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
|
||
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
|
||
|
||
<script type="importmap">
|
||
{
|
||
"imports": {
|
||
"@web/state": "path/to/state.mjs",
|
||
"@web/base": "path/to/base.mjs"
|
||
}
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 2. 导出清单
|
||
* **Logic**: `HTTP`, `UI`, `State`, `MouseMover`
|
||
* **Components**: `<API>`, `<Modal>`, `<Dialog>`, `<Toast>`, `<AutoForm>`, `<TagsInput>`, `<FastList>`, `<List>`, `<GroupedList>`, `<FastGroupedList>`, `<Tree>`, `<FastTree>`, `<CollapseTree>`, `<Nav>`, `<Resizer>`
|
||
|
||
---
|
||
|
||
## 二、 核心组件详述
|
||
|
||
### 1. 网络与数据 (`HTTP` & `<API>`)
|
||
* **`HTTP`**: 静态请求工具（`get`, `post`, `put`, `delete`, `request`）。
|
||
* **`<API>`**: 声明式请求容器。
|
||
* `$.request.url`: 请求地址。
|
||
* `auto`: 属性存在时，url 变化自动触发请求。
|
||
* `@response`: 请求成功事件。
|
||
|
||
### 2. UI 交互 (Namespace `UI`)
|
||
* `UI.alert(msg)` / `UI.confirm(msg)`: 基础对话框。
|
||
* `UI.toast(msg, {type: 'success'})`: 自动消失的轻提示。
|
||
|
||
### 3. 数据驱动表单 (`<AutoForm>`)
|
||
核心配置项：`$.state.schema` (结构) 和 `$.state.data` (数据)。
|
||
|
||
```html
|
||
<AutoForm
|
||
$.state.schema="[
|
||
{name:'user', type:'text', label:'用户名', required:true},
|
||
{name:'role', type:'select', options:['Admin', 'User'], label:'角色'}
|
||
]"
|
||
$.state.data="myData">
|
||
</AutoForm>
|
||
```
|
||
|
||
### 4. 高性能列表 (`<FastList>` 家族)
|
||
支持万级数据、动态高度、虚拟滚动。
|
||
|
||
| 组件名 | 特点 |
|
||
| :--- | :--- |
|
||
| `<FastList>` | 基础虚拟滚动列表。 |
|
||
| `<FastGroupedList>` | 带分组的虚拟列表。 |
|
||
| `<FastTree>` | 虚拟滚动树。 |
|
||
| `<CollapseTree>` | 支持折叠的树结构。 |
|
||
|
||
**示例 (动态高度列表):**
|
||
```html
|
||
<FastList $.state.list="items">
|
||
<div slot="item" $.style.height="${item.h}px" $text="item.label"></div>
|
||
</FastList>
|
||
```
|
||
|
||
---
|
||
|
||
## 三、 组件详细清单与 API
|
||
|
||
### 逻辑类 (JS API)
|
||
* **`HTTP.request(opt)`**: 返回 `Promise`，结果包含 `ok`, `status`, `result`, `error`。
|
||
* **`UI.showDialog({title, message, buttons, type})`**: 弹出自定义对话框。
|
||
* **`MouseMover.start(event, callbacks)`**: 全局鼠标移动监听（用于拖拽）。
|
||
|
||
### 组件类 (Custom Elements)
|
||
* **`<Modal>`**:
|
||
* `$bind="state.show"`: 双向绑定显隐。
|
||
* `slot-id="header/body/footer"`: 内容插槽。
|
||
* **`<TagsInput>`**: 标签录入，绑定数据为字符串数组。
|
||
* **`<Nav>`**: 响应式导航栏。
|
||
* `$.state.brand`: `{image, icon, label}`。
|
||
* `$.state.list`: 菜单数组。
|
||
* **`<Resizer>`**:
|
||
* `vertical`: 属性，切换水平/垂直。
|
||
* `min/max`: 限制尺寸。
|
||
|
||
---
|
||
|
||
## 四、 最佳实践 (AI 指令)
|
||
1. **拒绝手动 DOM 操作**: 优先使用 `$bind` 和 `$.state` 驱动 UI。
|
||
2. **列表性能**: 大数据量（>50条）强制使用 `Fast` 系列组件。
|
||
3. **样式优先**: 优先使用 Bootstrap 5 Utility classes (如 `d-flex`, `p-3`, `gap-2`)。
|
||
4. **微任务**: 涉及 DOM 尺寸计算的代码必须包裹在 `Promise.resolve().then(() => { ... })` 中。
|