jianghu-ui 1.0.1

package/src/components/JhTable/JhTable.md

@@ -0,0 +1,730 @@
+# JhTable - 高级表格组件
+
+参考 Ant Design Pro 的 ProTable 设计的增强版数据表格组件，提供丰富的企业级功能。
+
+## ✨ 核心特性
+
+### 1. ProTable 样式系统
+
+#### 表格标题区
+- **headerTitle**: 表格标题显示
+- **tooltip**: 标题提示信息
+- **header-title 插槽**: 自定义标题内容
+
+```vue
+<jh-table
+  header-title="用户列表"
+  tooltip="这是用户管理列表"
+>
+  <template v-slot:header-title>
+    <div class="custom-title">
+      <v-icon>mdi-account-group</v-icon>
+      <span>用户管理</span>
+    </div>
+  </template>
+</jh-table>
+```
+
+#### 卡片样式
+- **cardBordered**: 显示卡片边框和阴影（默认 true）
+- **ghost**: 幽灵模式，无边框无背景（默认 false）
+
+```vue
+<!-- 卡片样式 -->
+<jh-table :card-bordered="true" />
+
+<!-- 幽灵模式 -->
+<jh-table :ghost="true" />
+```
+
+### 2. 批量操作提示栏
+
+当启用行选择时，选中数据后会自动显示批量操作提示栏。
+
+```vue
+<jh-table
+  :show-select="true"
+  @selection-change="handleSelectionChange"
+>
+  <!-- 自定义批量操作提示内容 -->
+  <template v-slot:alert="{ selectedRowKeys, selectedRows }">
+    <span>已选择 {{ selectedRows.length }} 项</span>
+  </template>
+
+  <!-- 自定义批量操作按钮 -->
+  <template v-slot:alert-actions="{ selectedRowKeys, selectedRows }">
+    <v-btn small text color="primary" @click="handleBatchExport">
+      <v-icon small left>mdi-download</v-icon>
+      导出
+    </v-btn>
+    <v-btn small text color="error" @click="handleBatchDelete">
+      <v-icon small left>mdi-delete</v-icon>
+      批量删除
+    </v-btn>
+  </template>
+</jh-table>
+```
+
+### 3. 轮询和防抖
+
+#### 轮询刷新
+自动定时刷新表格数据，适用于实时监控场景。
+
+```vue
+<jh-table
+  :request="fetchData"
+  :polling="5000"
+/>
+```
+
+#### 搜索防抖
+减少搜索时的请求频率，提升性能。
+
+```vue
+<jh-table
+  :request="fetchData"
+  :debounce-time="500"
+/>
+```
+
+### 4. 增强的工具栏
+
+#### 工具栏配置
+```vue
+<jh-table
+  :toolbar="{
+    search: true,      // 搜索框
+    refresh: true,     // 刷新按钮
+    setting: true,     // 列设置
+    density: true,     // 密度切换
+    fullscreen: true   // 全屏
+  }"
+/>
+```
+
+#### 工具栏插槽
+```vue
+<jh-table>
+  <!-- 左侧操作按钮（在标题区显示） -->
+  <template v-slot:toolbar-actions>
+    <v-btn color="success" @click="handleCreate">
+      <v-icon left>mdi-plus</v-icon>
+      新增
+    </v-btn>
+  </template>
+
+  <!-- 右侧额外按钮 -->
+  <template v-slot:toolbar-extra>
+    <v-btn outlined>
+      <v-icon left>mdi-download</v-icon>
+      导出
+    </v-btn>
+  </template>
+</jh-table>
+```
+
+### 5. 表格额外内容区
+
+在表格下方添加额外内容，如统计信息、图表等。
+
+```vue
+<jh-table>
+  <template v-slot:table-extra>
+    <div class="pa-4">
+      <v-row>
+        <v-col cols="3">
+          <v-card>
+            <v-card-text>
+              <div class="text-h4">1,234</div>
+              <div class="text-caption">总用户数</div>
+            </v-card-text>
+          </v-card>
+        </v-col>
+      </v-row>
+    </div>
+  </template>
+</jh-table>
+```
+
+### 6. 高级筛选栏
+
+集成 JhQueryFilter 组件，提供强大的筛选功能。
+
+```vue
+<jh-table
+  :show-filter="true"
+  :filter-fields="[
+    { key: 'username', label: '用户名', type: 'text' },
+    { key: 'status', label: '状态', type: 'select', options: [...] },
+    { key: 'dateRange', label: '日期', type: 'daterange' }
+  ]"
+  :filter-collapsible="true"
+  :filter-default-collapsed="true"
+  @filter-search="handleFilterSearch"
+  @filter-reset="handleFilterReset"
+/>
+```
+
+### 7. 列增强功能
+
+#### copyable - 可复制
+```javascript
+{
+  text: '邮箱',
+  value: 'email',
+  copyable: true  // 显示复制按钮
+}
+```
+
+#### ellipsis - 省略号
+```javascript
+{
+  text: '描述',
+  value: 'description',
+  ellipsis: true  // 超长文本省略，hover 显示完整内容
+}
+```
+
+### 8. 操作列配置化
+
+```vue
+<jh-table
+  :action-column="{
+    title: '操作',
+    width: 180,
+    fixed: 'right',
+    buttons: [
+      {
+        text: '编辑',
+        type: 'link',        // link / icon / button
+        icon: 'mdi-pencil',
+        color: 'primary',
+        tooltip: '编辑记录',
+        onClick: (row) => { console.log('编辑', row) },
+        visible: (row) => row.status !== '禁用',
+        confirm: '确认编辑？'
+      },
+      {
+        text: '删除',
+        type: 'link',
+        icon: 'mdi-delete',
+        color: 'error',
+        onClick: (row) => { console.log('删除', row) },
+        confirm: '确认删除？'
+      }
+    ]
+  }"
+/>
+```
+
+### 9. 服务端分页
+
+```vue
+<jh-table
+  :request="fetchData"
+  :pagination="{
+    current: 1,
+    pageSize: 20,
+    pageSizeOptions: [10, 20, 50, 100]
+  }"
+/>
+```
+
+```javascript
+async fetchData(params) {
+  // params: { page, pageSize, search, sorter, filters }
+  const response = await fetch('/api/users', {
+    method: 'POST',
+    body: JSON.stringify(params),
+  });
+  return {
+    data: response.list,
+    total: response.total,
+    success: true,
+  };
+}
+```
+
+### 10. 行选择
+
+```vue
+<jh-table
+  :show-select="true"
+  :single-select="false"
+  @selection-change="handleSelectionChange"
+/>
+```
+
+```javascript
+handleSelectionChange({ selectedRowKeys, selectedRows }) {
+  console.log('选中的 keys:', selectedRowKeys);
+  console.log('选中的行:', selectedRows);
+}
+```
+
+### 11. 密度切换
+
+三种密度自动适配：
+- **default**: 48px 行高
+- **medium**: 40px 行高
+- **compact**: 32px 行高
+
+```vue
+<jh-table size="medium" />
+```
+
+### 12. 列 Schema 渲染（ProTable 对齐）
+
+- 列可声明 `valueType`、`valueEnum`、`valueEnumStatusMap`、`valueFormatter`、`valueProps`，JhTable 会按类型自动格式化并保持 Tooltip / 复制 / hover 等体验。
+- 典型类型：`status`、`money`、`percent`、`progress`、`digit`、`date`/`dateTime`/`dateRange`、`avatar`、`json`、`code`、`index` 等。
+
+| 字段 | 说明 |
+| ---- | ---- |
+| `valueType` | 控制默认渲染器，例如 `status` 显示 chip、`progress` 显示进度条 |
+| `valueEnum` | 枚举映射 `{ value: { text, status, color, icon } }` |
+| `valueEnumStatusMap` | 按状态调整颜色/样式，覆盖内置的 success/warning/error/processing/default |
+| `valueFormatter(value, row, column)` | 最终展示前的格式化函数（返回值将直接显示） |
+| `valueProps` | 透传给默认渲染器的配置（进度条高度、金额精度、头像尺寸等） |
+
+```vue
+<jh-table
+  :headers="[
+    {
+      text: '状态',
+      value: 'status',
+      valueType: 'status',
+      valueEnumStatusMap: { warning: { color: 'orange darken-2' } },
+      valueEnum: {
+        pending: { text: '待审核', status: 'warning', icon: 'mdi-clock' },
+        online: { text: '可用', status: 'success' },
+        offline: { text: '禁用', status: 'error' },
+      },
+    },
+    {
+      text: '账单金额',
+      value: 'amount',
+      valueType: 'money',
+      valueFormatter: (value) => `${(value / 10000).toFixed(2)} 万`,
+      valueProps: { currencySymbol: '¥', precision: 2 },
+    },
+    {
+      text: '完成进度',
+      value: 'progress',
+      valueType: 'progress',
+      valueProps: { color: 'success', height: 8, showValue: true },
+    },
+    {
+      text: '任务 JSON',
+      value: 'payload',
+      valueType: 'json',
+      ellipsis: true,
+    },
+  ]"
+  :items="taskList"
+/>
+```
+
+### 13. 列驱动筛选（search schema → JhQueryFilter）
+
+- `show-filter` + `auto-filter-from-headers（默认 true）` 开启后，只有在 `headers` 中显式声明了 `search`（`true` 或配置对象）的列才会自动生成 JhQueryFilter 字段，默认不会把所有列都展示出来。
+- `search: true` 代表采用默认的文本输入筛选；设置为对象时可进一步控制输入类型、占位、初始值等；`search: false` 仍可用于兼容旧配置的“强制关闭”场景。
+- `search` 支持对象写法：`{ valueType, formItemProps, transform, initialValue, key, placeholder }`，可直接控制控件类型、初始值和后端映射。
+- `transform(value)` 用于把表单值拆分成后端期望的结构，例如日期区间拆成 `startDate/endDate`；也可通过 `valueEnumKey` 让 select 选项使用枚举中的其他字段。
+- 手动传入 `filter-fields` 且 key 重复时，组件会优先使用手动配置，保证可完全自定义。
+
+```vue
+const headers = [
+  {
+    text: '状态',
+    value: 'status',
+    valueType: 'status',
+    valueEnum: {
+      pending: { text: '待审核', status: 'warning', value: 'PENDING' },
+      approved: { text: '已通过', status: 'success', value: 'APPROVED' },
+    },
+    search: {
+      valueType: 'select',
+      valueEnumKey: 'value',
+      initialValue: 'PENDING',
+    },
+  },
+  {
+    text: '创建时间',
+    value: 'createdAt',
+    valueType: 'dateTime',
+    search: {
+      valueType: 'dateRange',
+      initialValue: ['2024-01-01', '2024-01-31'],
+      transform: (value) => ({
+        startDate: value?.[0],
+        endDate: value?.[1],
+      }),
+    },
+  },
+];
+
+<jh-table
+  :headers="headers"
+  :request="fetchData"
+  show-filter
+  @filter-search="filters => console.log(filters)"
+/>;
+```
+
+如需关闭自动注入，可设置 `:auto-filter-from-headers="false"`，或直接移除列的 `search` 配置（保留 `search: false` 写法也兼容）。
+
+## 📋 完整 Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| headers | 表格表头配置 | Array | [] |
+| items | 表格数据（客户端分页） | Array | [] |
+| request | 数据请求函数（服务端分页） | Function | null |
+| headerTitle | 表格标题 | String | '' |
+| tooltip | 标题提示信息 | String | '' |
+| cardBordered | 是否显示卡片边框 | Boolean | true |
+| ghost | 幽灵模式（无边框无背景） | Boolean | false |
+| toolbar | 工具栏配置 | Object/Boolean | {...} |
+| showFilter | 是否显示筛选栏 | Boolean | false |
+| filterFields | 筛选字段配置 | Array | [] |
+| filterInitialValues | 筛选初始值 | Object | {} |
+| autoFilterFromHeaders | 是否根据列 schema 自动注入筛选字段 | Boolean | true |
+| filterCollapsible | 筛选栏是否可折叠 | Boolean | true |
+| filterDefaultCollapsed | 筛选栏默认是否折叠 | Boolean | true |
+| actionColumn | 操作列配置 | Object/Boolean | null |
+| pagination | 分页配置 | Object/Boolean | {...} |
+| showSelect | 是否显示选择框 | Boolean | false |
+| singleSelect | 是否单选 | Boolean | false |
+| polling | 轮询间隔（毫秒），0 表示不轮询 | Number | 0 |
+| debounceTime | 搜索防抖时间（毫秒） | Number | 300 |
+| loading | 加载状态 | Boolean | false |
+| size | 表格密度 | String | 'default' |
+| rowKey | 行数据的 Key | String | 'id' |
+
+## 🎯 插槽
+
+| 插槽名 | 说明 | 参数 |
+|--------|------|------|
+| header-title | 自定义标题内容 | - |
+| toolbar-actions | 工具栏左侧操作按钮 | - |
+| toolbar-extra | 工具栏右侧额外内容 | - |
+| alert | 自定义批量操作提示内容 | { selectedRowKeys, selectedRows } |
+| alert-actions | 批量操作按钮区 | { selectedRowKeys, selectedRows } |
+| table-extra | 表格额外内容区 | - |
+| item.{column} | 自定义列内容 | { item, value, index } |
+| header.{column} | 自定义表头 | { header } |
+
+## 🔧 方法
+
+| 方法名 | 说明 | 参数 |
+|--------|------|------|
+| reload() | 重新加载数据（服务端分页） | - |
+| reset() | 重置到第一页 | - |
+| clearSelection() | 清空选择 | - |
+| getSelectedRows() | 获取选中的行 | - |
+
+## 📡 事件
+
+| 事件名 | 说明 | 回调参数 |
+|--------|------|----------|
+| create-click | 点击新增按钮 | - |
+| update-click | 点击详情按钮 | (item) |
+| delete-click | 点击删除按钮 | (item) |
+| row-click | 点击行 | (item, event) |
+| selection-change | 选择改变 | { selectedRowKeys, selectedRows } |
+| refresh | 点击刷新按钮 | - |
+| copy-success | 复制成功 | (text) |
+| request-error | 请求失败 | (error) |
+| filter-search | 筛选查询 | (queryData) |
+| filter-reset | 筛选重置 | - |
+
+## 🎨 完整示例
+
+```vue
+<template>
+  <jh-table
+    ref="tableRef"
+    header-title="用户管理"
+    tooltip="管理系统用户信息"
+    :card-bordered="true"
+    :headers="headers"
+    :request="fetchData"
+    :show-select="true"
+    :show-filter="true"
+    :filter-fields="filterFields"
+    :action-column="actionColumn"
+    :polling="10000"
+    :debounce-time="500"
+    @selection-change="handleSelectionChange"
+    @filter-search="handleFilterSearch"
+  >
+    <!-- 工具栏按钮 -->
+    <template v-slot:toolbar-actions>
+      <v-btn color="success" @click="handleCreate">
+        <v-icon left>mdi-plus</v-icon>
+        新增用户
+      </v-btn>
+    </template>
+
+    <!-- 额外工具 -->
+    <template v-slot:toolbar-extra>
+      <v-btn outlined @click="handleExport">
+        <v-icon left>mdi-download</v-icon>
+        导出
+      </v-btn>
+    </template>
+
+    <!-- 批量操作 -->
+    <template v-slot:alert-actions="{ selectedRows }">
+      <v-btn small text color="error" @click="handleBatchDelete">
+        批量删除
+      </v-btn>
+    </template>
+
+    <!-- 自定义状态列 -->
+    <template v-slot:item.status="{ item }">
+      <v-chip
+        :color="item.status === '启用' ? 'success' : 'error'"
+        small
+      >
+        {{ item.status }}
+      </v-chip>
+    </template>
+  </jh-table>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      headers: [
+        { text: 'ID', value: 'id', width: 80 },
+        { text: '用户名', value: 'username', copyable: true },
+        { text: '邮箱', value: 'email', ellipsis: true, copyable: true },
+        { text: '状态', value: 'status' },
+        { text: '创建时间', value: 'createdAt' },
+        { text: '操作', value: 'action', width: 180 },
+      ],
+      filterFields: [
+        { key: 'username', label: '用户名', type: 'text' },
+        { key: 'status', label: '状态', type: 'select', options: [...] },
+      ],
+      actionColumn: {
+        title: '操作',
+        width: 180,
+        buttons: [
+          {
+            text: '编辑',
+            type: 'link',
+            icon: 'mdi-pencil',
+            color: 'primary',
+            onClick: this.handleEdit,
+          },
+          {
+            text: '删除',
+            type: 'link',
+            icon: 'mdi-delete',
+            color: 'error',
+            confirm: '确认删除？',
+            onClick: this.handleDelete,
+          },
+        ],
+      },
+    };
+  },
+  methods: {
+    async fetchData(params) {
+      const response = await this.$api.getUsers(params);
+      return {
+        data: response.list,
+        total: response.total,
+        success: true,
+      };
+    },
+    handleCreate() {
+      // 新增逻辑
+    },
+    handleEdit(row) {
+      // 编辑逻辑
+    },
+    handleDelete(row) {
+      // 删除逻辑
+    },
+    handleBatchDelete() {
+      const rows = this.$refs.tableRef.getSelectedRows();
+      // 批量删除逻辑
+    },
+    handleSelectionChange({ selectedRows }) {
+      console.log('选中:', selectedRows);
+    },
+    handleFilterSearch(queryData) {
+      console.log('筛选:', queryData);
+    },
+  },
+};
+</script>
+```
+
+## 🆚 对比 Ant Design ProTable
+
+### ✅ 已实现的 ProTable 功能
+
+- ✅ headerTitle - 表格标题
+- ✅ tooltip - 标题提示
+- ✅ cardBordered - 卡片边框
+- ✅ ghost - 幽灵模式
+- ✅ toolbar - 工具栏配置
+- ✅ search - 搜索功能
+- ✅ options - 列设置、密度、刷新、全屏
+- ✅ request - 服务端分页
+- ✅ polling - 轮询刷新
+- ✅ debounceTime - 搜索防抖
+- ✅ rowSelection - 行选择
+- ✅ tableAlertRender - 批量操作提示栏
+- ✅ tableAlertOptionRender - 批量操作按钮
+- ✅ columns.copyable - 可复制列
+- ✅ columns.ellipsis - 省略号
+- ✅ actionColumn - 操作列配置
+
+### 🎯 Jianghu UI 特色功能
+
+- ✅ JhQueryFilter 集成 - 强大的高级筛选
+- ✅ Vuetify 深度集成 - 完美的 Material Design
+- ✅ 移动端优化 - 响应式设计
+- ✅ 丰富的插槽系统 - 高度可定制
+
+## 🚀 最新增强能力（v2.1）
+
+### 1. 原生 v-data-table 属性透传
+通过 `dataTableProps` 或直接在 `<jh-table>` 上声明属性，即可传递 Vuetify `v-data-table` 的原生能力（如 `hide-default-footer`、`show-expand`、`item-class` 等），迁移老项目时几乎零成本。
+
+```vue
+<jh-table
+  :headers="headers"
+  :items="items"
+  hide-default-footer
+  :data-table-props="{ showExpand: true, disablePagination: true }"
+/>
+```
+
+### 2. 多列排序 & 受控排序
+- 新增 `sortBy`、`sortDesc`、`multiSort`、`mustSort` 属性
+- 新增 `sort-change`、`update:sortBy`、`update:sortDesc` 事件
+- 服务端模式自动携带 `sorter` 信息，便于后端直接解析
+
+```vue
+<jh-table
+  :headers="headers"
+  :request="fetchData"
+  multi-sort
+  :sort-by="['createdAt']"
+  :sort-desc="[true]"
+  @sort-change="({ sorter }) => console.log(sorter)"
+/>
+```
+
+### 3. 列状态持久化（columnsState）
+
+```vue
+<jh-table
+  :headers="headers"
+  :columns-state="{
+    persistenceKey: 'user-table-columns',
+    defaultVisible: { email: false },
+    value: customState
+  }"
+  @columns-state-change="val => customState = val"
+/>
+```
+
+> 会自动使用 `localStorage` 缓存列显示状态，刷新或重新登录依旧生效。
+
+### 4. 对齐 ProTable 的 rowSelection API
+- `rowSelection.type = 'radio' | 'checkbox'`
+- `rowSelection.defaultSelectedRowKeys`
+- `rowSelection.selectedRowKeys`（受控模式）
+- `rowSelection.onChange(selectedKeys, selectedRows)`
+
+```vue
+<jh-table
+  :headers="headers"
+  :items="items"
+  :row-selection="{
+    type: 'radio',
+    defaultSelectedRowKeys: [1],
+    onChange: (keys, rows) => console.log(keys, rows)
+  }"
+/>
+```
+
+### 5. 自定义批量操作提示（tableAlertRender）
+
+- `tableAlertRender`：函数或 `false`。函数签名为 `(h, { selectedRows, selectedRowKeys, onCleanSelected }) => VNode`，返回的内容会替换默认 “已选择 X 项” 提示；配置为 `false` 时隐藏默认提示。
+- `tableAlertOptionRender`：函数或 `false`。同样接受 `{ selectedRows, selectedRowKeys, onCleanSelected }`，可输出批量操作按钮；也可以直接使用 `#alert-actions` slot。
+- 插槽优先级高于 props，方便在单文件组件内直接书写模板；若同时设置 `tableAlertRender === false` 且无插槽，则整块提示区域不会出现。
+
+```vue
+<jh-table
+  :headers="headers"
+  :items="apps"
+  show-select
+  :table-alert-render="(h, { selectedRows, onCleanSelected }) => {
+    const totalPods = selectedRows.reduce((sum, row) => sum + row.podCount, 0);
+    const totalCalls = selectedRows.reduce((sum, row) => sum + row.callCount, 0);
+    return h('div', { class: 'd-flex align-center flex-wrap gap-4' }, [
+      h('span', { class: 'font-weight-medium' }, `已选 ${selectedRows.length} 项`),
+      h('v-btn', {
+        props: { text: true, xSmall: true, color: 'primary' },
+        on: { click: onCleanSelected }
+      }, '取消选择'),
+      h('span', `容器数量：${totalPods} 个`),
+      h('span', `调用量：${totalCalls} 次`)
+    ]);
+  }"
+  :table-alert-option-render="(h, { selectedRows }) => h('div', [
+    h('v-btn', { props: { small: true, color: 'error' } }, '批量删除'),
+    h('v-btn', { props: { small: true, outlined: true, color: 'primary' } }, '导出数据')
+  ])"
+/>
+```
+
+## 📱 响应式设计
+
+组件针对移动端进行了全面优化：
+- 自动调整工具栏布局
+- 操作列在移动端显示为下拉菜单
+- 批量操作栏自适应布局
+- 表格密度自动调整
+
+## 🎨 主题定制
+
+组件完全遵循 Vuetify 主题系统，支持：
+- 颜色主题定制
+- 暗黑模式
+- 自定义样式覆盖
+
+## 📝 更新日志
+
+### v2.1.0 (2024-04)
+- ♻️ `dataTableProps` + `$attrs` 透传原生 `v-data-table` 能力，迁移更顺滑
+- ✨ 新增列状态持久化 `columnsState`，支持 `localStorage` 和受控模式
+- ✨ 新增 `sortBy`/`sortDesc`/`multiSort`/`mustSort` 以及 `sort-change` 事件
+- ✨ rowSelection 对齐 ProTable（`type`、`defaultSelectedRowKeys`、`selectedRowKeys`、`onChange`）
+- 🧼 selection 事件、`page`、`items-per-page`、`click:row` 等事件与 Vuetify 行为保持一致
+
+### v2.0.0 (2024-01)
+- ✨ 新增 ProTable 样式系统（headerTitle, tooltip, cardBordered, ghost）
+- ✨ 新增批量操作提示栏（alert, alert-actions 插槽）
+- ✨ 新增轮询刷新功能（polling）
+- ✨ 新增搜索防抖功能（debounceTime）
+- 🎨 优化工具栏布局和样式
+- 🎨 优化移动端适配
+- 📝 完善文档和示例
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 📄 License
+
+MIT