# @bhplugin/vue3-datatable 中文文档

规范地址：https://npmcn.com/package/%40bhplugin/vue3-datatable/

版本：3\.0\.0
npm 元数据更新时间：2026-04-16T07:08:52.090Z
中文译文更新时间：2026-11-08T01:19:43.066Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bhplugin/vue3-datatable
原文对照：https://npmcn.com/package/%40bhplugin/vue3-datatable/?lang=original
项目主页：https://github.com/bhaveshpatel200/vue3-datatable#readme
源码仓库：https://github.com/bhaveshpatel200/vue3-datatable

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：128 kB，25 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：vue \>=3\.0\.0
- 首次发布：2022-11-12T16:56:23.018Z
- 最新版本发布：2026-04-16T07:08:51.963Z
- 近 30 天下载量：16619（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：33（近 12 个月 1 个）

## 中文简介

Vue3 数据表 - 完全自定义并易于使用数据表库

## 安装

```sh
npm install @bhplugin/vue3-datatable
```

也可以使用：`pnpm add @bhplugin/vue3-datatable`、`yarn add @bhplugin/vue3-datatable`、`bun add @bhplugin/vue3-datatable`

## README

# @bhplugin/vue3-数据表

零依赖 Vue 3 数据表组件,包含客户端/服务器侧页,排序,过滤,行选择,以及自定义单元格渲染等功能.

## 示例

