vue3-components-plus 3.0.30 → 3.0.32

package/dist/ComponentDemo/DialogDemo.vue

@@ -54,8 +54,8 @@ function openDialog(data = {}) {
         },
       },
       width: '800px', // 宽度, 整个弹出框的高度，非内容高度
-      height: '450px', // 高度, 不配置则默认为内容高度
-      dialogPadding: [10, 20], // 弹窗内padding
+      height: '50%', // 高度, 不配置则默认为内容高度
+      dialogPadding: [100], // 弹窗内padding
       // 设置函数时，则有放大和还原按钮，且按返回的对象设置弹出框。（会关闭拖动功能）
       // maxSize: function () {
       //   return { width: '100%', height: '800px', x: 0, y: 100 }

package/dist/ComponentDemo/NsTableDemo/NsTableDemoReadme.md

@@ -0,0 +1,677 @@
+# NsTable 组件族使用说明（`NsTableContainer` / `NsSearch` / `NsTable`）
+
+本文档只描述当前仓库表格体系的真实能力，重点帮助 AI 生成“搜索、表格、分页、列渲染、跨页选择”一体化页面代码。
+
+## 1. 组件关系
+
+| 组件 | 路径 | 作用 |
+|---|---|---|
+| `NsTableContainer` | `packages/components/NsTable/PageContainer.vue` | 搜索 + 表格 + 分页 + 选中状态总控 |
+| `NsSearch` | `packages/components/NsTable/PageSearch.vue` | 搜索区 |
+| `NsTable` | `packages/components/NsTable/PageTable.vue` | 表格主体与分页条 |
+| `TableColumn` | `packages/components/NsTable/TableColumn.js` | 递归列渲染器 |
+
+推荐优先使用 `NsTableContainer`，这样搜索、分页、选中同步逻辑都交给容器维护。
+
+## 2. 最小接入示例
+
+```vue
+<NsTableContainer
+  ref="tableRef"
+  :search-items="searchItems"
+  :table-data="tableData"
+  :columns="columns"
+  :total="total"
+  :table-props="{ rowKey: 'id', showSelection: true, showIndex: true }"
+  @search="handleSearch"
+  @selection-change="handleSelectionChange"
+/>
+```
+
+> 数据加载只需监听 `@search` 事件即可。容器会在搜索、重置、分页、排序变化时统一通过 `emitSearch()` 重新派发该事件，事件参数即可作为请求体直接发出。
+
+## 3. `NsTableContainer`
+
+### 3.1 Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `showSearch` | `Boolean` | `true` | 是否显示搜索区 |
+| `externalSearchParams` | `Object` | `{}` | 搜索默认值或外部回填值（合并到搜索表单初始值） |
+| `searchItems` | `Array` | `[]` | 搜索配置 |
+| `tableData` | `Array` | `[]` | 表格数据 |
+| `columns` | `Array` | `[]` | 列配置 |
+| `actionButtons` | `Array` | `[]` | 预留字段，当前未直接渲染（可由业务方在 `header-actions` 插槽中自行使用） |
+| `total` | `Number` | `0` | 总条数 |
+| `pageNumberKey` | `String` | `'currentPage'` | `@search` 事件参数 / `getPagination()` 中的页码键名 |
+| `pageSizeKey` | `String` | `'pageSize'` | `@search` 事件参数 / `getPagination()` 中的条数键名 |
+| `pageTotalKey` | `String` | `'total'` | `getPagination()` 返回对象的总数键名 |
+| `enterTrigger` | `Boolean` | `true` | 是否开启回车触发“查询”按钮 |
+| `searchProps` | `Object` | `{}` | 透传给 `NsSearch` |
+| `tableProps` | `Object` | `{}` | 透传给 `NsTable` |
+| `useDefaultPage` | `Boolean` | `true` | `true` 使用容器内部维护的页码 / 页大小（推荐，TableDemo.vue 即为此模式）；`false` 走外部 `currentPage / pageSize` 受控模式，并随分页变化派发 `update:currentPage`、`update:pageSize` |
+| `currentPage` | `Number \| null` | `null` | 受控页码，仅在 `useDefaultPage=false` 时使用 |
+| `pageSize` | `Number \| null` | `null` | 受控每页条数，仅在 `useDefaultPage=false` 时使用 |
+
+### 3.2 事件
+
+容器对外暴露的事件分两类：业务必需事件（推荐监听） 与 内部冗余事件（默认不必监听）。
+
+#### 3.2.1 推荐监听的事件
+
+| 事件 | 参数 | 说明 |
+|---|---|---|
+| `search` | `params` | 搜索 / 重置 / 翻页 / 切换条数 / 排序变化时统一派发；参数已合并搜索表单值 + 分页 + 排序，可直接发给后端 |
+| `reset` | - | 搜索区点击“重置”后触发（之后会再派发一次 `search`） |
+| `add` | - | 顶部默认新增按钮点击 |
+| `selection-change` | `selection` | 选中行变化（容器维护跨页选择，参数为跨页累计选中行） |
+| `link-click` | `row, column` | `type: 'link'` 列文本点击 |
+
+> 数据加载只接 `@search` 一个事件即可；TableDemo.vue 也是这种用法。
+
+#### 3.2.2 内部冗余事件（默认不必监听）
+
+| 事件 | 参数 | 说明 |
+|---|---|---|
+| `sort-change` | `sort` | 排序变化（已包含在 `search` 事件 `sort` 字段中） |
+| `row-click` | `row, column, event` | 行点击；仅在需要业务化高亮 / 单击响应时监听 |
+| `size-change` | `size` | 每页条数变化（`search` 已覆盖） |
+| `current-change` | `page` | 页码变化（`search` 已覆盖） |
+| `page-change` | `{ currentPage, pageSize }` | 页码或条数变化后的统一事件（`search` 已覆盖） |
+| `update:currentPage` | `page` | 双向绑定页码（仅 `useDefaultPage=false` 受控模式使用） |
+| `update:pageSize` | `size` | 双向绑定条数（仅 `useDefaultPage=false` 受控模式使用） |
+
+### 3.3 当前实现的关键行为
+
+- 搜索或重置时会先清空选中状态
+- `NsSearch` 触发查询时会携带 `_resetPage: true`，容器收到后会把页码重置为 `1`
+- 翻页 / 切换每页条数 / 排序变化时，容器内部会通过 `emitSearch()` 重新派发 `search` 事件，业务侧只需监听 `@search` 即可统一刷新数据；不需要额外调用 `loadData`
+- `emitSearch()` 派发的参数包含：合并后的搜索表单值 + `[pageNumberKey]` / `[pageSizeKey]` 当前页码与条数 + `sort: { prop, order }` 排序状态
+- `initSearchAndLoad()` 在 `showSearch=true` 时优先读取搜索表单数据后再触发 `search` 事件
+- 排序、`size-change`、`current-change` 之外，容器还会派发统一事件 `page-change`（含 `currentPage / pageSize`）
+
+### 3.4 实例方法
+
+| 方法 | 说明 |
+|---|---|
+| `initSearchAndLoad()` | 初始化查询；优先读取搜索表单数据后派发 `search` 事件 |
+| `reload()` | 以当前搜索条件 + 分页 + 排序重新派发 `search` 事件 |
+| `refresh(isFirstPage = true)` | 重新派发 `search` 事件刷新数据；`isFirstPage=true`（默认）时会把页码重置为 `1`，传 `false` 则保持当前页（等同 `reload()`） |
+| `getSearchParams()` | 获取与 `@search` 事件参数同形的 payload（合并搜索值 + 分页 + 排序），可直接用于手动发请求 |
+| `getSearchFormData()` | 读取搜索表单 |
+| `setSearchFormData(data)` | 回填搜索表单 |
+| `resetSearchForm()` | 重置搜索表单 |
+| `validateSearchForm()` | 校验搜索表单 |
+| `getPagination()` | 获取分页对象，键名遵循 `pageNumberKey / pageSizeKey / pageTotalKey` |
+| `getSelectionRows()` | 获取选中行 |
+| `getSelectionKeys()` | 获取选中 key |
+| `setSelectionRows(rows)` | 设置选中行 |
+| `setSelectionKeys(keys)` | 设置选中 key |
+| `clearAllSelection()` | 清空选中 |
+| `selectAll()` | 全选当前页 |
+| `isRowSelected(row)` | 判断某行是否选中 |
+| `isKeySelected(key)` | 判断某 key 是否选中 |
+
+> 用法示例：
+> ```js
+> // 拿到与 @search 同形的 payload，自行发请求
+> const params = containerRef.value.getSearchParams()
+> // { ...搜索表单值, [pageNumberKey]: 1, [pageSizeKey]: 10, sort: { prop, order } }
+>
+> // 刷新当前列表（保持搜索条件 / 分页 / 排序不变）
+> containerRef.value.refresh()
+> ```
+
+### 3.5 插槽
+
+| 插槽名 | 说明 |
+|---|---|
+| `extend` | 位于搜索区与表格之间的扩展区域，可放置业务提示、统计信息或额外操作 |
+
+```vue
+<NsTableContainer
+  :search-items="searchItems"
+  :table-data="tableData"
+  :columns="columns"
+  :total="total"
+>
+  <template v-slot:extend>
+    <el-alert
+      type="info"
+      :closable="false"
+      show-icon
+      title="这里是 extend 插槽"
+    />
+  </template>
+</NsTableContainer>
+```
+
+## 4. `NsSearch`
+
+### 4.1 Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `items` | `Array` | `[]` | 搜索项配置 |
+| `externalParams` | `Object` | `{}` | 默认值或外部注入值 |
+| `defaultSpan` | `Number` | `6` | 每项默认栅格 |
+| `showCollapse` | `Boolean` | `true` | 是否显示展开/收起 |
+| `collapseLimit` | `Number` | `3` | 折叠时显示数量 |
+| `slotRenderers` | `Object` | `{}` | 外部插槽渲染器映射 |
+| `actionsAlign` | `String` | `'left'` | 查询/重置按钮对齐方式，支持 `left / center / right` |
+| `actionsSpan` | `Number \| null` | `null` | 查询/重置按钮栏独立栅格，未设置时回退 `defaultSpan` |
+| `actionsWidth` | `String \| Number` | `''` | 查询/重置按钮栏独立宽度，支持如 `320px`、`30%`、`280` |
+| `collapseToggleText` | `Array \| String` | `['展开','收起']` | 展开/收起按钮文案，推荐传数组 `[展开文案, 收起文案]` |
+| `enterTrigger` | `Boolean` | `true` | 是否给“查询”按钮挂载 `v-enterClick` |
+
+### 4.2 事件
+
+| 事件 | 参数 | 说明 |
+|---|---|---|
+| `search` | `formData + _resetPage` | 查询触发 |
+| `reset` | - | 重置触发 |
+
+### 4.3 按钮栏布局配置
+
+`NsSearch` 默认按钮居左；可通过 `actionsAlign` 配置：
+
+- `left`：按钮居左（默认）
+- `center`：按钮居中
+- `right`：按钮居右
+
+还可单独控制按钮栏宽度：
+
+- `actionsSpan`：按栅格系统控制按钮栏占位
+- `actionsWidth`：按固定宽度控制按钮栏展示宽度
+- `collapseToggleText`：推荐使用数组 `[展开文案, 收起文案]`，也兼容字符串 `展开文案/收起文案`
+- `enterTrigger`：默认 `true`；设为 `false` 时，回车不会自动触发查询按钮点击
+- 同时设置时：`actionsSpan` 与 `actionsWidth` 会同时生效，实际显示宽度通常以 `actionsWidth` 为主
+- `TableDemo` 示例页中，`actionsSpan` 与 `actionsWidth` 放在同一行联动演示；`actionsSpan` 输入值会在示例代码里转成数字后再透传给 `NsSearch`
+
+示例：
+
+```vue
+<NsSearch
+  :items="searchItems"
+  :actionsAlign="'right'"
+  :actionsSpan="8"
+  actionsWidth="320px"
+  :collapseToggleText="['更多', '收起']"
+/>
+```
+
+### 4.4 实例方法
+
+| 方法 | 返回 | 说明 |
+|---|---|---|
+| `getFormData()` | `Object` | 获取搜索值 |
+| `setFormData(data)` | `void` | 合并回填 |
+| `resetForm()` | `void` | 重置并触发查询 |
+| `validate()` | `Promise<Boolean>` | 表单校验 |
+| `clearValidate(props?)` | `void` | 清除校验 |
+
+### 4.5 搜索项配置 `items[]`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `prop` | `String` | 表单字段名 |
+| `label` | `String` | 标签 |
+| `span` | `Number` | 栅格宽度 |
+| `component` | `String \| Component` | 组件 |
+| `attrs` | `Object` | 透传给组件的属性 |
+| `events` | `Object` | 透传给组件的事件 |
+| `children` | `Array` | `ElSelect` 的选项源 |
+| `defaultValue` | `Any` | 默认值 |
+| `formItemAttrs` | `Object` | 透传给 `el-form-item` |
+| `type` | `String` | `slot` 表示该项用插槽渲染 |
+| `slot` | `Boolean \| String` | 插槽开关或插槽名 |
+
+### 4.6 搜索区插槽
+
+| 插槽名 | scope |
+|---|---|
+| `actions-after-reset` | `{ formData, handleSearch, handleReset, isCollapsed }` |
+| 自定义搜索项插槽 | `{ formData, item }` |
+
+```vue
+<template v-slot:actions-after-reset="{ formData, handleSearch }">
+  <el-button link @click="() => { formData.status = 1; handleSearch() }">仅看启用</el-button>
+</template>
+```
+
+## 5. `NsTable`
+
+### 5.1 Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `tableData` | `Array` | `[]` | 表格数据 |
+| `columns` | `Array` | `[]` | 列配置 |
+| `actionButtons` | `Array` | `[]` | 预留字段 |
+| `showAddButton` | `Boolean` | `true` | 是否显示默认新增按钮 |
+| `addButtonText` | `String` | `'新增'` | 新增按钮文案 |
+| `showHeaderToolbar` | `Boolean` | `true` | 是否显示头部工具栏 |
+| `showSelection` | `Boolean` | `false` | 是否显示多选列 |
+| `showIndex` | `Boolean` | `false` | 是否显示序号列 |
+| `indexWidth` | `String \| Number` | `60` | 序号列宽度 |
+| `indexAlign` | `String` | `''` | 序号列单元格对齐方式，支持 `left / center / right` |
+| `indexHeaderAlign` | `String` | `''` | 序号列表头对齐方式；未设置时回退 `indexAlign` |
+| `border` | `Boolean` | `true` | 边框 |
+| `stripe` | `Boolean` | `false` | 斑马纹 |
+| `height` | `String \| Number` | `undefined` | 固定高度 |
+| `maxHeight` | `String \| Number` | `undefined` | 最大高度 |
+| `autoHeight` | `Boolean` | `true` | 未指定高度时自动填充 |
+| `rowKey` | `String \| Function` | `undefined` | 行唯一键 |
+| `defaultExpandAll` | `Boolean` | `false` | 树表默认展开 |
+| `highlightCurrentRow` | `Boolean` | `false` | 高亮当前行 |
+| `loading` | `Boolean` | `false` | 加载状态 |
+| `showPagination` | `Boolean` | `true` | 是否显示分页 |
+| `total` | `Number` | `0` | 总数 |
+| `currentPage` | `Number \| null` | `null` | 受控页码 |
+| `pageSize` | `Number \| null` | `null` | 受控页大小 |
+| `pageSizes` | `Array` | `[10,20,50,100]` | 条数选项 |
+| `paginationLayout` | `String` | `'total, sizes, prev, pager, next, jumper'` | 分页布局 |
+| `pageNumberKey` | `String` | `'currentPage'` | 分页对象页码键名 |
+| `pageSizeKey` | `String` | `'pageSize'` | 分页对象条数键名 |
+| `pageTotalKey` | `String` | `'total'` | 分页对象总数字段 |
+| `slotRenderers` | `Object` | `{}` | 外部插槽渲染器 |
+
+### 5.2 事件
+
+| 事件 | 参数 |
+|---|---|
+| `add` | - |
+| `selection-change` | `selection` |
+| `sort-change` | `sort` |
+| `row-click` | `row, column, event` |
+| `size-change` | `size` |
+| `current-change` | `page` |
+| `link-click` | `row, column` |
+| `update:currentPage` | `page` |
+| `update:pageSize` | `size` |
+
+### 5.3 透传能力
+
+- `$attrs` 会透传给内部 `el-table`（Vue 3 中 `$listeners` 已合并到 `$attrs`，事件会以 `onEventName` 的格式存在于 `$attrs` 中）
+- 因此可直接继续传 `default-sort`、`row-class-name`、`cell-class-name` 等原生能力
+
+### 5.4 实例方法
+
+分为三类：
+
+- 选择相关：`getSelectionRows`、`getSelectionKeys`、`setSelectionRows`、`setSelectionKeys`、`clearSelection`、`toggleRowSelection`、`toggleAllSelection`、`selectAll`、`clearAllSelection`、`isRowSelected`、`isKeySelected`
+- 表格控制：`clearSort`、`clearFilter`、`doLayout`、`sort`
+- 分页控制：`resetPage`、`setPage`、`setPageSize`、`getPagination`、`setPagination`
+
+### 5.5 真实限制
+
+- `setPagination(pagination)` 只读取 `pagination.currentPage` 和 `pagination.pageSize`
+- 它不会识别自定义键名 `pageNumberKey / pageSizeKey`
+- 若使用 `header-actions` 插槽，默认新增按钮会隐藏
+
+## 6. 列配置 `columns[]`
+
+`TableColumn.js` 会递归渲染列，因此支持普通列、分组列、操作列、自定义渲染列。
+
+### 6.1 可直接透传的原生列属性
+
+`el-table-column` 的常规字段都可以直接写，例如：
+
+- `prop`
+- `label`
+- `width`
+- `minWidth`
+- `sortable`
+- `fixed`
+- `align`
+
+### 6.2 扩展字段
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `children` | `Array<Column>` | 子列 |
+| `type` | `String` | `action` / `tag` / `image` / `link` |
+| `slot` | `String` | 单元格插槽名 |
+| `headerSlot` | `String` | 表头插槽名 |
+| `buttons` | `Array` | `action` 列按钮列表 |
+| `enum` | `Array` | 枚举映射 |
+| `options` | `Array` | 同样可用于 tag 枚举映射 |
+| `formatter` | `Function` | 自定义显示函数 |
+| `tagType` | `String \| Function` | tag 类型 |
+| `tagSize` | `String` | tag 大小 |
+| `imageWidth` | `String \| Number` | 图片宽度 |
+| `imageHeight` | `String \| Number` | 图片高度 |
+| `linkText` | `String` | link 文案 |
+
+### 6.3 `action` 列按钮配置
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `label` | `String` | 按钮文本 |
+| `type` | `String` | 按钮类型 |
+| `icon` | `Component \| String` | 图标（Element Plus 推荐传入组件对象，如 `import { Edit } from '@element-plus/icons-vue'`） |
+| `size` | `String` | 尺寸 |
+| `link` | `Boolean` | 为真时渲染成 `text` 风格 |
+| `show` | `Boolean \| Function` | 是否显示 |
+| `disabled` | `Boolean \| Function` | 是否禁用 |
+| `handler` | `Function` | 点击回调 |
+| `slot` | `String` | 自定义按钮渲染器名称 |
+
+### 6.4 当前实现细节
+
+- `show(row)` 和 `disabled(row)` 当前只接收 `row`，不要假设一定有 `index`
+- `handler(row, index)` 会收到行数据与行序号
+- `button.slot` 对应的渲染器会收到 `{ row, column, button, $index }`
+- `button.style` 当前实现不会被渲染到按钮上，生成代码时不要依赖它
+
+### 6.5 常用列示例
+
+```js
+const columns = [
+  { prop: 'name', label: '名称', minWidth: 160 },
+  {
+    prop: 'status',
+    label: '状态',
+    type: 'tag',
+    options: [
+      { label: '启用', value: 1 },
+      { label: '禁用', value: 0 },
+    ],
+    tagType: (row) => (row.status === 1 ? 'success' : 'info'),
+  },
+  {
+    prop: 'avatar',
+    label: '头像',
+    type: 'image',
+    width: 90,
+    imageWidth: 40,
+    imageHeight: 40,
+  },
+  {
+    prop: 'title',
+    label: '标题',
+    type: 'link',
+    minWidth: 180,
+    linkText: '查看详情',
+  },
+  {
+    prop: 'customValue',
+    label: '自定义',
+    slot: 'custom-cell',
+  },
+  {
+    type: 'action',
+    label: '操作',
+    width: 180,
+    fixed: 'right',
+    buttons: [
+      {
+        label: '编辑',
+        link: true,
+        handler: (row) => handleEdit(row),
+      },
+      {
+        label: '删除',
+        link: true,
+        show: (row) => row.status !== -1,
+        handler: (row) => handleDelete(row),
+      },
+    ],
+  },
+  {
+    label: '分组信息',
+    children: [
+      { prop: 'groupName', label: '组名', width: 120 },
+      { prop: 'groupLeader', label: '组长', width: 120 },
+    ],
+  },
+]
+```
+
+## 7. 插槽与 `slotRenderers`
+
+### 7.1 推荐优先级
+
+优先使用普通 Vue 具名插槽；只有在需要把渲染函数直接写进配置对象时，才使用 `slotRenderers`。
+
+### 7.2 支持的插槽名
+
+| 插槽名 | 位置 | scope |
+|---|---|---|
+| `header-left` | 表格头部左侧 | `{ tableData }` |
+| `header-actions` | 表格头部右侧 | `{ tableData }` |
+| `empty` | 空状态 | `{ tableData }` |
+| `actions-after-reset` | 搜索区重置按钮后 | `{ formData, handleSearch, handleReset, isCollapsed }` |
+| 搜索项 slot | `NsSearch` | `{ formData, item }` |
+| 列 `slot` | `NsTable` | `{ row, column, $index }` |
+| 列 `headerSlot` | `NsTable` | Element 表头 scope |
+| `button.slot` | `action` 按钮 | `{ row, column, button, $index }` |
+
+### 7.3 `slotRenderers` 的真实签名
+
+当前实现不是 `(type, context) => VNode`，而是直接：
+
+```js
+(scope) => VNode
+```
+
+也就是说，渲染函数直接收到 scope 对象。
+
+```js
+import { h } from 'vue'
+import { ElTag } from 'element-plus'
+
+const slotRenderers = {
+  statusTag: ({ row }) => h(ElTag, { type: row.status === 1 ? 'success' : 'info' }, () => row.status === 1 ? '启用' : '禁用'),
+}
+```
+
+## 8. 跨页选择
+
+如果 `NsTableContainer` 配置了 `tableProps.rowKey`，容器会自动维护一份跨页选中 key 集合。
+
+### 8.1 必要条件
+
+- 必须设置 `tableProps.rowKey`
+- `rowKey` 可以是字符串字段名，也可以是函数
+
+### 8.2 容器会帮你做什么
+
+- 翻页后自动把当前页里已选中的行重新勾上
+- `getSelectionKeys()` 返回跨页累计 key
+- `getSelectionRows()` 返回当前已缓存的选中行对象
+
+### 8.3 AI 生成代码约束
+
+- 若要稳定使用 `getSelectionKeys / setSelectionKeys / isKeySelected`，一定提供 `rowKey`
+- 若业务需要跨页全量批量操作，建议以 key 集合为主，不要只依赖当前页 selection 数组
+
+## 9. Demo 应覆盖的能力
+
+AI 生成页面时，建议至少覆盖下列功能点：
+
+| 模块 | 建议能力 |
+|---|---|
+| 搜索区 | `ElInput`、`ElSelect`、`slot` 项、默认值、折叠展开 |
+| 表格列 | 普通列、分组列、tag、image、link、slot、headerSlot、action |
+| 交互 | `search`、`reset`、`add`、`selection-change`、`link-click`（其它分页 / 排序事件可不再单独接） |
+| 选择 | `rowKey`、跨页选择、批量操作 |
+| 扩展 | `actions-after-reset`、`header-actions`、`empty` |
+
+## 10. AI 生成代码规则
+
+- 优先使用 `NsTableContainer`
+- 数据加载统一通过监听 `@search` 事件完成；事件参数已合并 搜索值 + 分页 + 排序，可直接发给后端
+- 不要再向 `NsTableContainer` 传 `:load-data` 属性，组件无此 prop
+- 默认 `useDefaultPage=true` 模式下，不需要绑定 `:current-page.sync` / `:page-size.sync`，也不需要单独监听 `@sort-change / @size-change / @current-change / @page-change`
+- 列配置只写当前实现支持的字段
+- `slotRenderers` 写成 `(scope) => VNode`
+- 动作按钮显隐逻辑用 `show(row)`，不要依赖第二个参数
+- 如需跨页勾选，必须配置 `tableProps.rowKey`
+- 若用自定义 `header-actions`，不要再依赖默认新增按钮
+- 如果使用 `setPagination()`，传入对象必须是 `{ currentPage, pageSize }`
+- 需要服务端排序时，`columns[].sortable` 应写为 `'custom'`，`@search` 事件参数中的 `sort.prop / sort.order` 即为后端入参
+
+## 11. 推荐 Prompt
+
+```text
+请生成 Vue2.7 + script setup 的 NsTableContainer 页面，要求：
+1) searchItems 覆盖 ElInput、ElSelect、ElDatePicker、slot 项、defaultValue；
+2) columns 覆盖普通文本列、children 分组列、image、link、tag、自定义 slot、headerSlot、action；
+3) 仅监听 search、reset、add、selection-change、link-click 这五个事件即可；
+4) 数据加载只通过 @search 事件触发，事件参数中含搜索值、分页（pageNumberKey / pageSizeKey）以及 sort 对象；
+5) 提供 rowKey，并演示 getSelectionKeys、setSelectionKeys、isKeySelected；
+6) 提供 actions-after-reset、header-actions、empty 插槽示例；
+7) 如使用 slotRenderers，按当前项目的 (scope) => VNode 签名实现；
+8) 不使用 TS，不虚构不存在的 props 或方法（例如不要使用已不存在的 :load-data，不要在 useDefaultPage=true 模式下绑定 currentPage.sync / pageSize.sync）。
+```
+
+## 12. 标准模板
+
+```vue
+<template>
+  <NsTableContainer
+    ref="tableRef"
+    page-number-key="pageNo"
+    page-size-key="pageSize"
+    page-total-key="totalCount"
+    :search-items="searchItems"
+    :table-data="tableData"
+    :columns="columns"
+    :total="total"
+    :table-props="{
+      rowKey: 'id',
+      showSelection: true,
+      showIndex: true,
+      indexWidth: 72,
+      indexAlign: 'center',
+      border: true,
+      stripe: true,
+      paginationLayout: 'total, sizes, prev, pager, next',
+    }"
+    @search="fetchData"
+    @reset="onReset"
+    @add="onAdd"
+    @selection-change="onSelectionChange"
+    @link-click="onLinkClick"
+  >
+    <template v-slot:actions-after-reset="{ formData, handleSearch }">
+      <el-button type="text" @click="() => { formData.status = 1; handleSearch() }">仅看启用</el-button>
+    </template>
+
+    <template v-slot:header-actions>
+      <el-button type="primary" @click="onAdd">新增</el-button>
+      <el-button :disabled="!selectedIds.length" @click="batchDelete">批量删除</el-button>
+    </template>
+
+    <template v-slot:status="{ row }">
+      <el-tag :type="row.status === 1 ? 'success' : 'info'">
+        {{ row.status === 1 ? '启用' : '禁用' }}
+      </el-tag>
+    </template>
+
+    <template v-slot:empty>
+      <el-empty description="暂无数据" />
+    </template>
+  </NsTableContainer>
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const tableRef = ref(null)
+const tableData = ref([])
+const total = ref(0)
+const selectedIds = ref([])
+
+const searchItems = ref([
+  {
+    prop: 'keyword',
+    label: '关键字',
+    component: 'ElInput',
+    attrs: { clearable: true, placeholder: '请输入关键字' },
+  },
+  {
+    prop: 'status',
+    label: '状态',
+    component: 'ElSelect',
+    attrs: { clearable: true },
+    children: [
+      { label: '启用', value: 1 },
+      { label: '禁用', value: 0 },
+    ],
+  },
+])
+
+const columns = ref([
+  { prop: 'name', label: '名称', minWidth: 160, type: 'link' },
+  { prop: 'code', label: '编码', width: 120 },
+  { prop: 'status', label: '状态', width: 100, slot: 'status' },
+  { prop: 'createTime', label: '创建时间', width: 180, sortable: 'custom' },
+  {
+    type: 'action',
+    label: '操作',
+    width: 160,
+    fixed: 'right',
+    buttons: [
+      {
+        label: '编辑',
+        type: 'text',
+        handler: (row) => console.log('编辑', row),
+      },
+      {
+        label: '删除',
+        type: 'text',
+        handler: (row) => console.log('删除', row),
+      },
+    ],
+  },
+])
+
+// @search 事件参数 query 已包含搜索表单值 + 分页参数 + 排序信息
+const fetchData = async (query) => {
+  console.log('请求体：', query)
+
+  // 真实场景：将 query 直接发给后端
+  // const res = await api.list(query)
+  // tableData.value = res.data
+  // total.value = res.totalCount
+
+  tableData.value = [
+    { id: 1, name: '项目一', code: 'P001', status: 1, createTime: '2026-01-01' },
+    { id: 2, name: '项目二', code: 'P002', status: 0, createTime: '2026-01-02' },
+  ]
+  total.value = 2
+}
+
+const onReset = () => {
+  console.log('重置完成')
+}
+
+const onAdd = () => {
+  console.log('新增')
+}
+
+const onSelectionChange = (selection) => {
+  selectedIds.value = selection.map((item) => item.id)
+}
+
+const onLinkClick = (row) => {
+  console.log('查看详情', row)
+}
+
+const batchDelete = () => {
+  console.log('批量删除', selectedIds.value)
+}
+
+onMounted(() => {
+  tableRef.value?.initSearchAndLoad()
+})
+</script>
+
+<style scoped>
+.table-demo /deep/ .page-table__pagination {
+  justify-content: center;
+}
+</style>
+```