dataTable/README.md

@web/datatable AI 开发指南

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

---

一、 快速开始

1. 引入依赖

<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. 虚拟滚动与 AOT 预编译

通过 $.state.list 绑定大数据集。组件采用 AOT (Ahead-of-Time) 模板预编译技术，自动消除嵌套循环，实现万级数据的秒级渲染。

2. 极速排序与筛选

支持本地数据的瞬间排序与筛选。

• 交互: 点击表头下拉菜单，支持升序/降序、文本搜索。
• 性能: 基于 _refExt 注入机制，更新 800+ 单元格仅需百毫秒级 Paint 耗时。

3. 多维编辑

• 行内编辑: 双击单元格利用 AutoForm 自动匹配类型。高度自适应父容器，支持 textarea, switch 等。
• 状态同步: 利用全局 State 机，实现零延迟的数据回写。

4. 固定列与紧凑状态栏

• 在 fields 定义中设置 pinned: 'left' 或 pinned: 'right'。
• 底部状态栏采用 1 / 1000 紧凑格式，集成快捷删除按钮。

---

三、 API 参考

<DataTable> 属性与事件

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

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

字段定义结构 (field):

{
  "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">。