---
name: deppon-pro-table
description: >-
    使用 Vue 3 script setup、@deppon/deppon-template 的 ProTable 与 @deppon/deppon-ui
    生成或改写列表页（搜索、分页、工具栏、行操作、插槽列）。在用户需要数据表格、CRUD 列表、
    ProTable columns，或提到 ProTable、数据表格 时应用。
---

# deppon-pro-table：ProTable 列表（私有 npm）

## 依据来源（私有 npm）

-   **`deppon-npm-private-registry`**：外仓安装与文档位置。
-   **`@deppon/deppon-template`**：`ProTable` — README、`VITE_USAGE.md`、`USAGE.md`、`es/**/*.d.ts`。
-   **`@deppon/deppon-ui`**：表格区按钮、`ElTag` 等。
-   **`deppon-npm-skills`**：多级表头、展开行等见其它专项 skill。不默认读取 `deppon-npm` 的 `site/`。

## 与本仓库其它列表类 skill 的边界

- 若需要 **顶部独立一条内联 `ProForm` 做查询**、中间 `ProTable`、**底部或弹窗整块 `ProForm` 编辑实体**（三块分离），用 **`deppon-pro-page-query-table-form`**，而不是把本 skill 的「内置搜索」硬拆成两套 UI。
- 若要在表格 **单元格内** 编辑（`editable`、增删行等），用 **`deppon-pro-table-cell-editable`**，不是「整页查询+表+表单」skill。

## 必须遵守的栈与风格

-   `import { ProTable } from '@deppon/deppon-template'`。
-   `import { ElButton, ElMessage, ElTag, ... } from '@deppon/deppon-ui'`。
-   `script setup` + `ref`/`onMounted`/`watch` 与项目惯例一致。

## 模板骨架（ProTable 常见 props）

核心 props：

-   数据：` :data-source="tableData"`
-   列：` :columns="columns"`
-   分页：`:show-pagination="true"` + `:current-page` + `:page-size` + `:page-sizes` + `:total`
-   加载：`:loading="loading"`
-   搜索区（内置）：`:search-label-width`、`:search-cols`、`search-title`、`@search`、`@reset`、`@values-change`
-   行操作：`:show-operations="true"` + `#operations` / `#batchOperations`
-   事件：`@size-change`、`@current-change`、`@selection-change`

常用增强：

-   `stripe`、` :fixed-table="true"`、` :row-selection="rowSelection"`、` :draggable="true"`
-   ` :toolbar-options="{ reload, density, setting, fullScreen }"`
-   ` :empty-text` / ` :empty-image`

## columns 约定（ProTable）

与列表+搜索共用时，单列常见字段：

-   `prop`：数据字段名。
-   `label`：表头。
-   `width` / `minWidth` / `fixed` / `align`
-   `hideInSearch: false`：参与搜索（按需显式写出参与搜索的列）。
-   `valueType`：如 `textRange`（双框范围，以 **`ProTable` 文档/类型** 为准）。
-   `initialValue` / `initialValue: [...]`：搜索区初值。
-   `fieldProps`：搜索控件的 props（含 `placeholder`、`isClearInitialValue` 等）。
-   `rules`：搜索表单项校验。
-   `slots: { default: 'slotName' }`：表格体插槽；模板里写 `<template #slotName="{ row }">`。
-   `sorter: true` 或自定义 `(a,b)=>...`
-   `filters` + `filterMethod`：列头筛选（若当前版本列类型支持）。

操作列通常在列配置里留 `prop: 'action'`，并用 `#action` 插槽渲染按钮。

## 状态与数据流

-   `loading`、`currentPage`、`pageSize`、`total`、`tableData` 全用 `ref`。
-   分页：`handleSizeChange` 更新 `pageSize`，常把 `currentPage` 重置为 1；`handleCurrentChange` 更新页码。
-   查询：`handleSearch(values)` 里合并条件、`currentPage=1`、拉取列表。
-   重置：`handleReset` 调用表格暴露的重置或清空搜索表单（与 **`ProTable` 事件/方法** 对齐）。
-   远程列表：在 `fetchList` 里统一处理 `loading`、错误提示与 `total`。

## 插槽命名速查

-   `#tableTitle`：表头标题区。
-   `#paginationBefore`：分页条左侧（如「新建」）。
-   `#operations`：表格上方操作按钮行。
-   `#batchOperations="{ selectedRows, clearSelection }"`：批量操作。
-   列体：`#status`、`#action` 等与 `slots.default` 名称一致。

## 生成清单

-   [ ] 列 `prop` 与接口字段一致；`label` 中文业务名。
-   [ ] 需要搜索的列未误设 `hideInSearch: true`。
-   [ ] 分页与查询联动时重置到第一页。
-   [ ] 操作列固定宽度，避免挤压。