# antdv-pro-table

**Repository Path**: TsMask/antdv-pro-table

## Basic Information

- **Project Name**: antdv-pro-table
- **Description**: 【Vue3】Ant Design Vue Pro Table 增强标题组件，保留 Table 原生 API，增加搜索/工具条特性。
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-15
- **Last Updated**: 2026-08-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Ant Design Vue Pro Table

Ant Design Vue Pro 表格组件，在原生 Table 之上提供查询表单、工具栏、列状态、数据请求与状态管理能力。

[![Vue Support](https://img.shields.io/badge/support-Vue3-green?style=flat)](./package.json)
[![NPM version](https://img.shields.io/npm/v/antdv-pro-table/latest?style=flat)](https://www.npmjs.com/package/antdv-pro-table)
[![NPM downloads](https://img.shields.io/npm/dm/antdv-pro-table.svg?style=flat)](https://www.npmjs.com/package/antdv-pro-table)
![License MIT](https://img.shields.io/badge/License-MIT-blue.svg)

[中文](./README.md) | [English](./README.en.md)

## 安装 Install

```bash
npm i antdv-pro-table
```

`antdv-pro-table` 需要在 Vue 3 与 Ant Design Vue 4 环境中使用：

```bash
npm i vue ant-design-vue @ant-design/icons-vue
```

## 功能特性 Features

| 组件 / 函数 | 说明 |
| --- | --- |
| ProTable | Pro 表格容器，内置查询区、工具栏、密度切换、刷新、列设置与高度填充 |
| ProColumns | 扩展表格展示列配置，支持 `valueType`、`valueEnum` 与自定义渲染 |
| ProColumnsSearch | 独立查询项配置，专门用于 `search.columns` |
| useProTableData | 数据层 Hook，管理请求、分页、排序、筛选、轮询、请求合批与过期响应丢弃 |
| useRowSelection | 行选择 Hook，支持跨页保留、禁用行过滤、批量选择与反选 |
| useExpandable | 行展开 Hook，支持跨页保留、手风琴模式、批量展开与收起 |
| 查询表单 | 支持常规查询、轻量筛选、响应式栅格、label 宽度与折叠配置 |
| 列状态 | 支持显示隐藏、固定、拖拽排序，可通过 localStorage / sessionStorage 持久化或受控同步 |
| 原生能力 | Ant Design Vue Table 属性、事件与插槽均可透传，降低接入成本 |

完整组件、Hook、类型、属性、事件与插槽说明见 [API.md](./API.md)。

## 简单使用 Simple Usage

首先引入 Ant Design Vue 与 `antdv-pro-table` 的样式：

```js
// main.[js|ts]
import { createApp } from 'vue';
import App from './App.vue';
import Antd from 'ant-design-vue';
import 'ant-design-vue/dist/reset.css';
import 'antdv-pro-table/dist/style.css';

const app = createApp(App);
app.use(Antd).mount('#app');
```

之后在页面中组合 `ProTable` 与 `useProTableData`：

```vue
<template>
  <ProTable
    row-key='id'
    :columns='columns'
    :data-source='dataSource'
    :loading='loading'
    :pagination='pagination'
    :search='{ columns: searchColumns, onSearch }'
    :toolbar='{ onReload: reload }'
    @change='onTableChange'
  >
    <template #toolBarRender>
      <a-button type='primary' @click='openCreate'>新建用户</a-button>
    </template>
  </ProTable>
</template>

<script setup lang='ts'>
import { h } from 'vue';
import {
  ProTable,
  useProTableData,
  type ProColumns,
  type ProColumnsSearch,
} from 'antdv-pro-table';

interface UserItem {
  id: number;
  name: string;
  status: number;
  createdAt: string;
}

const columns: ProColumns<UserItem>[] = [
  { title: '姓名', dataIndex: 'name', copyable: true },
  { title: '状态', dataIndex: 'status', valueType: 'select', valueEnum: STATUS_ENUM },
  {
    title: '创建时间',
    dataIndex: 'createdAt',
    valueType: 'dateTime',
    sorter: true,
  },
  {
    title: '操作',
    valueType: 'option',
    render: (_dom, record) => [
      h('a', { onClick: () => openEdit(record) }, '编辑'),
    ],
  },
];

const searchColumns: ProColumnsSearch[] = [
  { title: '姓名', dataIndex: 'name' },
  { title: '状态', dataIndex: 'status', valueType: 'select', valueEnum: STATUS_ENUM },
];

const {
  dataSource,
  loading,
  pagination,
  onSearch,
  onTableChange,
  reload,
} = useProTableData({
  request: (params, sort, filter) => queryUsers(params, sort, filter),
});
</script>
```

## 示例 Examples

- 演示测试：[playground](./playground/)
- 可视化配置：`/pro-table`
- 基础查询表格：`/table/basic`
- 查询表单与轻量筛选：`/table/search`
- 值类型展示：`/table/value-type`
- 列特性与列状态：`/table/column-features`、`/table/columns-state`
- 行选择与批量操作：`/table/selection`
- 轮询列表：`/table/list`

## 环境要求 Requirements

- Node.js `>= 22`
- Vue `>= 3.4`
- Ant Design Vue `>= 4.2`

## 持续维护 Continuous Maintenance

```bash
# 安装所需依赖
npm install

# 启动本地 playground
npm run dev

# 类型检查并打包生成 dist 目录与 .d.ts 文件
npm run build

# 预览生产构建
npm run preview
```