@web/base AI 开发指南 (全面版)

@web/base 是基于 State.js 构建的高性能 Web 基础组件库。它采用原生 ESM、零打包架构，深度集成 Bootstrap 5，旨在为 AI 驱动的开发提供极致精简且功能完备的 UI 与逻辑基建。

---

一、 快速开始

1. 引入依赖

在 HTML 中配置 importmap。推荐使用 loader.js 自动管理：

<!-- 依赖 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 (数据)。

<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>	支持折叠的树结构。

示例 (动态高度列表):

<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(() => { ... }) 中。