bw-pro-table 0.0.1 → 0.0.3

package/README.md

@@ -1,20 +1,34 @@
 # BwProTable
 
-基于 **ant-design-vue 3/4** 的高级业务表格组件，提供 ProTable 级别的开箱即用体验。
+基于 **ant-design-vue 4** 的高级业务表格组件，提供 ProTable 级别的开箱即用体验。采用 Vue 3 Composition API + TypeScript 编写，提供完整的类型推导。
 
 ## 特性
 
-- 🚀 **双模式数据加载**：支持 `request` 异步请求模式 和 `dataSource` 静态数据模式，无缝切换
-- ✏️ **行内编辑**：单元格级/行级编辑、撤销/重做、字段校验、批量编辑
-- 🔍 **多管道筛选**：搜索栏 + 表头筛选 + 列头搜索，三套独立管道协同工作
-- 🎨 **12 种内置渲染器**：text、number、date、tag、image、link、progress、avatar、action、index、currency、boolean，支持 `defineColumnType` 自定义扩展
-- 📊 **列管理**：拖拽排序列、列显隐/列宽调节，支持持久化到 localStorage
-- 📎 **Excel 导入导出**：支持 xlsx 导出/导入预览/模板下载（xlsx 按需动态加载）
-- ✅ **跨页多选**：跨页保持选中状态，支持全选所有页
-- 🔄 **工具栏**：刷新、密度切换、全屏、列设置、边框/斑马纹切换
-- 💾 **状态持久化**：列配置、分页、密度、筛选、排序自动持久化，可选 sessionStorage 或自定义 StorageAdapter
-- ⌨️ **键盘导航**：方向键行导航，支持 Enter/Space/Delete 等快捷键
-- 🎯 **TypeScript 全类型支持**：完整的 Props/Events/Slots/Methods 类型推导
+### 已集成功能
+
+- 🚀 **双模式数据加载**：`request` 异步请求模式 与 `dataSource` 静态数据模式互斥，支持自动竞态保护与页码越界校验
+- 🎨 **12 种内置渲染器**：`text`、`number`、`date`、`tag`、`image`、`link`、`progress`、`avatar`、`action`、`index`、`currency`、`boolean`（含 `enum` 别名），支持 `defineColumnType` 注册自定义类型
+- 🔍 **三管道筛选系统**：搜索栏 + 表头筛选（ant-design-vue 原生）+ 列头搜索（Popover），独立运行并合并为 `mergedSearchParams`
+- 📊 **客户端筛选与排序**：DataSource 模式下自动应用 `applyClientFilters`（三管道合并）与 `applyClientSort`（支持自定义 sorter 函数）
+- ✏️ **行内编辑**：单元格级 / 行级双模式编辑，草稿数据管理，字段校验（required/type/min/max/pattern/validator），撤销/重做（Command Pattern），批量编辑
+- 📋 **列管理**：HTML5 拖拽排序列、列宽调节（rAF 批处理节流）、列显隐设置面板，特殊列自动排除
+- 💾 **状态持久化**：列配置、分页、密度、筛选、排序持久化到 `localStorage` / `sessionStorage` / 自定义 `StorageAdapter`，支持版本管理与数据校验
+- ✅ **跨页多选**：跨页保持选中状态，支持全选所有页（DataSource 内存 / Request 回调），最大选择数限制
+- 📎 **Excel 导入导出**：xlsx 按需懒加载，导出 Excel/CSV/选中行，导入预览/自动列映射/校验/模板下载
+- 🔄 **工具栏**：刷新、密度切换、全屏、列设置、边框/斑马纹切换、清除筛选、选中计数显示
+- 🌐 **国际化**：vue-i18n 集成，`locale` prop 部分覆写，优先级：`props.locale` > `vue-i18n` > `zh-CN` 默认
+- 🎯 **TypeScript 全类型支持**：完整的 Props / Events / Slots / Methods / Composables 类型导出
+
+### 已编码但未集成的功能
+
+以下功能已在 `composables/` 中实现对应逻辑，类型定义已就绪，但**尚未在主组件 `BwProTable.vue` 中集成**，运行时不生效。详见 [未集成功能说明](#未集成功能说明) 章节。
+
+- 右键菜单（`BwProTableContextMenu.vue`）
+- 高级筛选面板（`BwProTableAdvancedFilter.vue`）
+- 视图管理（`useTableView`）
+- 键盘导航（`useBwKeyboard`）
+- 权限过滤（`useBwPermission`）
+- 行拖拽排序（`useDragSort`）
 
 ## 安装
 
@@ -24,19 +38,22 @@ npm install bw-pro-table
 
 ### 依赖要求
 
+**必选 peerDependencies**：
+
 | 依赖 | 版本 | 说明 |
 |------|------|------|
 | `vue` | `^3.3.0` | 核心框架 |
-| `ant-design-vue` | `^3.2.0 \|\| ^4.0.0` | UI 组件库 |
-| `@ant-design/icons-vue` | `^6.0.0 \|\| ^7.0.0` | 图标库 |
-| `dayjs` | `^1.11.0` | 日期处理 |
+| `ant-design-vue` | `^4.0.0` | UI 组件库 |
+| `@ant-design/icons-vue` | `^7.0.0` | 图标库 |
+| `dayjs` | `^1.11.0` | 日期处理（渲染器与编辑态使用） |
+| `vue-i18n` | `^9.0.0 \|\| ^10.0.0 \|\| ^11.0.0` | 国际化 |
 
-**可选依赖**（按需安装）：
+**可选 peerDependencies**（按需安装）：
 
-| 依赖 | 说明 |
-|------|------|
-| `xlsx` | Excel 导入导出功能需要 |
-| `screenfull` | 全屏切换功能需要 |
+| 依赖 | 说明 | 何时需要 |
+|------|------|----------|
+| `xlsx` | `^0.18.0` | Excel 导入导出功能（按需动态 `import()` 懒加载） |
+| `screenfull` | `^6.0.0` | 工具栏全屏切换功能 |
 
 ## 快速开始
 
@@ -91,8 +108,8 @@ const fetchUsers = async (params: {
 };
 
 const rowSelection = {
-  type: 'checkbox',
-  onChange: (keys: any[], rows: any[]) => {
+  type: 'checkbox' as const,
+  onChange: (keys: (string | number)[], rows: User[]) => {
     console.log('选中:', keys, rows);
   },
 };
@@ -103,161 +120,445 @@ const rowSelection = {
 
 ### Props
 
+#### 核心数据
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `columns` | `ProColumnsType<RecordType>` | **必填** | 列定义数组，详见 [ProColumnType](#procolumntype-列定义) |
+| `request` | `(params) => Promise<{data, total, success}>` | - | 异步数据请求函数，与 `dataSource` 互斥 |
+| `dataSource` | `RecordType[]` | - | 静态数据源，与 `request` 互斥 |
+| `rowKey` | `string \| GetRowKey` | `'id'` | 行唯一标识字段名或函数（函数式 rowKey 时编辑/选择等功能可能受限，建议用字符串） |
+| `tableId` | `string` | 随机生成 | 表格唯一标识，持久化命名空间必需 |
+| `cacheKey` | `string` | - | 持久化缓存键（与 `tableId` 二选一，优先使用 `cacheKey`） |
+| `title` | `string` | - | 表格标题（显示在工具栏） |
+
+#### 搜索
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `search` | `boolean \| SearchConfig` | - | 搜索栏配置，`false` 隐藏搜索栏，`true` 全部使用默认值 |
+| `columnSearch` | `false \| HeaderSearchConfig` | - | 列头搜索全局配置，`false` 禁用所有列的 `headerSearch` |
+
+> **SearchConfig**：`{ labelWidth?: number; defaultCollapsed?: boolean; resetText?: string; searchText?: string; collapsedCount?: number; colon?: boolean }`
+
+#### 工具栏
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `toolbar` | `false \| ToolbarConfig` | - | 工具栏配置，`false` 隐藏整个工具栏 |
+
+> **ToolbarConfig**：`{ refresh?: boolean; density?: boolean; fullscreen?: boolean; columnSetting?: boolean; export?: boolean \| ExportConfig; clearFilter?: boolean; import?: boolean \| ImportConfig; viewManager?: boolean; bordered?: boolean; striped?: boolean }`
+
+#### 功能配置
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `editConfig` | `EditConfig` | - | 行内编辑配置，详见 [行内编辑](#行内编辑) |
+| `dragConfig` | `DragConfig` | - | 拖拽配置（当前仅 `columnDraggable` 生效） |
+| `rowSelection` | `TableRowSelection` | - | 行选择配置（透传 ant-design-vue） |
+| `crossPageSelection` | `false \| CrossPageSelectionConfig` | - | 跨页多选配置，`false` 禁用 |
+| `exportConfig` | `ExportConfig` | - | 导出配置（也可通过 `toolbar.export` 传入） |
+| `importConfig` | `ImportConfig` | - | 导入配置（也可通过 `toolbar.import` 传入） |
+| `contextMenu` | `ContextMenuConfig` | - | 右键菜单配置（**类型已定义，运行时未集成**） |
+| `persistence` | `false \| PersistenceConfig` | - | 持久化配置，`false` 禁用 |
+
+#### 样式与透传
+
 | 参数 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `columns` | `ProColumnsType` | **必填** | 列定义数组 |
-| `request` | `(params) => Promise<{data, total, success}>` | - | 异步数据请求函数，与 dataSource 互斥 |
-| `dataSource` | `any[]` | - | 静态数据源，与 request 互斥 |
-| `rowKey` | `string` | `'id'` | 行数据唯一标识字段名 |
-| `title` | `string` | - | 表格标题 |
 | `size` | `'small' \| 'middle' \| 'default'` | `'default'` | 表格尺寸 |
-| `pagination` | `false \| TablePaginationConfig` | `{}` | 分页配置，设为 false 禁用 |
 | `bordered` | `boolean` | `false` | 是否显示边框 |
 | `striped` | `boolean` | `false` | 是否显示斑马纹 |
+| `defaultEmptyText` | `string` | `'-'` | 空单元格占位符（`null`/`undefined`/`''` 时显示） |
+| `loading` | `boolean` | - | 外部加载态（与内部状态机合并） |
+| `pagination` | `false \| TablePaginationConfig` | `{}` | 分页配置，`false` 禁用分页 |
 | `scroll` | `{ x?, y? }` | - | 表格滚动配置 |
 | `sticky` | `boolean \| { offsetHeader? }` | - | 表头固定 |
-| `search` | `false \| SearchConfig` | - | 搜索栏配置，false 隐藏 |
-| `toolbar` | `false \| ToolbarConfig` | - | 工具栏配置，false 隐藏 |
-| `tableId` | `string` | 随机生成 | 表格唯一标识，持久化必需 |
-| `cacheKey` | `string` | - | 持久化缓存键（与 tableId 二选一） |
-| `persistence` | `false \| PersistenceConfig` | - | 持久化配置 |
-| `editConfig` | `EditConfig` | - | 行内编辑配置 |
-| `dragConfig` | `DragConfig` | - | 列拖拽配置 |
-| `rowSelection` | `TableRowSelection` | - | 行选择配置 |
-| `crossPageSelection` | `false \| CrossPageSelectionConfig` | - | 跨页多选配置 |
-| `exportConfig` | `ExportConfig` | - | 导出配置 |
-| `importConfig` | `ImportConfig` | - | 导入配置 |
-| `viewConfig` | `ViewConfig` | - | 视图管理配置 |
 | `expandable` | `ExpandableConfig` | - | 行展开配置 |
+| `rowClassName` | `(record, index) => string` | - | 行 className 函数（与内置斑马纹/选中样式合并） |
+| `class` | `string` | - | 表格根元素 CSS 类名 |
+| `style` | `CSSProperties` | - | 表格根元素样式 |
+| `locale` | `Partial<BwProTableLocale>` | - | 国际化语言包，传入部分字段即可覆写 |
 
 ### Events
 
 | 事件 | 参数 | 说明 |
 |------|------|------|
-| `load` | `{ dataSource, total }` | 数据加载完成 |
+| `load` | `{ dataSource: any[], total: number }` | 数据加载成功完成 |
 | `error` | `Error` | 数据加载失败 |
-| `change` | `(pagination, filters, sorter, extra)` | 表格变化（排序/筛选） |
-| `resizeColumn` | `(width, column)` | 列宽调整 |
+| `change` | `(pagination, filters, sorter, extra)` | 表格变化（分页/排序/筛选），`extra` 含 `action: 'paginate' \| 'sort' \| 'filter'` 和 `currentDataSource: any[]` |
+| `resizeColumn` | `(width: number, column: ProColumnType)` | 列宽调整 |
 
 ### Methods（通过 ref 调用）
 
-| 方法 | 说明 |
-|------|------|
-| `fetchData()` | 手动刷新数据 |
-| `getSelectedRowKeys()` | 获取当前页选中行 keys |
-| `getSelectedRows()` | 获取当前页选中行数据 |
-| `getDataSource()` | 获取当前数据源 |
-| `clearSelection()` | 清空跨页选择 |
-| `getCrossPageSelectedKeys()` | 获取跨页选中的 keys |
-| `getCrossPageSelectedRows()` | 获取跨页选中的行数据 |
+#### 数据与选择
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `fetchData` | `() => Promise<void>` | 手动刷新数据 |
+| `getDataSource` | `() => any[]` | 获取当前数据源 |
+| `getSelectedRowKeys` | `() => (string \| number)[]` | 获取当前页选中行 keys |
+| `getSelectedRows` | `() => any[]` | 获取当前页选中行数据 |
+| `clearSelection` | `() => void` | 清空所有选择（含跨页） |
+| `getCrossPageSelectedKeys` | `() => (string \| number)[]` | 获取跨页选中的所有 keys |
+| `getCrossPageSelectedRows` | `() => (any \| null)[]` | 获取跨页选中的行数据（Request 模式下部分可能为 `null`） |
+
+#### 行内编辑
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `startRowEdit` | `(rowKey) => Promise<void>` | 进入行编辑模式 |
+| `startCellEdit` | `(rowKey, field) => Promise<void>` | 进入单元格编辑模式 |
+| `saveEdit` | `(rowKey) => Promise<boolean>` | 保存编辑（返回是否校验通过） |
+| `cancelEdit` | `(rowKey, field?) => void` | 取消编辑（传入 field 时仅取消该单元格） |
+| `addRow` | `(position?: 'top' \| 'bottom') => void` | 新增空行（默认追加到底部） |
+| `cloneRow` | `(rowKey) => void` | 克隆行（插入到顶部） |
+| `deleteRow` | `(rowKey) => Promise<void>` | 删除单行 |
+| `deleteRows` | `(keys) => Promise<void>` | 批量删除行 |
+| `isCellEditing` | `(rowKey, field) => boolean` | 判断单元格是否编辑中 |
+| `getEditingKeys` | `() => Set<string \| number>` | 获取当前编辑中的行 keys |
+| `canUndo` | `() => boolean` | 是否可撤销 |
+| `canRedo` | `() => boolean` | 是否可重做 |
+| `undo` | `() => void` | 撤销 |
+| `redo` | `() => void` | 重做 |
+| `openBatchEdit` | `() => void` | 打开批量编辑弹窗 |
+
+#### 导入导出
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `exportExcel` | `() => Promise<void>` | 导出 Excel |
+| `exportCsv` | `() => Promise<void>` | 导出 CSV |
+| `exportSelected` | `(rows, keys?) => Promise<void>` | 导出选中行 |
+| `openFileDialog` | `() => void` | 打开导入文件对话框 |
+| `downloadTemplate` | `(columns: { title: string; dataIndex: string }[]) => Promise<void>` | 下载导入模板 |
 
 ### Slots
 
-| 插槽名 | 说明 |
-|--------|------|
-| `search` | 自定义搜索栏 |
-| `toolbar` | 自定义工具栏 |
-| `toolbar-extra` | 工具栏左侧额外内容 |
-| 动态列插槽 | `bodyCell`、`headerCell` 等 ant-design-vue 原生插槽均支持 |
+| 插槽名 | 作用域参数 | 说明 |
+|--------|-----------|------|
+| `search` | - | 自定义整个搜索栏（替换默认组件） |
+| `toolbar` | - | 自定义整个工具栏（替换默认组件） |
+| `toolbar-extra` | - | 工具栏左侧额外内容（追加到默认工具栏） |
+| `toolbar-right` | - | 工具栏右侧额外内容（追加到内置按钮组左侧） |
+| `bodyCell` | `{ column, record, index, text, value }` | 自定义单元格渲染（覆盖 valueType 渲染器） |
+| `headerCell` | `{ column }` | 自定义表头单元格（列头搜索 Popover 仍会追加在右侧） |
+
+> **插槽透传机制**：除上述具名插槽外，所有 ant-design-vue Table 原生插槽均通过 `v-for="$slots"` 透传支持。
 
 ## ProColumnType 列定义
 
+`ProColumnType` 在 ant-design-vue `TableColumnType` 基础上扩展以下字段：
+
 ```ts
-interface ProColumnType<RecordType = any> extends ColumnType<RecordType> {
+interface ProColumnType<RecordType = any> extends Omit<TableColumnType<RecordType>, 'children'> {
   // === 值渲染 ===
   valueType?: ValueType;           // 内置渲染器类型
-  valueEnum?: ValueEnumMap;        // 枚举值映射（tag 渲染）
-  customRender?: RenderFn;         // 自定义渲染函数
+  valueEnum?: ValueEnumMap;        // 枚举值映射（tag/enum 渲染 + 搜索栏 select）
+  dateFormat?: string;             // 日期格式（valueType='date'，默认 'YYYY-MM-DD'）
+  precision?: number;              // 小数精度（valueType='number'/'currency'）
+  currencyPrefix?: string;         // 货币前缀（默认 '¥'）
+  currencySuffix?: string;         // 货币后缀（默认 ''）
+  customRender?: RenderFn;         // 自定义渲染函数（无 valueType 匹配时回退）
+
+  // === 空值与溢出 ===
+  emptyText?: string;              // 空单元格占位符（覆盖全局 defaultEmptyText）
+  overflow?: 'ellipsis' | 'wrap' | 'clip'; // 溢出策略
 
   // === 搜索 ===
-  search?: boolean | SearchFieldConfig; // 搜索栏字段配置
-  headerSearch?: boolean;          // 列头搜索（仅 text 类型）
+  search?: boolean | SearchFieldConfig;    // 搜索栏字段配置（true 启用自动匹配控件）
+  headerSearch?: boolean | HeaderSearchConfig; // 列头搜索（仅 valueType='text' 生效）
+  renderFormItem?: (context: { model, search, resetField }) => VNode; // 自定义搜索表单控件
+  hideInSearch?: boolean;              // 是否在搜索栏中隐藏该列（默认 false）
 
   // === 编辑 ===
-  editable?: boolean;              // 是否可编辑
+  editable?: boolean | ((record) => boolean); // 是否可编辑
   formRules?: FormRule[];          // 编辑校验规则
-  editComponent?: string | Component; // 自定义编辑组件
-  editProps?: Record<string, any>; // 编辑组件属性
+  editComponent?: string;          // 编辑态组件类型（当前按 valueType 自动匹配）
+  editComponentProps?: Record<string, any>;   // 编辑态组件额外属性
+
+  // === 渲染器专属 ===
+  actions?: ActionItem[];          // 操作列按钮（valueType='action'）
+  imageWidth?: number;             // 图片宽度（默认 32）
+  imageHeight?: number;            // 图片高度（默认 32）
+  linkProps?: { href?, target?, onClick? };   // 链接配置
+  progressProps?: { strokeColor? };           // 进度条配置
+  avatarProps?: { srcField?, nameField?, showName?, size?, shape? }; // 头像配置
+  booleanSwitch?: boolean;         // 布尔列使用 Switch 开关（默认图标）
 
   // === 其他 ===
   hidden?: boolean;                // 是否隐藏列
-  copyable?: boolean;              // 是否可复制
-  ellipsis?: boolean;              // 是否省略
-  tooltip?: string | Function;     // 提示
+  description?: string;            // 表头说明文字（Tooltip 显示）
+  columnGroup?: string;            // 列所属分组
+  authority?: string | string[];   // 列级权限标识（类型已定义，运行时未集成）
+  children?: ProColumnsType;       // 子列（分组表头）
+}
+```
+
+### ActionItem 操作列按钮
+
+```ts
+interface ActionItem<RecordType = any> {
+  label: string;                                    // 按钮文字
+  type?: 'primary' | 'dashed' | 'link' | 'text' | 'default'; // 按钮类型（默认 'link'）
+  danger?: boolean;                                 // 危险操作样式
+  icon?: string;                                    // @ant-design/icons-vue 图标名
+  confirm?: string;                                 // 气泡确认文案（设置后点击先弹 Popconfirm）
+  authority?: string | string[];                    // 权限标识（未集成）
+  disabled?: boolean | ((record) => boolean);       // 是否禁用
+  hidden?: boolean | ((record) => boolean);         // 是否隐藏
+  onClick?: (record, index) => void | Promise<void>; // 点击回调
+}
+```
+
+### FormRule 校验规则
+
+```ts
+interface FormRule {
+  required?: boolean;               // 是否必填
+  message?: string;                 // 校验失败消息
+  type?: 'string' | 'number' | 'boolean' | 'email' | 'url'; // 值类型
+  min?: number;                     // 最小值（number 类型）或最小长度（string 类型）
+  max?: number;                     // 最大值（number 类型）或最大长度（string 类型）
+  pattern?: RegExp;                 // 正则校验
+  validator?: (value, record) => Promise<void> | void; // 自定义校验（throw 或 reject 表示失败）
 }
 ```
 
-## ValueType 内置渲染器
+## ValueType 渲染器
+
+### 内置渲染器
+
+| valueType | 渲染输出 | 支持的额外列属性 |
+|-----------|----------|------------------|
+| `text` | 文本 + Tooltip（`ellipsis !== false` 时） | `emptyText`、`ellipsis` |
+| `number` | 千分位格式化数字 | `precision`、`emptyText` |
+| `date` | dayjs 格式化日期 | `dateFormat`（默认 `'YYYY-MM-DD'`）、`emptyText` |
+| `currency` | 货币符号 + 千分位 | `precision`、`currencyPrefix`（默认 `'¥'`）、`currencySuffix`、`emptyText` |
+| `tag` / `enum` | `a-tag` + 颜色 | `valueEnum`、`emptyText` |
+| `image` | `a-image` 缩略图（含预览） | `imageWidth`（默认 32）、`imageHeight`（默认 32）、`emptyText` |
+| `link` | `<a>` 链接 + `LinkOutlined` 图标 | `linkProps: { href?(无时默认 `'#'` 并阻止跳转), target?(默认 `'_blank'`, 自动设 `rel='noopener noreferrer'`), onClick?: (record, event) => void }`、`emptyText` |
+| `progress` | `a-progress` 进度条 | `progressProps: { strokeColor? }`、`emptyText` |
+| `avatar` | `a-avatar` + 名称 | `avatarProps: { srcField?(默认 `'avatar'`), nameField?(默认 `'name'`), showName?(默认 `true`), size?(默认 32), shape?(默认 `'circle'`) }`、`emptyText` |
+| `boolean` | ✓/✗ 图标（默认）或 `a-switch`（`booleanSwitch: true`） | `booleanSwitch`、`emptyText` |
+| `action` | 按钮组 + Popconfirm | `actions: ActionItem[]` |
+| `index` | 行号（`index + 1`） | - |
 
-| valueType | 说明 | 支持的额外属性 |
-|-----------|------|----------------|
-| `text` | 文本 | `copyable` |
-| `number` | 数字 | `precision` |
-| `date` | 日期 | `dateFormat` |
-| `currency` | 货币 | `precision`, `currencySymbol` |
-| `tag` | 标签 | `valueEnum` |
-| `image` | 图片 | `imageWidth`, `imageHeight` |
-| `link` | 链接 | `linkText` |
-| `progress` | 进度条 | - |
-| `avatar` | 头像 | `avatarSize` |
-| `boolean` | 布尔值 | `trueText`, `falseText` |
-| `action` | 操作列 | `actions` |
-| `index` | 序号列 | `indexOffset` |
+> **空值约定**：所有渲染器对 `null`/`undefined`/`''` 显示 `emptyText`（列级）或 `defaultEmptyText`（全局，默认 `'-'`）。`boolean` 类型中 `false` 是合法值（显示红叉），不视为空值。
 
 ### 自定义 valueType
 
+通过 `defineColumnType` 注册自定义渲染器：
+
 ```ts
 import { defineColumnType } from 'bw-pro-table';
+import { h } from 'vue';
 
-defineColumnType('customStatus', ({ text, record, column }) => {
-  return h('span', { style: { color: text === 'ok' ? 'green' : 'red' } }, text);
+defineColumnType('customStatus', ({ value, record, index, column }) => {
+  return h('span', { style: { color: value === 'ok' ? 'green' : 'red' } }, value);
 });
+
+// 在列定义中使用
+const columns = [
+  { title: '状态', dataIndex: 'status', valueType: 'customStatus' as any },
+];
 ```
 
-## 搜索配置
+**渲染器函数签名**：
 
-```vue
-<BwProTable
-  :columns="columns"
-  :search="{
-    labelWidth: 100,
-    collapsedRows: 3,
-    submitText: '查询',
-    resetText: '重置',
-  }"
-/>
+```ts
+type RendererFn = (ctx: {
+  value: any;          // 单元格值
+  record: any;         // 行数据
+  index: number;       // 行索引
+  column: ProColumnType; // 列配置
+}) => VNode | string | number;
 ```
 
-列上标注可搜索字段：
+### 渲染器 API
+
+| API | 说明 |
+|-----|------|
+| `defineColumnType(type, renderer)` | 注册自定义渲染器（已存在会警告并覆盖） |
+| `registerRenderer(type, renderer)` | 注册渲染器（底层 API） |
+| `getRenderer(type)` | 获取渲染器 |
+| `hasRenderer(type)` | 判断渲染器是否存在 |
+| `getRendererSafe(type)` | 获取渲染器（自动初始化内置渲染器） |
+| `ensureRenderers()` | 惰性初始化所有内置渲染器（幂等） |
+| `resetRenderers()` | 重置注册表（仅用于测试隔离） |
+
+## 数据加载模式
+
+### Request 模式（服务端）
+
+传入 `request` 异步函数，组件管理分页、筛选、排序：
+
+```ts
+const request = async (params: {
+  current: number;      // 当前页码
+  pageSize: number;     // 每页条数
+  [key: string]: any;   // 合并的搜索/筛选/排序参数
+}) => {
+  const res = await api.fetch(params);
+  return {
+    data: res.list,     // 当前页数据数组
+    total: res.total,   // 数据总数
+    success: true,      // 是否成功
+  };
+};
+```
+
+**参数合并**：`mergedSearchParams` 将以下参数合并后传给 `request`：
+- `searchFormParams`（搜索栏表单值）
+- `headerSearchParams`（列头搜索文本）
+- `tableFilterParams`（表头筛选值）
+- `sortState`（排序状态，展开为 `sortField` + `sortOrder`）
+
+**竞态保护**：`fetchData` 使用版本号（`fetchVersion`）防止过期响应覆盖最新数据。
+
+**页码越界校验**：数据返回后若当前页超过最大页数，自动回退到最后一页并重试一次（防止后端 total 不稳定导致无限递归）。
+
+### DataSource 模式（客户端）
+
+传入 `dataSource` 静态数组，组件自动应用客户端筛选与排序：
 
 ```ts
-{ title: '姓名', dataIndex: 'name', search: true }
-{ title: '状态', dataIndex: 'status', search: { label: '状态', widget: 'select', options: [...] } }
+const dataSource = ref<User[]>([...]);
+
+// 模板
+<BwProTable :columns="columns" :data-source="dataSource" />
 ```
 
+**客户端筛选 `applyClientFilters`**：
+
+按以下顺序对数据应用三管道筛选：
+
+1. **searchFormParams**（搜索栏）：
+   - `tag`/`boolean`/`number`/`currency`/`date` 类型 → 精确匹配（`===`）
+   - `text`/其他类型 → 子串匹配（大小写不敏感）
+2. **headerSearchParams**（列头搜索）：子串匹配（大小写不敏感）
+3. **tableFilterParams**（表头筛选）：数组 `includes` 或精确匹配
+
+**客户端排序 `applyClientSort`**：
+
+- 若列定义了 `sorter` 函数（`CompareFn` 或 `{ compare }`）→ 使用自定义比较
+- 否则 → 通用比较（数字用 `-`，字符串用 `localeCompare`，`null` 值排末尾）
+- 支持多列排序（取第一个排序项作为主排序）
+
+### 模式切换
+
+监听 `request` prop 变化自动切换模式：
+- 切换到 Request 模式 → 重置页码到 1 并请求数据
+- 切换到 DataSource 模式 → 校验页码边界并刷新数据
+
+## 搜索系统
+
+### 三管道架构
+
+| 管道 | 来源 | 触发方式 | 适用模式 |
+|------|------|----------|----------|
+| 搜索栏 | `BwProTableSearch.vue` 表单 | 点击"查询"按钮 | 两种模式 |
+| 表头筛选 | ant-design-vue 原生 `column.filters` | 列头筛选下拉 | 两种模式（Request 传后端，DataSource 客户端） |
+| 列头搜索 | `BwProTableColumnSearch.vue` Popover | 点击搜索图标 | 两种模式 |
+
+三个管道独立维护状态，最终合并到 `mergedSearchParams` 传给 `request` 或在客户端筛选中应用。
+
+### 搜索栏控件自动匹配
+
+搜索栏根据列的 `valueType` 自动渲染对应控件：
+
+| valueType | 搜索控件 |
+|-----------|----------|
+| `text` / `link` / 无 valueType | `a-input`（文本输入） |
+| `tag` | `a-select`（选项来自 `valueEnum`） |
+| `boolean` | `a-select`（是/否选项） |
+| `number` / `currency` | `a-input-number` |
+| `date` | `a-date-picker` |
+| `image` / `avatar` / `progress` / `action` / `index` | 不可搜索（自动排除） |
+| 其他 | `a-input`（兜底） |
+
+> **`hideInSearch`**：列上设置 `hideInSearch: true` 可跳过搜索栏控件生成，适用于 ID、操作列等无需搜索的字段。
+
+**自定义搜索控件**：通过 `renderFormItem` 完全自定义（优先级高于 valueType 自动匹配）：
+
+```ts
+{
+  title: '状态',
+  dataIndex: 'status',
+  renderFormItem: ({ model, search, resetField }) => {
+    return h(ASelect, {
+      value: model.status,
+      'onUpdate:value': (v) => { model.status = v; search(); },
+      options: [...],
+    });
+  },
+}
+```
+
+> `renderFormItem` 接收 `{ model, search, resetField }` 上下文：`model` 可直接读写表单值，`search()` 触发查询，`resetField(dataIndex)` 清除指定字段。
+
+### 列头搜索（headerSearch）
+
+仅 `valueType='text'` 的列支持列头搜索（`HEADER_SEARCHABLE_TYPES` 白名单）。在列上配置：
+
+```ts
+{ title: '姓名', dataIndex: 'name', valueType: 'text', headerSearch: true }
+// 或带配置
+{ title: '姓名', dataIndex: 'name', valueType: 'text', headerSearch: { placeholder: '搜索姓名' } }
+```
+
+**HeaderSearchConfig**：`{ enabled?, placeholder?, searchText?, resetText? }`
+
+全局配置通过 `columnSearch` prop：
+- `columnSearch: false` → 禁用所有列的列头搜索
+- `columnSearch: { placeholder: '...' }` → 覆写默认配置
+
+### 清除筛选
+
+调用 `clearFilter` 或工具栏"清除筛选"按钮会清空所有三个管道的筛选状态及排序，并重置到第一页。
+
 ## 行内编辑
 
-```vue
-<BwProTable
-  :columns="columns"
-  :editConfig="{
-    mode: 'cell',           // 'cell' | 'row'
-    saveText: '保存',
-    cancelText: '取消',
-    deleteText: '删除',
-    addText: '新增行',
-    maxHistory: 20,
-    onSave: async (record) => {
-      await api.save(record);
-    },
-    onDelete: async (record) => {
-      await api.delete(record.id);
-    },
-  }"
-/>
+### EditConfig 配置
+
+```ts
+interface EditConfig<RecordType = any> {
+  mode?: 'cell' | 'row';           // 编辑模式（默认 'cell'）
+  newRecord?: Partial<RecordType>; // 新增行默认值
+  onEditStart?: (record, field?) => Promise<boolean> | boolean; // 编辑前回调（返回 false 阻止）
+  onSave?: (record, isNew) => Promise<void> | void;  // 保存回调
+  onDelete?: (keys) => Promise<void> | void;          // 删除回调
+  addable?: boolean;               // 是否允许新增（默认 true）
+  deletable?: boolean;             // 是否允许删除（默认 true）
+}
 ```
 
-列上标注可编辑字段：
+### 编辑模式
+
+| 模式 | 触发 | 行为 |
+|------|------|------|
+| `cell` | `startCellEdit(rowKey, field)` | 仅单个单元格进入编辑态，其他单元格正常显示 |
+| `row` | `startRowEdit(rowKey)` | 整行进入编辑态 |
+
+**草稿数据管理**：编辑期间的修改存储在 `draftData: Map<rowKey, Record<field, value>>`，保存时合并到数据源，取消时回滚到 `originalData` 备份。
+
+### 编辑组件自动匹配
+
+编辑态根据列的 `valueType` 自动渲染编辑组件：
+
+| valueType | 编辑组件 |
+|-----------|----------|
+| `number` / `currency` | `a-input-number` |
+| `date` | `a-date-picker`（格式使用 `dateFormat` 或默认 `'YYYY-MM-DD'`） |
+| `tag` / `enum` | `a-select`（选项来自 `valueEnum`） |
+| `boolean` | `a-switch` |
+| 其他（`text` 等） | `a-input` |
+
+校验失败时编辑组件边框变红，下方显示错误消息。
+
+### 字段校验
+
+在列上配置 `formRules`，保存时自动校验：
 
 ```ts
 {
@@ -271,49 +572,194 @@ defineColumnType('customStatus', ({ text, record, column }) => {
 }
 ```
 
-## 持久化配置
+校验规则执行顺序：`required` → `type` → `min` → `max` → `pattern` → `validator`（每个字段仅报第一个错误）。
 
-```vue
-<BwProTable
-  tableId="user-table"
-  :persistence="{
-    enabled: true,
-    storage: 'localStorage',  // 'localStorage' | 'sessionStorage' | StorageAdapter
-    keyPrefix: 'my-app',
-    debug: false,
-    onError: (err, action) => console.warn('持久化错误:', err),
-  }"
-/>
+`editable` 支持函数形式动态判断可编辑性：
+
+```ts
+{ dataIndex: 'status', editable: (record) => record.role === 'admin' }
 ```
 
-支持的持久化范围：列显隐/顺序/宽度、分页大小、当前页码、密度、筛选、排序。
+### 撤销/重做（Command Pattern）
 
-## 导出/导入
+编辑操作以命令（`EditCommand`）形式压入撤销栈：
 
-需要安装 `xlsx` 依赖：
+```ts
+interface EditCommand {
+  type: 'update' | 'add' | 'delete';
+  rowKey: string | number;
+  field?: string;       // update 命令的字段名
+  oldValue?: any;       // update 的旧值
+  newValue?: any;       // update 的新值
+  record?: any;         // add/delete 的完整记录
+  index?: number;       // delete 的原始索引（用于撤销时恢复位置）
+}
+```
 
-```bash
-npm install xlsx
+- **撤销栈上限**：`2 * DEFAULT_PAGE_SIZE - 1`（默认 19 条），超出时移除最旧命令
+- **新操作入栈时清空重做栈**
+- `undo()`/`redo()` 通过 `ref` 方法或键盘快捷键调用
+
+### 批量编辑
+
+通过 `openBatchEdit()` 打开批量编辑弹窗，选择字段和值后应用到所有选中行：
+
+```ts
+const tableRef = ref();
+// 选中多行后
+tableRef.value.openBatchEdit();
+// 弹窗确认后自动调用 onSave 回调逐行保存
 ```
 
+跨页多选模式下，批量编辑应用于所有跨页选中的行。
+
+### 新增与克隆行
+
+```ts
+tableRef.value.addRow('top');    // 在顶部新增空行
+tableRef.value.addRow('bottom'); // 在底部新增空行（默认）
+tableRef.value.cloneRow(rowKey); // 克隆行（插入到顶部）
+```
+
+新增行使用 `editConfig.newRecord` 作为默认值，自动进入编辑态。新增行的 key 格式为 `new_{timestamp}_{random}`。
+
+## 列管理
+
+### 列拖拽排序
+
+启用列拖拽后，表头显示拖拽图标，可拖动调整列顺序：
+
 ```vue
 <BwProTable
-  :toolbar="{ export: true, import: true }"
-  :exportConfig="{
-    filename: '用户列表',
-    chunkSize: 5000,
-    columnMapping: { name: '姓名', age: '年龄' },
-  }"
-  :importConfig="{
-    validateRules: [{ required: true, message: '不能有空值' }],
-    onImport: async (data) => { await api.batchCreate(data); },
-    beforeImport: (data) => data.map(item => ({ ...item, source: 'import' })),
-  }"
+  :columns="columns"
+  :drag-config="{ columnDraggable: true }"
 />
 ```
 
+**实现细节**：
+- 使用 HTML5 Drag and Drop API
+- 拖拽时自定义幽灵图（蓝色背景白色文字的列标题）
+- `dragVersion` 计数器变化触发表头重渲染（更新拖拽视觉反馈）
+- `reorderColumns(fromDataIndex, toDataIndex)` 分离可见/隐藏列各自保持相对顺序
+- **特殊列排除**：`valueType='index'`、`valueType='action'`、`dataIndex='action'` 的列不参与拖拽（`isSpecialColumn`）
+
+### 列宽调节
+
+列宽调节通过 rAF（`requestAnimationFrame`）批处理节流，避免每像素触发响应式更新：
+
+- 宽度变更先收集到 `pendingWidths` 对象
+- 每帧通过 `flushColumnWidths()` 统一写入 `shallowRef<Record<string, number>>`
+- 持久化写入也合并到同一 rAF 周期
+- 组件卸载时确保刷新残留的待持久化数据
+
+### 列设置面板
+
+工具栏的列设置按钮打开面板，支持：
+- 列显隐切换（`checked`）
+- 列顺序调整（`order`）
+- 列宽显示
+- 重置到初始状态（`onColumnReset`）
+
+列配置变化通过 `onColumnChange` 自动持久化。
+
+## 持久化系统
+
+### PersistenceConfig 配置
+
+```ts
+interface PersistenceConfig {
+  enabled?: boolean;    // 是否启用（默认 true）
+  storage?: 'localStorage' | 'sessionStorage' | StorageAdapter; // 存储方式（默认 'localStorage'）
+  keyPrefix?: string;   // 键名前缀（默认 'bw-pro-table'）
+  onError?: (error: Error, operation: 'get' | 'set' | 'remove') => void; // 错误回调
+  debug?: boolean;      // 调试模式（输出 console.warn 日志，默认 false）
+}
+```
+
+### 持久化范围
+
+| 状态 | 说明 |
+|------|------|
+| 列配置 | 显隐（`checked`）、顺序（`order`）、宽度（`width`） |
+| 分页大小 | `pageSize` |
+| 当前页码 | `current` |
+| 密度 | `density`（`'small' \| 'middle' \| 'default'`） |
+| 筛选状态 | `filters`（合并 `tableFilterParams` + `headerSearchParams`） |
+| 排序状态 | `sorter`（`{ field, order }`） |
+
+### 存储键格式
+
+```
+{keyPrefix}:{tableId 或 cacheKey}:cache
+```
+
+默认示例：`bw-pro-table:user-table:cache`
+
+> **注意**：启用持久化时建议设置固定的 `tableId` 或 `cacheKey`，否则使用随机 `tableId` 会导致刷新后配置无法恢复（调试模式下会输出警告）。
+
+### 版本管理
+
+- 当前版本：`V1.0.0`（`PERSISTED_DATA_VERSION`）
+- 加载时校验 `version` 字段，版本不匹配自动清除缓存
+- `validatePersistedState()` 校验数据结构完整性（`columns` 数组每项需含 `key`/`checked`/`order`）
+
+### 自定义 StorageAdapter
+
+```ts
+interface StorageAdapter {
+  get: (key: string) => PersistedTableState | null;
+  set: (key: string, value: PersistedTableState) => void;
+  remove: (key: string) => void;
+}
+
+// 示例：使用 IndexedDB
+const customAdapter: StorageAdapter = {
+  get: (key) => { /* 从 IndexedDB 读取 */ },
+  set: (key, value) => { /* 写入 IndexedDB */ },
+  remove: (key) => { /* 删除 */ },
+};
+
+<BwProTable :persistence="{ storage: customAdapter }" />
+```
+
 ## 跨页多选
 
+### CrossPageSelectionConfig 配置
+
+```ts
+interface CrossPageSelectionConfig {
+  enabled?: boolean;          // 是否启用（默认 false）
+  onSelectAllPages?: (searchParams) => Promise<(string | number)[]> | (string | number)[]; // Request 模式下全选回调
+  maxSelectCount?: number;    // 最大选择数（0 表示不限制）
+}
+```
+
+### 工作机制
+
+- **crossPageKeys**：`Set<string | number>` 存储所有跨页选中的 key
+- **selectedRowsMap**：`Map<key, record>` 存储对应的行数据
+- **syncSelectedRowKeys()**：每次数据更新后，用 `crossPageKeys ∩ dataSource` 计算当前页应显示的选中状态
+- **diffing 逻辑**：翻页选择时，通过对比前后 `selectedRowKeys` 差集更新 `crossPageKeys`
+
+### 全选所有页
+
+| 模式 | 行为 |
+|------|------|
+| DataSource | 直接从内存 `dataSource` 提取所有 key |
+| Request | 调用 `onSelectAllPages(mergedSearchParams)` 回调获取全量 key |
+
+> Request 模式下"选择所有页"按钮仅当提供 `onSelectAllPages` 回调时才显示（该操作需后端返回全量 key，是重操作）。DataSource 模式下始终显示。
+
+### 跨页选择菜单
+
+跨页模式下自动注入以下选择菜单项到 ant-design-vue `selections`：
+- 选择当前页（`SELECTION_ALL`）
+- 反选当前页（`SELECTION_INVERT`）
+- 选择所有页（条件显示）
+- 清空所有（`clear-all`）
+
+### 示例
+
 ```vue
 <BwProTable
   :row-selection="{ type: 'checkbox' }"
@@ -321,7 +767,6 @@ npm install xlsx
     enabled: true,
     maxSelectCount: 100,
     onSelectAllPages: async (params) => {
-      // Request 模式下返回所有匹配行的 key
       const res = await api.getAllKeys(params);
       return res.keys;
     },
@@ -329,13 +774,250 @@ npm install xlsx
 />
 ```
 
-## 从源码使用（开发）
+## Excel 导入导出
+
+需要安装 `xlsx` 依赖（按需动态 `import()` 懒加载，不影响首屏体积）：
+
+```bash
+npm install xlsx
+```
+
+### ExportConfig 导出配置
 
 ```ts
-import { BwProTable } from 'bw-pro-table';
-import 'bw-pro-table/dist/style.css';
+interface ExportConfig {
+  filename?: string;      // 导出文件名（默认 'export'）
+  chunkSize?: number;     // 分片大小（默认 10000，超出时分片构建+进度条）
+  maxRows?: number;       // 最大导出行数警告阈值（默认 50000，不阻止仅警告）
+  type?: 'xlsx' | 'csv';  // 导出类型
+  columnMapping?: Record<string, string>; // 自定义列映射（dataIndex → 表头文字）
+  beforeExport?: () => Promise<boolean> | boolean; // 导出前拦截（返回 false 阻止）
+  onExportAll?: (params) => Promise<any[]> | any[]; // Request 模式获取全量数据
+  onExportSelected?: (keys) => Promise<any[]> | any[]; // 获取选中行完整数据
+}
+```
+
+### 导出方式
+
+| 方法 | 说明 | 数据来源 |
+|------|------|----------|
+| `exportExcel()` | 导出 `.xlsx` | `onExportAll` 回调或当前 `dataSource` |
+| `exportCsv()` | 导出 `.csv`（UTF-8 BOM） | `onExportAll` 回调或当前 `dataSource` |
+| `exportSelected(rows, keys?)` | 导出选中行为 `.xlsx` | 传入的 `rows` 或 `onExportSelected(keys)` 回调 |
+
+**导出列处理**：自动排除 `hidden: true` 的列和特殊列（`index`/`action`），表头使用 `columnMapping[dataIndex]` 或 `column.title`。
+
+**分片导出**：数据量超过 `chunkSize` 时分片构建 sheet，每 5 片 yield 到主线程避免阻塞，进度通过 `exportProgress` ref 暴露。
+
+### ImportConfig 导入配置
+
+```ts
+interface ImportConfig {
+  columnMapping?: Record<string, string>; // 预设列映射（col_X → dataIndex）
+  validateRules?: ImportValidateRule[];   // 校验规则（含必填 field 字段）
+  beforeImport?: (data) => Promise<any[]> | any[]; // 导入前数据转换
+  onImport?: (data) => Promise<void> | void;       // 导入提交回调
+}
+
+interface ImportValidateRule extends FormRule {
+  field: string; // 校验目标字段名（必填）
+}
+```
+
+### 导入流程
+
+1. **文件选择**：`openFileDialog()` 打开文件选择器（接受 `.xlsx/.xls/.csv`）
+2. **解析预览**：使用 FileReader + xlsx 解析，第一行为表头，预览最多 10 行（`IMPORT_PREVIEW_MAX_ROWS`）
+3. **自动列映射**：`autoMapColumns` 匹配 Excel 表头与 `column.title`/`dataIndex`（忽略大小写），用户预设的 `columnMapping` 优先级最高
+4. **手动映射**：预览弹窗中可手动调整列映射
+5. **校验**：`runValidation` 基于 `validateRules` + 列级 `formRules` 逐行逐字段校验（含 `validator` 自定义函数）
+6. **转换**：`beforeImport` 回调转换数据
+7. **提交**：`onImport` 回调提交数据，成功后 Request 模式自动刷新数据
+
+### 模板下载
+
+```ts
+tableRef.value.downloadTemplate(
+  columns
+    .filter(c => c.dataIndex && !isSpecialColumn(c))
+    .map(c => ({ title: c.title, dataIndex: c.dataIndex }))
+);
+```
+
+生成仅含表头行的空 `.xlsx` 模板文件。
+
+## 工具栏与全屏
+
+### 工具栏配置
+
+```vue
+<BwProTable
+  :toolbar="{
+    refresh: true,        // 刷新按钮
+    density: true,        // 密度切换（small/middle/default）
+    fullscreen: true,     // 全屏切换
+    columnSetting: true,  // 列设置面板
+    export: true,         // 导出按钮
+    import: true,         // 导入按钮
+    clearFilter: true,    // 清除筛选按钮
+    bordered: true,       // 显示边框切换 Switch
+    striped: true,        // 显示斑马纹切换 Switch
+  }"
+/>
 ```
 
+### 全屏
+
+使用 `screenfull` 库实现全屏切换。全屏时动态切换 `getPopupContainer`，确保 Popover/Dropdown 挂载到全屏容器内（通过 `a-config-provider` 实现）。
+
+### 密度切换
+
+切换表格 `size`（`'small' | 'middle' | 'default'`），变更后自动持久化。
+
+### 边框与斑马纹
+
+工具栏提供边框（`bordered`）和斑马纹（`striped`）Switch 切换按钮，分别通过 `toolbar.bordered`、`toolbar.striped` 控制显隐（默认 `true`，传 `false` 隐藏对应开关）。斑马纹通过 `getRowClassName` 注入 `bw-pro-table-row-striped` 类（偶数行）。
+
+## 国际化
+
+### 优先级链
+
+```
+props.locale > vue-i18n 全局消息 > zh-CN 默认值
+```
+
+### 使用方式
+
+**方式一：`locale` prop 部分覆写**
+
+```vue
+<BwProTable
+  :locale="{ toolbar: { refresh: 'Reload', export: 'Export Excel' } }"
+/>
+```
+
+**方式二：vue-i18n 集成**
+
+在 vue-i18n 配置中添加 `bwProTable` 命名空间的消息，组件会自动读取当前 locale 对应的消息。
+
+**方式三：导入默认中文包**
+
+```ts
+import { zhCN } from 'bw-pro-table';
+```
+
+### BwProTableLocale 接口
+
+语言包按功能分类：`search`、`toolbar`、`table`、`columnSetting`、`edit`、`export`、`import`、`contextMenu`、`view`、`error`、`selection`、`filter`、`boolean`。完整结构见 `types.ts` 中的 `BwProTableLocale` 接口。
+
+## 独立 Composables
+
+以下 composables 可独立于 `BwProTable` 组件使用（均已从 `index.ts` 导出）：
+
+| Composable | 说明 |
+|------------|------|
+| `useBwRowEdit` | 行内编辑（草稿/校验/撤销重做/批量编辑） |
+| `useExportExcel` | Excel 导出（xlsx 懒加载/分片/进度） |
+| `useImportExcel` | Excel 导入（解析/映射/校验/预览） |
+| `usePersistence` | 状态持久化（localStorage/sessionStorage/自定义） |
+| `useBwRowSelection` | 行选择管理 |
+| `useQueryParams` | 查询参数管理 |
+| `useColumnHeaderSearch` | 列头搜索状态管理 |
+| `useContextMenu` | 右键菜单状态管理（未集成） |
+| `useDragSort` | 拖拽排序（未集成） |
+| `useBwKeyboard` | 键盘导航（未集成） |
+| `useTableView` | 视图管理（未集成） |
+| `useBwPermission` | 权限过滤（未集成） |
+| `useLocale` / `mergeLocale` | 国际化工具 |
+
+示例：
+
+```ts
+import { useBwRowEdit, useExportExcel } from 'bw-pro-table';
+
+const { editingKeys, startRowEdit, saveEdit, undo, redo } = useBwRowEdit({
+  dataSource,
+  columns,
+  rowKey: 'id',
+  editConfig,
+  onSave: async (record, isNew) => { /* ... */ },
+});
+```
+
+## 未集成功能说明
+
+以下功能已在 `composables/` 或独立组件中实现，但**尚未在主组件 `BwProTable.vue` 中集成**，运行时不生效。相关类型定义已就绪，可在 types.ts 中查阅。
+
+| 功能 | 位置 | 类型定义 | 状态 |
+|------|------|----------|------|
+| 右键菜单 | `BwProTableContextMenu.vue` + `useContextMenu` | `ContextMenuConfig`、`ContextMenuItem` | 组件已实现，主组件未绑定 `contextmenu` 事件 |
+| 高级筛选 | `BwProTableAdvancedFilter.vue` | `AdvancedFilterCondition`、`AdvancedFilterGroup`、`FilterOperator` | 组件已实现，工具栏未添加入口 |
+| 视图管理 | `useTableView` | `ViewConfig` | composable 已实现，工具栏 `viewManager` 按钮未渲染 |
+| 键盘导航 | `useBwKeyboard` | `KEYBOARD_NAV_KEYS` 常量 | composable 已实现，核心组件未挂载 |
+| 权限过滤 | `useBwPermission` | `authority` 字段（`ProColumnType`） | composable 已实现，`displayColumns` 未集成过滤 |
+| 行拖拽 | `useDragSort` | `DragConfig.rowDraggable` | composable 已实现，仅实现了列拖拽 |
+
+> 这些功能的类型已导出，配置 prop 可传入但不会产生运行时效果。如需使用，可独立引入对应 composable 自行集成。
+
+## 高级用法
+
+### 自定义搜索控件
+
+```ts
+import { h } from 'vue';
+import { Select as ASelect } from 'ant-design-vue';
+
+const columns = [
+  {
+    title: '状态',
+    dataIndex: 'status',
+    renderFormItem: ({ model, search }) => {
+      return h(ASelect, {
+        value: model.status,
+        'onUpdate:value': (v) => { model.status = v; search(); },
+        options: [
+          { label: '启用', value: 'active' },
+          { label: '禁用', value: 'inactive' },
+        ],
+      });
+    },
+  },
+];
+```
+
+### 自定义渲染器
+
+```ts
+import { defineColumnType } from 'bw-pro-table';
+import { h } from 'vue';
+import { Tag } from 'ant-design-vue';
+
+defineColumnType('priority', ({ value }) => {
+  const colorMap: Record<string, string> = { high: 'red', medium: 'orange', low: 'green' };
+  return h(Tag, { color: colorMap[value] }, value);
+});
+
+// 使用
+const columns = [{ title: '优先级', dataIndex: 'priority', valueType: 'priority' as any }];
+```
+
+### 自定义 bodyCell 插槽
+
+```vue
+<BwProTable :columns="columns" :request="request">
+  <template #bodyCell="{ column, record, index, text }">
+    <template v-if="column.dataIndex === 'name'">
+      <a-tag color="blue">{{ text }}</a-tag>
+    </template>
+    <template v-else>
+      {{ text }}
+    </template>
+  </template>
+</BwProTable>
+```
+
+> 使用 `bodyCell` 插槽会覆盖 valueType 渲染器的自动匹配。
+
 ## License
 
 MIT