[文档演示文稿( D)](https://vue3-datatable-document.vercel.app/)

## 安装

#### 国家预防机制

```bash
npm install @bhplugin/vue3-datatable --save
```

#### 雅伦

```bash
yarn add @bhplugin/vue3-datatable
```

## 使用量

```html
<template>
    <vue3-datatable :rows="rows" :columns="cols" :sortable="true" :columnFilter="true"> </vue3-datatable>
</template>

<script setup lang="ts">
    import { ref } from "vue";
    import Vue3Datatable from "@bhplugin/vue3-datatable";
    import type { IColumnDefinition } from "@bhplugin/vue3-datatable";
    import "@bhplugin/vue3-datatable/dist/style.css";

    const cols = ref<IColumnDefinition[]>([
        { field: "id", title: "ID", isUnique: true, type: "number", filter: false },
        { field: "name", title: "Name" },
        { field: "email", title: "Email" },
        { field: "age", title: "Age", type: "number" },
        { field: "dob", title: "Date of Birth", type: "date" },
        { field: "isActive", title: "Active", type: "bool" },
        { field: "address.city", title: "City" },
    ]);

    const rows = ref<Array<Record<string, unknown>>>([
        { id: 1, name: "John Doe", email: "john@example.com", age: 28, dob: "1997-05-15", isActive: true, address: { city: "New York" } },
        { id: 2, name: "Jane Smith", email: "jane@example.com", age: 34, dob: "1991-11-22", isActive: false, address: { city: "London" } },
        // ...
    ]);
</script>
```

## 道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| **栏** (必须) | `IColumnDefinition[]` | `[]` | 表格栏定义 |
| **行数** (必须) | `Record[]` | `[]` | 表格行数据 |
| **是服务器模式** | `boolean` | `false` | 启用服务器侧模式( 残疾客户端排序/ filter/ pgination) |
| **共计** | `number` | `0` | 总行数( 在服务器模式下需要) |
| **皮肤** | `string` | `"bh-table-striped bh-table-hover"` | 表皮类 : `bh-table-striped`, (中文(简体) ), `bh-table-hover`, (中文(简体) ), `bh-table-bordered`, (中文(简体) ), `bh-table-compact` |
| **装入** | `boolean` | `false` | 显示加载覆盖/ skeleton |
| **有检查框** | `boolean` | `false` | 显示行选择的复选框列 |
| **搜索** | `string` | `""` | 全局搜索字符串 |
| **页 次** | `number` | `1` | 当前页面( 基于 1 个) |
| **页面大小** | `number` | `10` | 每页行数 |
| **页面大小选项** | `number[]` | `[10, 20, 30, 50, 100]` | 页面大小下拉选项 |
| **显示页码** | `boolean` | `true` | 显示页面大小 |
| **行分类** | `string | Function` | `""` | 自定义行类(字符串或 `(row) => string`(中文(简体) ) |
| **单元格分类** | `string | Function` | `""` | 自定义单元格类(字符串或 `(row) => string`(中文(简体) ) |
| **可排序** | `boolean` | `false` | 启用列排序 |
| **排序颜色** | `string` | `""` | 初始排序列字段 |
| **排序方向** | `'asc' | 'desc'` | `"asc"` | 初始排序方向 |
| **分栏** | `boolean` | `false` | 启用每栏过滤输入 |
| **列数** | `Record<string, string>` | `null` | 过滤条件的i18n标签(见下文) |
| **标记** | `boolean` | `true` | 显示页形 |
| **显示数字** | `boolean` | `true` | 显示页码按钮 |
| **显示数字** | `number` | `5` | 最大可见页码按钮 |
| **显示第一页** | `boolean` | `true` | 显示第一页按钮 |
| **显示最后页** | `boolean` | `true` | 显示最后一页按钮 |
| **页形信息** | `string` | `"Showing {0} to {1} of {2} entries"` | 插件信息模板( E)`{0}` =开始, `{1}` =结束, `{2}` =共计) |
| **无数据关联** | `string` | `"No data available"` | 空状态文本 |
| **骨架** | `number` | `10` | 装入时的骨架行数 |
| **粘结页眉** | `boolean` | `false` | 粘贴表头 |
| **高度** | `string` | `"500px"` | 可滚动高度( 仅限 `stickyHeader`(中文(简体) ) |
| **粘接第一相册** | `boolean` | `false` | 粘贴第一列 |
| **克隆页眉InFooter** | `boolean` | `false` | 克隆头为页脚行 |
| **选择RowOnClick** | `boolean` | `false` | 点击切换行选择 |

### 列缩放键

```ts
{
    no_filter: 'No filter',
    contain: 'Contain', not_contain: 'Not contain',
    equal: 'Equal', not_equal: 'Not equal',
    start_with: 'Starts with', end_with: 'Ends with',
    greater_than: 'Greater than', greater_than_equal: 'Greater than or equal',
    less_than: 'Less than', less_than_equal: 'Less than or equal',
    is_null: 'Is null', is_not_null: 'Not null',
    all: 'All', true: 'True', false: 'False'   // boolean column filter labels
}
```

## 栏定义

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| **是独一无二的** | `boolean` | `false` | 标记为唯一行标识符( 用于选择密钥) |
| **字段** | `string` | `""` | 数据字段路径( 支持点标记 : `address.city`(中文(简体) ) |
| **标题** | `string` | `""` | 列头文字 |
| **价值** | `string` | `""` | 初始过滤值 |
| **条件** | `IFilterCondition` | `""` | 默认过滤条件( E)`contain` 用于字符串, `equal` 数字/ 日期, 布尔为空) |
| **类型** | `string` | `"string"` | 列类型 : `string`, (中文(简体) ), `number`, (中文(简体) ), `date`, (中文(简体) ), `bool` |
| **宽度** | `string` | `""` | 列宽( 例如 ), `"200px"`(中文(简体) ) |
| **微风** | `string` | `""` | 最小列宽 |
| **最大宽度** | `string` | `""` | 最大列宽 |
| **隐藏** | `boolean` | `false` | 从渲染中隐藏列 |
| **过滤器** | `boolean` | `true` | 启用列过滤器 |
| **搜索** | `boolean` | `true` | 全局搜索中包含 |
| **排序** | `boolean` | `true` | 启用排序 |
| **(简体中文)** | `boolean` | `false` | 列包含原始 HTML |
| **单元格渲染器** | `Function` | \- 说吧 | 自定义单元格渲染器 : `(row) => '<strong>html</strong>'` (自动化) |
| **页眉分类** | `string` | `""` | 自定义信头单元格类 |
| **单元格分类** | `string` | `""` | 自定义细胞类 |

## 活动

| 活动 | 有效载荷 | 说明 |
| --- | --- | --- |
| **更改服务器** | `IServerChangeResponse` | 仅服务器模式——具有完整状态的聚合事件(页面、排序、搜索、过滤器、更改 类型) |
| **页面变化** | `number` | 用户点击了 pagination 按钮( 静默于程序重排) |
| **页面变更** | `number` | 页面大小下降已更改 |
| **排序变化** | `ISortChangeResponse` | 应用的列排序( 不重设页面) |
| **过滤变化** | `IColumnDefinition[]` | 列过滤值或条件已更改 |
| **搜索变化** | `string` | 全局搜索文件已更改 |
| **选择行** | `Record[]` | 行选择已更改( 只有用户交互) |
| **划线** | `Record` | 单行点击 |
| **线条 DBClick** | `Record` | 双击行 |
| **重设** | \- 说吧 | `reset()` 被调用——仅在重置时发生,所有其他被压制 |

### 活动规则

-   排序对 **没有** 重置页面
-   过滤/ 搜索/ 页面大小重排到第 1 页, 但只发布特定事件( 不) `pageChange`(中文(简体) )
-   `pageChange` 仅来自明确用户 pagination 点击的点火
-   重置期间,仅限 `reset` (+ 数) `changeServer` (在服务器模式中) 发出——所有其他事件被压制

## 方法

| 方法 | 说明 |
| --- | --- |
| **重设( c)** | 重置所有状态( 选择、 过滤、 搜索、 排序、 页面) |
| **获得FilteredRows ()** | 返回所有已过滤行 |
| **获取可视Rows ()** | 返回当前页面可见行 |
| **获取 ColumnFilters ()** | 以当前过滤状态返回列定义 |
| **获取选中的Rows ()** | 返回所有所选行 |
| **清除选中的Rows ()** | 取消所有行的选择 |
| **选择Row( 索引)** | 按索引选择行 |
| **未选择Row( 索引)** | 按索引删除行 |
| **是 RowSecret( 索引)** | 检查是否选中行 |

## 槽数

### 自定义单元格渲染( 按列字段命名)

```html
<vue3-datatable :rows="rows" :columns="cols">
    <template #name="{ value }">
        <strong>{{ value.name }}</strong>
    </template>
</vue3-datatable>
```

### 插孔箭头插槽

```html
<template #firstArrow> &laquo; </template>
<template #previousArrow> &lsaquo; </template>
<template #nextArrow> &rsaquo; </template>
<template #lastArrow> &raquo; </template>
```

### 状态空位

```html
<template #noData>
    <div>No records found.</div>
</template>
```

## 服务器模式示例

```html
<vue3-datatable
    :rows="rows"
    :columns="cols"
    :loading="loading"
    :totalRows="totalRows"
    :isServerMode="true"
    :pageSize="10"
    :sortable="true"
    :columnFilter="true"
    @page-change="onPageChange"
    @page-size-change="onPageSizeChange"
    @sort-change="onSortChange"
    @filter-change="onFilterChange"
    @search-change="onSearchChange"
/>
```

## 更改日志

[更改日志](https://vue3-datatable-document.vercel.app/changelog)

## 许可证

**@bhplugin/vue3-数据表** 是一个开源软件,根据该软件许可 [麻省理工学院许可证](http://opensource.org/licenses/MIT)。 。 。 .

## 我们的其他插件

### 角数据表 - [**@bhplugin/ng-数据表**](https://www.npmjs.com/package/@bhplugin/ng-datatable)

## 支助

[![Buy Me A Coffee](https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png)](https://www.buymeacoffee.com/bhplugin)

## 常见问题

### @bhplugin/vue3-datatable 是什么？

Vue3 数据表 - 完全自定义并易于使用数据表库

### 如何安装 @bhplugin/vue3-datatable？

在项目目录运行 npm install @bhplugin/vue3-datatable，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（\>=3\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bhplugin/vue3-datatable 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bhplugin/vue3-datatable 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bhplugin/vue3-datatable 可以商用吗？

@bhplugin/vue3-datatable 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bhplugin/vue3-datatable 的下载量有多少？

根据 npm 官方下载统计，@bhplugin/vue3-datatable 在 2026/10/08 – 2026/11/06 这 30 天内被下载 16,619 次，日均约 554 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bhplugin/vue3-datatable 还在维护吗？

最新版本 3\.0\.0 发布于 2026/04/16（6 个月前）；至今共发布 33 个版本，其中过去 12 个月发布了 1 个；首次发布于 2022/11/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。