# @web/datatable AI 开发指南

`@web/datatable` 是一个高性能、无状态的 Web 数据表格组件，支持万级数据虚拟滚动、多维编辑及固定列。

---

## 一、 快速开始

### 1. 引入依赖
```html
<script type="importmap">
{
  "imports": {
    "@web/state": "path/to/state.mjs",
    "@web/base": "path/to/base.mjs",
    "@web/datatable": "path/to/datatable.mjs"
  }
}
</script>
```

### 2. 导出清单
*   **Components**: `<DataTable>`

---

## 二、 核心功能

### 1. 虚拟滚动
通过 `$.state.list` 绑定大数据集，组件将自动启用虚拟滚动。

### 2. 多维编辑
*   **简单类型**: 双击单元格直接编辑（支持 `text`, `number`, `select`）。
*   **复杂类型**: 双击触发 `Modal` 浮层编辑（支持 `json`, `object`, `array` 等）。

### 3. 固定列
在 `fields` 定义中设置 `pinned: 'left'` 或 `pinned: 'right'`。

---

## 三、 API 参考

### `<DataTable>` 属性与事件

| 属性 | 类型 | 说明 |
| :--- | :--- | :--- |
| `$.state.fields` | `Array` | 字段定义清单 |
| `$.state.list` | `Array` | 数据列表 |

| 事件 | 参数 | 说明 |
| :--- | :--- | :--- |
| `@update` | `{row, field, value, oldValue, isComplex}` | 单元格或复杂编辑器数据更新 |
| `@delete` | `{row}` | 行删除请求 |

**字段定义结构 (`field`):**
```json
{
  "id": "unique_id",
  "name": "Display Name",
  "type": "text | number | select | json",
  "width": 150,
  "pinned": "left | right",
  "options": ["A", "B"] // 仅 select 类型
}
```

---

## 四、 最佳实践
1. **保持无状态**：始终通过 `@update` 事件在外部更新数据源。
2. **样式隔离**：优先使用组件提供的工具栏插槽 `<div slot="toolbar">`。