@jzt-packages/components 1.0.0

package/src/JztQueryTable/README.md

@@ -0,0 +1,567 @@
+# JztQueryTable 查询表格组件
+
+> 一个基于 **配置驱动（Config-Driven）** 的查询表格组件，在 `el-table` 基础上做了二次封装。把一个表格页常见的「搜索区 + 顶部操作按钮 + 表格主体 + 操作列 + 分页」全部封装成配置项，页面里几乎不写搜索 / 重置 / 分页逻辑。
+
+适用场景：列表查询页、带 Tab 的数据页、主从选择弹窗等。
+
+> ⚠️ **关于同目录下的 `QueryTable 功能.md`**：那是早期从掘金搬来的**旧版本文档**，多处已与当前代码不符（如旧的 `columns` 顶级 prop、搜索 `el` 写 `'input'` 等），**请以本 README 为准**。
+
+---
+
+## 目录
+
+- [一、核心特性](#一核心特性)
+- [二、快速上手](#二快速上手)
+- [三、组件结构与数据流](#三组件结构与数据流)
+- [四、组件 Props（ProTableProps）](#四组件-propsprotableprops)
+- [五、数据请求与分页约定](#五数据请求与分页约定)
+- [六、tableConfig.columns 列配置](#六tableconfigcolumns-列配置)
+- [七、tableConfig.queryItems 搜索配置](#七tableconfigqueryitems-搜索配置)
+- [八、enum 字典](#八enum-字典)
+- [九、顶部按钮 topList 与操作列 operation](#九顶部按钮-toplist-与操作列-operation)
+- [十、特殊列 columnConfig（选择/序号/展开/排序）](#十特殊列-columnconfig选择序号展开排序)
+- [十一、多选与单选](#十一多选与单选)
+- [十二、Tabs 页签切换](#十二tabs-页签切换)
+- [十三、自定义渲染（render / 插槽 / 表头）](#十三自定义渲染render--插槽--表头)
+- [十四、暴露的属性和方法（ref）](#十四暴露的属性和方法ref)
+- [十五、事件](#十五事件)
+- [十六、插槽](#十六插槽)
+- [十七、列配置功能](#十七列配置功能)
+- [十八、常见踩坑点](#十八常见踩坑点)
+
+---
+
+## 一、核心特性
+
+1. **属性透传**：组件通过 `v-bind="$attrs"` 把所有属性 / 事件透传给 `el-table`，**支持 el-table 的全部 Props、事件、方法**，无额外心智负担。
+2. **搜索 / 重置 / 分页全自动**：传入 `requestApi` 即可，组件内部 hooks（`useTable`）托管搜索、重置、分页查询。
+3. **配置化搜索区**：在列配置上写 `search` 字段即可让该项变成搜索条件，复用 `JztSearchForm`（Grid 响应式布局）。
+4. **字典 enum**：列 / 搜索项共用一份 `enum`，自动格式化单元格内容 & 填充搜索下拉。
+5. **内置操作按钮**：顶部 `topList`、行内 `operation` 操作列，支持权限、二次确认、动态显隐、自定义渲染。
+6. **多选 / 单选 / 展开 / 拖拽排序**：开箱即用，跨页多选也支持。
+7. **Tabs 页签**：内置 `tabs-list`，切换 Tab 自动切换列配置 / 重新请求。
+8. **列配置持久化**：配合 `gridParams`，支持用户自定义列显隐、顺序、每页条数并保存到后端。
+
+---
+
+## 二、快速上手
+
+最小可用示例（接口请求 + 搜索 + 分页 + 操作列）：
+
+```vue
+<template>
+  <JztQueryTable
+    ref="proTable"
+    :table-config="tableConfig"
+    :request-api="getUserList"
+    row-key="id"
+  >
+    <!-- 行内操作按钮的另一种写法：用插槽 -->
+    <template #operation="scope">
+      <el-button type="primary" link @click="onEdit(scope.row)">编辑</el-button>
+    </template>
+  </JztQueryTable>
+</template>
+
+<script setup lang="tsx">
+import { JztQueryTable } from '@jzt-spd/components'
+import type { ProTableInstance, TableConfigProps } from '@jzt-spd/components/JztQueryTable'
+import { getUserList, getUserStatus } from '@/api/modules/user'
+
+const proTable = ref<ProTableInstance>()
+
+const tableConfig = reactive<TableConfigProps>({
+  // 1. 搜索条件（数组里每项既描述列，又可带 search 描述搜索框）
+  queryItems: [
+    { prop: 'username', label: '用户姓名', search: { el: 'el-input' } },
+    {
+      prop: 'status', label: '用户状态',
+      enum: getUserStatus,                                  // 异步字典
+      fieldNames: { label: 'userLabel', value: 'userStatus' },
+      search: { el: 'el-select', props: { filterable: true } }
+    },
+    {
+      prop: 'createTime', label: '创建时间',
+      search: {
+        el: 'el-date-picker',
+        span: 2,                                            // 搜索区占 2 列
+        props: { type: 'datetimerange', valueFormat: 'YYYY-MM-DD HH:mm:ss' }
+      }
+    }
+  ],
+  // 2. 顶部操作按钮
+  topList: [
+    { text: '新增', type: 'primary', fun: () => openDialog('add') },
+    { text: '批量删除', type: 'danger', fun: (scope) => batchDelete(scope.selectedListIds) }
+  ],
+  // 3. 表格列
+  columns: [
+    { type: 'selection', fixed: 'left', width: 55 },         // 多选列
+    { prop: 'username', label: '用户姓名', width: 150 },
+    { prop: 'status', label: '状态', tag: true, enum: getUserStatus, fieldNames: { label: 'userLabel', value: 'userStatus' } },
+    { prop: 'createTime', label: '创建时间', width: 180 },
+    {
+      prop: 'operation', label: '操作', fixed: 'right', width: 160,
+      btnLList: [
+        { text: '编辑', fun: (row) => openDialog('edit', row) },
+        { id: 'delete', text: '删除', type: 'danger', fun: (row) => deleteRow(row) } // id:'delete' 自动二次确认
+      ]
+    }
+  ]
+})
+
+const onEdit = (row) => openDialog('edit', row)
+</script>
+```
+
+> 💡 **导入约定**
+> - 组件：`import { JztQueryTable } from '@jzt-spd/components'`
+> - 类型：`import type { ProTableInstance, TableConfigProps, ColumnProps, TopButtonProps, tabsListProps } from '@jzt-spd/components/JztQueryTable'`
+
+---
+
+## 三、组件结构与数据流
+
+```
+JztQueryTable/
+├── index.vue                  # 主组件：搜索区 + 表头按钮 + el-table + 分页
+├── interface/index.ts         # 类型定义（ColumnProps / TopButtonProps / TableConfigProps 等）
+├── components/
+│   ├── TableColumn.vue        # 单列渲染：render/插槽/字典格式化/tag/小数/千分号
+│   ├── Pagination.vue         # 分页
+│   ├── ColumnsSetting.vue     # 列配置弹窗（显隐/排序/每页条数）
+│   └── ...
+└── hooks/
+    ├── useQueryTable.ts       # useTable（请求/分页）+ useOperation（展开）
+    └── useSelection.ts        # 多选状态管理
+```
+
+**数据流**：
+
+```
+tableConfig.queryItems ──> JztSearchForm（搜索区，Grid 布局）
+                          │
+                          ▼  点击搜索/重置
+                    useTable.getTableList()
+                          │
+requestApi(搜索参数 + 分页) ▼
+            ┌── dataCallback（可选，处理返回结构）──┐
+            ▼                                       │
+  { result/list, totalCount }  ──> tableData ──> el-table 渲染
+```
+
+---
+
+## 四、组件 Props（ProTableProps）
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `tableConfig` | `TableConfigProps` | **必填** | 表格三合一配置：`{ queryItems, columns, topList }` |
+| `requestApi` | `(params) => Promise` | - | 请求表格数据的接口（与 `data` 二选一） |
+| `data` | `any[]` | - | **静态数据**；传了它则不会用 `requestApi`，并支持前端分页 |
+| `requestAuto` | `boolean` | `true` | 初始化时是否自动请求 |
+| `dataCallback` | `(data) => data` | - | 对接口返回数据做结构转换（见 [第五章](#五数据请求与分页约定)） |
+| `initParam` | `object` | `{}` | 初始化请求参数，**每次请求都会带上**；变化会触发重新请求 |
+| `pagination` | `boolean` | `true` | 是否显示分页 |
+| `rowKey` | `string` | `'id'` | 行唯一标识（多选 / 树形 / 单选必填） |
+| `border` | `boolean` | `true` | 是否显示纵向边框 |
+| `toolButton` | `boolean \| Array` | `true` | 右上角功能按钮：`['refresh','setting','fullScreen']` |
+| `columnConfig` | `ColumnConfigProps` | - | 特殊列配置（选择 / 序号 / 展开 / 排序） |
+| `tabsList` | `tabsListProps[]` | - | Tab 页签数据 |
+| `tabActive` / `tabActiveName` | `string \| number` | - | Tab 当前值 / 绑定到 `initParam` 的 key |
+| `tabType` | `'' \| 'card' \| 'border-card'` | `''` | Tab 样式 |
+| `tabIsTop` | `boolean` | `false` | Tab 是否放在搜索区顶部 |
+| `tabChangeSearch` | `boolean` | `false` | 切换 Tab 是否自动重新请求 |
+| `searchCol` | `number \| object` | `{xs:1,sm:2,md:3,lg:4,xl:5,xxl:6}` | 搜索区每行列数（响应式） |
+| `searchCard` / `tableCard` | `boolean` | `true` | 搜索区 / 表格区是否卡片样式 |
+| `allowCollapsed` / `collapsed` | `boolean` | `true` | 搜索区是否可折叠 / 默认折叠 |
+| `validQuery` | `boolean` | `false` | 是否校验搜索条件必填项 |
+| `searchClear` | `boolean` | `true` | 搜索时是否清空已勾选 / 单选 |
+| `gridParams` | `{ gridId, url }` | - | 开启**列配置持久化**必须传 |
+| `rowClassName` | `Function \| string` | - | 行样式 class |
+| `emptyText` | `string` | `'暂无内容'` | 空数据文案 |
+| `minHeight` | `string \| false` | `'170px'` | 表格最小高度 |
+
+> **透传**：其余所有属性 / 事件（如 `highlight-current-row`、`show-summary`、`span-method`、`@row-click`）都通过 `$attrs` 透传给 `el-table`，按 Element Plus 文档用即可。
+
+---
+
+## 五、数据请求与分页约定
+
+### 1. 后端返回结构约定
+
+组件默认按如下结构解析返回数据：
+
+```ts
+{
+  result: [...] | list: [...],   // 列表数据（result 优先，其次 list）
+  totalCount: 100                 // 总条数（分页时）
+}
+```
+
+如果你的接口字段不一致，用 `dataCallback` 转换：
+
+```ts
+:data-callback="(data) => ({ list: data.items, totalCount: data.total })"
+```
+
+### 2. 分页参数约定
+
+- 发给后端的分页参数为 `{ pageIndex, pageSize }`，其中 **`pageIndex` 从 0 开始**（组件内部已做 `pageIndex - 1`）。
+- 前端 `pageable.pageIndex` 从 1 开始（仅用于展示）。
+- `pagination=false` 时，不发分页参数，且 `data` 若是数组则直接展示。
+
+### 3. 请求前对参数加工
+
+- `searchFilter: (form) => form`：在请求前对合并后的参数做最后加工。
+- `requestError: (err) => void`：请求失败回调。
+- `tableLoaded: (data) => void`：数据加载完成回调。
+
+### 4. 静态数据 + 前端分页
+
+传 `:data="arr"` 且不传 `requestApi`，组件自动做**前端切片分页**。
+
+---
+
+## 六、tableConfig.columns 列配置
+
+每个元素是 `ColumnProps`（继承 `el-table-column` 全部属性）：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `prop` | `string` | 字段名，**支持多级**：`'user.detail.age'` |
+| `label` | `string` | 列标题 |
+| `type` | `TypeProps` | 特殊列：`'index' \| 'selection' \| 'radio' \| 'expand' \| 'sort'` |
+| `width` / `minWidth` / `fixed` / `align` | - | 同 `el-table-column`（`align` 默认 `'left'`） |
+| `isShow` | `boolean \| Ref<boolean>` | 是否显示该列（默认 `true`） |
+| `isSetting` | `boolean \| Ref<boolean>` | 是否在列配置弹窗中可被用户调整（默认 `true`） |
+| `enum` | 见 [第八章](#八enum-字典) | 字典，自动格式化单元格内容 |
+| `isFilterEnum` | `boolean` | 单元格是否按 enum 格式化（默认 `true`；若 enum 仅用于搜索可设 `false`） |
+| `fieldNames` | `{ label, value, children }` | 自定义字典字段映射 |
+| `tag` | `boolean` | 是否用 `el-tag` 展示（配合 enum 的 `tagType`） |
+| `render` | `(scope) => VNode` | 自定义单元格内容（tsx） |
+| `headerRender` | `(scope) => VNode` | 自定义表头（tsx） |
+| `formatter` | `(scope) => string` | 格式化单元格值 |
+| `decimal` | `number \| 'numDecimal' \| 'countDecimal'` | 小数位数（`numDecimal`=金额配置、`countDecimal`=数量配置） |
+| `isPerMille` | `boolean` | 是否千分号分隔 |
+| `isUnderline` | `boolean` | 是否下划线 link 样式（配合 `fun` 点击） |
+| `fun` | `(scope) => void` | 单元格点击事件（配合 `isUnderline`） |
+| `_children` | `ColumnProps[]` | **多级表头** |
+| `btnLList` | `TopButtonProps[]` | **操作列按钮**（`prop` 必须为 `'operation'`） |
+| `selectable` | `(row, index) => boolean` | 多选时某行是否可选 |
+
+> **单元格渲染优先级**（`TableColumn.vue`）：
+> `render` > `插槽(#prop)` > `isUnderline 可点击文本` > `enum 字典格式化 / formatter / decimal` > 原始值。
+>
+> **表头渲染优先级**：`headerRender` > `插槽(#propHeader)` > `label`。
+
+---
+
+## 七、tableConfig.queryItems 搜索配置
+
+搜索项就是「列 + search 配置」。每个元素是 `QueryItemsProps`：
+
+| 字段 | 说明 |
+| --- | --- |
+| `prop` | 搜索字段名（提交接口的字段） |
+| `label` | 标签 |
+| `search` | **核心**，`SearchProps`，配置搜索框（见下表） |
+| `enum` / `fieldNames` | 字典（与列共用） |
+| `isSetFirstValue` | 是否默认选中第一项（异步字典） |
+| `cascader` / `isAwait` | 级联：声明下级 / 等待上级 |
+| `change` | `(scope) => void`，`scope` 含 `searchForm`、`value` 等 |
+| `rules` | 校验规则（配合 `validQuery`） |
+| `isShow` | 是否在搜索区显示 |
+
+**`SearchProps` 关键字段：**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `el` | `SearchType` | 控件类型，**必须带 `el-` 前缀**：`'el-input'`、`'el-select'`、`'el-date-picker'`、`'el-tree-select'`、`'el-cascader'`、`'el-radio-group'` 等 |
+| `props` | `object` | 透传给控件（如 `placeholder`、`filterable`、`type`、`valueFormat`） |
+| `events` | `object` | 透传事件（如 `change`、`focus`） |
+| `defaultValue` | `any` | 默认值（重置时回到此值） |
+| `span` | `number` | 占用列数，默认 `1`（与表格列的 24 栅格不同，这里是搜索区 Grid 列数） |
+| `offset` | `number` | 左侧偏移列数 |
+| `order` | `number` | 排序（数值越小越靠前） |
+| `key` | `string` | 提交字段名与 `prop` 不同时用 `key` 指定 |
+| `tooltip` | `string` | 搜索提示 |
+| `render` | `(scope) => VNode` | 完全自定义搜索控件（tsx） |
+| `isEnter` | `boolean` | 是否开启回车搜索 |
+
+> ⚠️ **常见错误**：旧文档写 `search: { el: 'input' }`，**当前版本必须写 `el: 'el-input'`**（带前缀），否则不渲染。
+
+---
+
+## 八、enum 字典
+
+`enum` 三种写法，**列与搜索项共用一份**：
+
+```ts
+// 1. 静态数组
+enum: [{ label: '启用', value: 1 }, { label: '禁用', value: 0 }]
+
+// 2. 异步接口（函数，无参）
+enum: getUserStatus
+
+// 3. 异步接口（带参）
+enum: (val) => getChildList(val)     // 级联时 val = 上级值
+enum: async () => { const res = await getX(); return res }  // 自定义处理
+```
+
+- 字段名不是 `label/value` 时，配 `fieldNames` 映射：
+  ```ts
+  fieldNames: { label: 'userLabel', value: 'userStatus' }
+  ```
+- 列默认会用 enum 把 `value` 反显成 `label`；若 enum 只想给搜索框用，设 `isFilterEnum: false`。
+- 配合 `tag: true`，可用 `el-tag` 展示，tag 类型取 enum 项的 `tagType`。
+
+---
+
+## 九、顶部按钮 topList 与操作列 operation
+
+两者结构相同，都是 `TopButtonProps[]`：
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 唯一标识；**`id: 'delete'` 会自动弹出二次确认** |
+| `text` | 按钮文字 |
+| `type` | `'primary' \| 'success' \| 'warning' \| 'danger' \| 'info'` |
+| `fun` | 点击回调（见下方参数说明） |
+| `hasPerm` | 权限标识，无权限自动隐藏 |
+| `icon` / `plain` / `link` / `round` / `circle` / `loading` / `disabled` | 同 `el-button` |
+| `hideFun` / `disabledFn` | 动态隐藏 / 禁用（返回 boolean） |
+| `secondConfirm` | 自定义二次确认文案（配合弹窗确认） |
+| `render` / `slotName` | 自定义按钮内容（tsx / 插槽） |
+| `badgeProps` | 红点 / 数字角标 |
+
+**回调参数：**
+
+- **顶部按钮** `fun(scope)`：`scope` = `{ radio, radioItem, isSelected, selectedList, selectedListIds, searchParam, searchForm }`
+  - `searchForm` 是经过格式化（删除空值、拆分时间范围）后的查询参数。
+- **操作列按钮** `fun(row)`：直接是当前行数据。
+  - 删除类按钮写 `id: 'delete'`，组件自动 `ElMessageBox.confirm('确定删除该条数据吗?')`，确认后才执行 `fun`。
+
+```ts
+// 顶部按钮：拿勾选数据
+{ text: '批量删除', type: 'danger', fun: (scope) => batchDelete(scope.selectedListIds) }
+
+// 操作列：自动二次确认
+{ id: 'delete', text: '删除', type: 'danger', fun: (row) => deleteApi({ id: row.id }) }
+```
+
+---
+
+## 十、特殊列 columnConfig（选择/序号/展开/排序）
+
+除了在 `columns` 里写 `{ type: 'selection' }`，也可用 `columnConfig` 统一配置：
+
+```ts
+:column-config="{
+  layout: 'selection,radio,index,expand,sort',   // 逗号分隔的布局顺序
+  selectionProps: { fixed: 'left', width: 55 },
+  radioProps:    { width: 70 },
+  indexProps:    { label: '#' },
+  expandProps:   { render: (scope) => <div>{scope.row.detail}</div> },  // 或用 #expand 插槽
+  sortProps:     { label: '排序' }
+}"
+```
+
+- `layout` 支持的类型：`selection`（多选）、`radio`（单选）、`index`（序号）、`expand`（展开）、`sort`（拖拽排序）。
+- 各 `xxxProps` 透传给对应的 `el-table-column`。
+
+---
+
+## 十一、多选与单选
+
+- **多选**：`type: 'selection'`，勾选数据通过插槽 `scope` 或 ref 拿到。
+- **单选**：`type: 'radio'`，组件维护 `radio` / `radioItem`，点击行或单选框触发 `radioChange`。
+- 跨页多选需配 `row-key`，并在 selection 列加 `reserve-selection`。
+
+**获取选中数据（任选其一）：**
+
+```ts
+// 方式1：ref
+const { isSelected, selectedList, selectedListIds, radio, radioItem } = proTable.value?.getTableCheckedValue()
+
+// 方式2：插槽 scope（见 #tableHeader）
+<template #tableHeader="scope">
+  <el-button :disabled="!scope.isSelected" @click="batchDelete(scope.selectedListIds)">批量删除</el-button>
+</template>
+```
+
+清空选中：`proTable.value?.clearSelection()`。
+
+---
+
+## 十二、Tabs 页签切换
+
+```ts
+:tabs-list="[
+  { label: '全部', value: 0 },
+  { label: '待审核', value: 1, tabCount: 5 }   // tabCount 显示数量角标
+]"
+tab-active-name="activeType"      // 绑定到 initParam.activeType
+@tab-change="(val) => onTabChange(val)"
+```
+
+- 切换 Tab 会把值写入 `initParam[tabActiveName]`，并可通过 `tabChangeSearch` 自动重新请求。
+- **不同 Tab 不同列**：在 `@tab-change` 里动态替换 `tableConfig.columns`。
+- 每个 Tab 可配独立 `gridId`（用于独立的列配置）；若所有 Tab 的 `gridId` 一致或都没有，则共享同一份列配置。
+
+---
+
+## 十三、自定义渲染（render / 插槽 / 表头）
+
+### 1. tsx render（最灵活）
+
+```tsx
+{
+  prop: 'status', label: '状态',
+  render: (scope) => (
+    <el-tag type={scope.row.status ? 'success' : 'danger'}>
+      {scope.row.status ? '启用' : '禁用'}
+    </el-tag>
+  )
+}
+```
+
+### 2. 作用域插槽（无需 tsx）
+
+```vue
+<!-- 单元格：#prop -->
+<template #status="scope">
+  <el-tag>{{ scope.row.status ? '启用' : '禁用' }}</el-tag>
+</template>
+
+<!-- 表头：#propHeader -->
+<template #createTimeHeader="scope">
+  <span style="color: #3475fa">{{ scope.column.label }}</span>
+</template>
+```
+
+### 3. 表头 headerRender
+
+```tsx
+{ prop: 'createTime', label: '创建时间',
+  headerRender: (scope) => <el-button onClick={...}>{scope.column.label}</el-button> }
+```
+
+---
+
+## 十四、暴露的属性和方法（ref）
+
+通过 `proTable.value.xxx` 调用：
+
+| 属性 / 方法 | 说明 |
+| --- | --- |
+| `element` | `el-table` 实例，可调用任意原生方法（如 `element.toggleRowSelection()`） |
+| `tableData` | 当前展示的数据 |
+| `pageable` | 分页信息 `{ pageIndex, pageSize, total }` |
+| `searchParam` / `searchInitParam` | 当前 / 初始查询参数 |
+| `formattedSearchForm` | 格式化后的查询参数 |
+| `isSelected` / `selectedList` / `selectedListIds` | 多选状态 |
+| **`getTableList()`** | 重新请求（携带当前查询 + 分页）—— **操作后刷新常用** |
+| `search()` | 查询（重置到第 1 页） |
+| `reset()` | 重置查询参数并重新请求 |
+| `searchAndClear()` | 查询并清空勾选 / 单选 |
+| `handleSizeChange(n)` / `handleCurrentChange(n)` | 改变每页条数 / 当前页 |
+| `clearSelection()` | 清空多选 |
+| `setRadioItem(key, row)` | 设置单选 |
+| `getTableCheckedValue()` | 一次性拿到所有选中数据 |
+| `toggleExpandAll(status?)` | 展开 / 折叠全部 |
+| `changeTableData(cb)` | 回调式修改表格数据 |
+| `saveColumns()` | 保存列配置 |
+| `enumMap` | 当前表格所有字典数据（Map） |
+
+**典型用法**：增删改后刷新 → `proTable.value?.getTableList()`。
+
+---
+
+## 十五、事件
+
+| 事件 | 回调参数 | 说明 |
+| --- | --- | --- |
+| `search` | `searchForm` | 点击搜索 |
+| `reset` | - | 点击重置 |
+| `selectionChange` | `{ isSelected, selectedList, selectedListIds }` | 多选变化 |
+| `radioChange` | `(key, row)` | 单选变化 |
+| `tabChange` | `val` | Tab 切换 |
+| `dragSort` | `{ newIndex, oldIndex }` | 拖拽排序完成 |
+| `rowClick` | `(row, column)` | 行点击 |
+| `cellClick` | `(row, column)` | 单元格点击 |
+| `getEndColumns` | `{ allColumns, checkColumns, pageSize, id }` | 列配置变化 |
+| `refreshColumnTable` | `type` | 列配置确定 / 重置 |
+
+> el-table 原生事件（`sort-change`、`filter-change` 等）同样通过 `$attrs` 透传，直接 `@sort-change="..."` 即可。
+
+---
+
+## 十六、插槽
+
+| 插槽 | 说明 |
+| --- | --- |
+| `tableHeader` | 表头左侧操作区（常用，含 `scope` 选中数据） |
+| `toolBtnLeft` / `toolBtnRight` | 顶部按钮左右两侧（含 `scope`） |
+| `tableTops` | 表格最顶部（搜索区下方、表格上方） |
+| `tableBottom` | 表格底部（如「+ 新增行」按钮） |
+| `rightBtn` / `formTopSlot` | 搜索区右侧 / 顶部 |
+| `queryTableMain` | 整个表格主体（完全自定义） |
+| `append` | 表格最后一行之后的内容 |
+| `empty` / `empty-desc` | 空数据自定义 |
+| `pagination` / `pageFooter` | 分页区 |
+| `#prop` / `#propHeader` | 单元格 / 表头作用域插槽 |
+| `expand` | 展开行内容 |
+| `settingBtnLeft` / `toolButton` | 功能按钮区扩展 |
+
+---
+
+## 十七、列配置功能
+
+让用户自定义「列显隐、顺序、每页条数」并保存到后端：
+
+```ts
+:tool-button="['refresh', 'setting', 'fullScreen']"
+:grid-params="{ gridId: 'your-grid-id', url: '/api/column-setting' }"
+```
+
+- 传了 `gridParams.url` 后，右上角齿轮按钮（`setting`）才会弹出列配置弹窗。
+- 不传 `gridParams` 时，`setting` 仅为前端临时调整（刷新丢失）。
+- 变化后通过 `@get-end-columns` 把结果回传给业务侧持久化。
+
+---
+
+## 十八、常见踩坑点
+
+1. **搜索 `el` 必须带 `el-` 前缀**：写 `'el-input'` 而非 `'input'`（旧文档的写法已失效）。可用类型见 `SearchType`。
+
+2. **配置走 `table-config`，不是顶级 `columns`**：当前版本用 `:table-config="{ queryItems, columns, topList }"`，旧文档的 `:columns="..."` 已废弃。
+
+3. **分页 `pageIndex` 从 0 开始**：组件已自动转换，后端按 0 起算；如果你的后端从 1 起算，需在 `requestApi` 里自行 `+1`。
+
+4. **返回字段不是 `result/totalCount`**：务必用 `dataCallback` 转成 `{ result/list, totalCount }`，否则表格空、分页失效。
+
+5. **多选 / 树形必须配 `row-key`**，跨页多选还需 selection 列的 `reserve-selection`。
+
+6. **删除按钮的二次确认**：操作列按钮 `id` 设为 `'delete'` 才会自动弹确认框；自定义文案用 `secondConfirm`。顶部按钮**不会**自动确认，需自己在 `fun` 里 `ElMessageBox.confirm`。
+
+7. **刷新表格统一用 `getTableList()`**：增删改后调 `proTable.value?.getTableList()`，不要手动改 `tableData`。
+
+8. **`initParam` 变化会自动重新请求**：适合做「外部条件驱动表格」（如 Tab、外部筛选）。若不希望自动请求，设 `:request-auto="false"` 后手动调 `getTableList()`。
+
+9. **静态数据 `data` 与 `requestApi` 互斥**：传了 `data` 就不会请求接口，且默认走前端分页。
+
+10. **`isShow` 可用 Ref 动态控制列显隐**：`isShow: toRef(myRef)`，适合「切换显示某列」的场景。
+
+---
+
+## 附：真实示例参考
+
+| 场景 | 参考文件 |
+| --- | --- |
+| **官方完整示例（搜索/Tab/操作列/渲染）** | `spd-main-layout/src/views/proTable/useQueryTable/index.vue` |
+| 复杂表格（多级表头 / 合计 / 合并 / 行样式） | `spd-main-layout/src/views/proTable/useComplexProTable/index.vue` |
+| 树形过滤 + 表格 | `spd-main-layout/src/views/proTable/useTreeFilter/index.vue` |
+| 业务列表（订单配送率） | `spd-basic-system/src/views/order/orderDeliveryRate/index.vue` |
+
+> 建议新人先跑 `useQueryTable/index.vue`，对照本文档逐项调试，覆盖了 90% 的常用功能。

package/src/JztQueryTable/components/ColSetting.vue

@@ -0,0 +1,67 @@
+<template>
+  <!-- 列设置 -->
+  <el-drawer v-model="drawerVisible" title="列设置" size="450px">
+    <div class="table-main">
+      <el-table
+        :data="colSetting"
+        :border="true"
+        row-key="prop"
+        default-expand-all
+        :tree-props="{ children: '_children' }"
+      >
+        <el-table-column prop="label" align="center" label="列名" />
+        <el-table-column
+          v-slot="scope"
+          prop="isShow"
+          align="center"
+          label="显示"
+        >
+          <el-switch
+            v-model="scope.row.isShow"
+            @change="changeShow(scope.row)"
+          ></el-switch>
+        </el-table-column>
+        <el-table-column
+          v-slot="scope"
+          prop="sortable"
+          align="center"
+          label="排序"
+        >
+          <el-switch v-model="scope.row.sortable"></el-switch>
+        </el-table-column>
+        <template #empty>
+          <div class="table-empty">
+            <img src="../assets//images//notData.png" alt="notData" />
+            <div>暂无可配置列</div>
+          </div>
+        </template>
+      </el-table>
+    </div>
+  </el-drawer>
+</template>
+
+<script setup lang="ts" name="ColSetting">
+import { ref } from "vue";
+import { ColumnProps } from "../interface";
+
+defineProps<{ colSetting: ColumnProps[] }>();
+
+const drawerVisible = ref<boolean>(false);
+
+const openColSetting = () => {
+  drawerVisible.value = true;
+};
+const changeShow = (row: ColumnProps) => {
+  row.isHide = !row.isShow;
+};
+
+defineExpose({
+  openColSetting,
+});
+</script>
+
+<style scoped lang="scss">
+.cursor-move {
+  cursor: move;
+}
+</style>