# edit-table

**Repository Path**: tjs/edit-table

## Basic Information

- **Project Name**: edit-table
- **Description**: 这是一个基于 Element Plus el-table 封装的轻量级可编辑表格组件，提供开箱即用的表格编辑能力。
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/tjs/edit-table
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-22
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EditTable

基于 Element Plus `el-table` 封装的轻量级可编辑表格组件，提供开箱即用的表格编辑能力。

## ✨ 功能特色

- 🎯 **便捷的编辑方式**：支持点击/双击/手动三种编辑触发模式
- 📦 **丰富的编辑组件**：内置支持 Input、Select、DatePicker、Switch、Checkbox 等多种编辑器
- ✅ **强大的校验功能**：支持同步/异步校验规则，支持自定义校验函数
- 🔄 **智能状态管理**：自动追踪数据变更，支持回滚、获取变更记录
- 🎨 **灵活的插槽机制**：支持自定义单元格显示和编辑组件

## 📦 安装

```bash
# 使用 pnpm
pnpm add @tjs524/edit-table

# 使用 npm
npm install @tjs524/edit-table

# 使用 yarn
yarn add @tjs524/edit-table
```

## 🔧 注册

### 全局注册

```typescript
import { createApp } from 'vue'
import App from './App.vue'
import EditTable from '@tjs524/edit-table'

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

### 局部注册

```vue
<script setup lang="ts">
import { EditTable, EditColumn } from '@tjs524/edit-table'
</script>
```

## 📖 基础用法

### 使用 EditColumn 插槽配置

```vue
<template>
  <EditTable :data="tableData">
    <EditColumn type="checkbox" />
    <EditColumn field="name" title="姓名" :edit-render="{ name: 'elInput' }" />
    <EditColumn field="age" title="年龄" :edit-render="{ name: 'elInputNumber' }" />
    <EditColumn field="status" title="状态" :edit-render="{ name: 'elSelect', options: statusOptions }" />
  </EditTable>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const tableData = ref([
  { id: 1, name: '张三', age: 28, status: 'active' },
  { id: 2, name: '李四', age: 32, status: 'inactive' },
])

const statusOptions = [
  { label: '活跃', value: 'active' },
  { label: '禁用', value: 'inactive' },
]
</script>
```

## 🎯 EditTable Props

| 参数              | 类型                                  | 默认值          | 说明       |
| --------------- | ----------------------------------- | ------------ | -------- |
| data            | `TableRow[]`                        | `[]`         | 表格数据     |
| editable        | `boolean`                           | `true`       | 是否可编辑    |
| editTrigger     | `'click' \| 'dblclick' \| 'manual'` | `'click'`    | 编辑触发方式   |
| editTriggerMode | `'cell' \| 'row'`                   | `'cell'`     | 编辑触发范围   |
| showIndex       | `boolean`                           | `false`      | 是否显示序号列  |
| selectMode      | `'single' \| 'multiple'`            | `'multiple'` | 选择模式     |
| rowKey          | `string`                            | `-`          | 行唯一标识字段名 |
| maxHeight       | `number \| string`                  | `-`          | 最大显示高度   |
| stripe          | `boolean`                           | `false`      | 斑马纹      |
| border          | `boolean \| 'outer' \| 'inner'`     | `false`      | 边框       |
| rowClassName    | `string \| Function`                | `-`          | 行类名      |
| onError         | `Function`                          | `-`          | 全局错误回调   |

## 🎯 EditColumn Props

| 参数         | 类型                              | 默认值     | 说明          |
| ---------- | ------------------------------- | ------- | ----------- |
| type       | `'checkbox' \| 'seq'`           | `-`     | 列类型         |
| field      | `string`                        | `-`     | 列标识（对应数据字段） |
| title      | `string`                        | `-`     | 列标题         |
| width      | `number \| string`              | `-`     | 列宽度         |
| minWidth   | `number \| string`              | `-`     | 最小列宽        |
| align      | `'left' \| 'center' \| 'right'` | `-`     | 对齐方式        |
| editRender | `EditRenderConfig`              | `-`     | 编辑渲染配置      |
| editRules  | `ValidationRule[]`              | `-`     | 校验规则        |
| sortable   | `boolean`                       | `false` | 是否可排序       |
| filterable | `boolean`                       | `false` | 是否可筛选       |
| fixed      | `'left' \| 'right' \| boolean`  | `-`     | 固定列         |

## 🎨 EditRenderConfig 配置

编辑渲染配置用于指定单元格使用的编辑器类型及相关参数。

| 属性      | 类型                                | 说明                    |
| ------- | --------------------------------- | --------------------- |
| name    | `EditorName`                      | 编辑器名称                 |
| attrs   | `Record<string, any>`             | 传递给编辑器的属性             |
| options | `{ label: string; value: any }[]` | 下拉选项（select/radio 类型） |

### 支持的编辑器类型

| name 值          | 对应组件                | 说明    |
| --------------- | ------------------- | ----- |
| `elInput`       | `ElInput`           | 文本输入框 |
| `elInputNumber` | `ElInputNumber`     | 数字输入框 |
| `elSelect`      | `ElSelect`          | 下拉选择器 |
| `elDatePicker`  | `ElDatePicker`      | 日期选择器 |
| `elTimePicker`  | `ElTimePicker`      | 时间选择器 |
| `elSwitch`      | `ElSwitch`          | 开关    |
| `elCheckbox`    | `ElCheckbox`        | 复选框   |
| `elRadio`       | `ElRadioGroup`      | 单选框   |
| `elTextarea`    | `ElInput(textarea)` | 文本域   |

### EditRenderConfig 示例

```typescript
// 文本输入
{ name: 'elInput', attrs: { placeholder: '请输入' } }

// 数字输入
{ name: 'elInputNumber', attrs: { min: 0, max: 100 } }

// 下拉选择
{ 
  name: 'elSelect', 
  options: [
    { label: '选项1', value: '1' },
    { label: '选项2', value: '2' }
  ]
}

// 日期选择
{ name: 'elDatePicker', attrs: { type: 'date' } }
```

## ✅ ValidationRule 校验规则

| 属性             | 类型                                         | 说明        |
| -------------- | ------------------------------------------ | --------- |
| required       | `boolean`                                  | 是否必填      |
| minLength      | `number`                                   | 最小长度      |
| maxLength      | `number`                                   | 最大长度      |
| min            | `number`                                   | 最小值（数字类型） |
| max            | `number`                                   | 最大值（数字类型） |
| pattern        | `RegExp \| string`                         | 正则表达式     |
| validator      | `Function`                                 | 自定义同步校验函数 |
| asyncValidator | `Function`                                 | 自定义异步校验函数 |
| trigger        | `'blur' \| 'change' \| ['blur', 'change']` | 校验触发时机    |
| message        | `string`                                   | 校验失败提示信息  |

### 校验规则示例

```typescript
const editRules = [
  { required: true, message: '必填项', trigger: 'blur' },
  { minLength: 2, maxLength: 20, message: '长度2-20字符', trigger: 'blur' },
  { pattern: /^[a-zA-Z]+$/, message: '只能输入字母', trigger: 'change' },
  { 
    validator: (value, row) => {
      if (value < 18) return '年龄必须大于18'
      return true
    },
    trigger: 'blur'
  },
  {
    asyncValidator: async (value) => {
      const exists = await checkExists(value)
      return exists ? '已存在' : true
    },
    trigger: 'blur'
  }
]
```

## 📡 事件

| 事件名               | 说明             | 参数                   |
| ----------------- | -------------- | -------------------- |
| edit-change       | 单元格值变更时触发      | `EditChangeParams`   |
| cell-click        | 单元格点击时触发       | `CellClickParams`    |
| cell-dblclick     | 单元格双击时触发       | `CellDblClickParams` |
| edit-start        | 开始编辑时触发        | `EditStartParams`    |
| edit-end          | 编辑结束时触发        | `EditEndParams`      |
| row-insert        | 插入行时触发         | `RowInsertParams`    |
| before-row-insert | 插入行前触发（可拦截）    | `RowInsertParams`    |
| row-remove        | 删除行时触发         | `RowRemoveParams`    |
| row-delete        | 删除行时触发（包含原始数据） | `RowDeleteParams`    |
| selection-change  | 选中状态变更时触发      | `TableRow[]`         |
| sort-change       | 排序变更时触发        | `SortChangeParams`   |

## 🔌 方法（Ref API）

通过 `ref` 调用组件方法：

```vue
<template>
  <EditTable ref="tableRef" :data="tableData">
    <!-- ... -->
  </EditTable>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { EditTableInstance } from '@tjs524/edit-table'

const tableRef = ref<EditTableInstance>()

// 调用方法
tableRef.value?.validateAll()
tableRef.value?.insertRow({ name: '新用户' })
</script>
```

### 方法列表

| 方法名               | 说明        | 参数                                | 返回值                              |
| ----------------- | --------- | --------------------------------- | -------------------------------- |
| getData           | 获取当前数据    | -                                 | `TableRow[]`                     |
| setData           | 设置数据      | `data: TableRow[]`                | `void`                           |
| getEditRecords    | 获取所有变更记录  | -                                 | `EditRecordResult`               |
| getNewRecords     | 获取新增记录    | -                                 | `TableRow[]`                     |
| getUpdateRecords  | 获取更新记录    | -                                 | `TableRow[]`                     |
| getRemoveRecords  | 获取删除记录    | -                                 | `TableRow[]`                     |
| getRemovedRows    | 获取已删除的原始行 | -                                 | `TableRow[]`                     |
| validateAll       | 执行全量校验    | -                                 | `Promise<ValidationErrorResult>` |
| clearEdit         | 清除编辑状态    | -                                 | `void`                           |
| revertEdit        | 回滚所有编辑    | -                                 | `void`                           |
| insertRow         | 插入行       | `row: TableRow, index?: number`   | `void`                           |
| removeRow         | 删除行       | `index: number \| number[]`       | `void`                           |
| restoreRow        | 恢复已删除的行   | `rows: TableRow \| TableRow[]`     | `void`                           |
| getSelectedRows   | 获取选中行     | -                                 | `TableRow[]`                     |
| scrollToRow       | 滚动到指定行    | `index: number`                   | `void`                           |
| scrollToColumn    | 滚动到指定列    | `prop: string`                    | `void`                           |
| startCellEdit     | 手动开启编辑    | `rowIndex: number, prop: string`  | `void`                           |
| endCellEdit       | 手动关闭编辑    | `rowIndex: number, prop: string`  | `void`                           |
| endAllEdit        | 关闭所有编辑    | -                                 | `void`                           |
| getCellValidation | 获取单元格校验状态 | `rowIndex: number, field: string` | `{ valid, errors }`              |

## 🧩 插槽

| 插槽名     | 说明                | 作用域参数                                           |
| ------- | ----------------- | ----------------------------------------------- |
| default | 放置 EditColumn 子组件 | -                                               |
| cell    | 自定义单元格显示内容        | `row, column, cellValue, rowIndex, columnIndex` |
| edit    | 自定义编辑组件           | `row, column, rowIndex, columnIndex`            |
| header  | 自定义列标题            | `column`                                        |
| empty   | 自定义空数据展示          | -                                               |

### 插槽使用示例

```vue
<template>
  <EditTable :data="tableData">
    <EditColumn field="name" title="姓名" :edit-render="{ name: 'elInput' }">
      <template #cell="{ cellValue }">
        <span class="custom-cell">{{ cellValue }}</span>
      </template>
    </EditColumn>

    <EditColumn field="action" title="操作">
      <template #edit>
        <button @click="handleAction">自定义操作</button>
      </template>
    </EditColumn>
  </EditTable>
</template>
```

## 🔄 变更追踪

组件内置变更追踪功能，可方便地获取新增、更新、删除的记录：

```typescript
const records = tableRef.value?.getEditRecords()

// 所有变更记录
console.log(records.editRecords)

// 新增记录
console.log(records.newRecords)

// 更新记录
console.log(records.updateRecords)

// 删除记录
console.log(records.removeRecords)
```

## ✅ 数据校验

```typescript
// 全量校验
const result = await tableRef.value?.validateAll()
if (result.valid) {
  // 校验通过，提交数据
  submitData()
} else {
  // 显示错误信息
  console.log(result.errors)
}

// 获取单个单元格校验状态
const cellValidation = tableRef.value?.getCellValidation(rowIndex, 'fieldName')
if (!cellValidation.valid) {
  console.log(cellValidation.errors)
}
```

## 🔧 完整 CRUD 示例

```vue
<template>
  <div>
    <div class="toolbar">
      <el-button @click="handleAdd">新增</el-button>
      <el-button @click="handleDelete" type="danger">删除选中</el-button>
      <el-button @click="handleSubmit" type="primary">提交</el-button>
      <el-button @click="handleRevert">回滚</el-button>
    </div>

    <EditTable ref="tableRef" :data="tableData" :show-index="true">
      <EditColumn type="checkbox" />
      <EditColumn field="name" title="姓名" :edit-render="{ name: 'elInput' }" :edit-rules="nameRules" />
      <EditColumn field="age" title="年龄" :edit-render="{ name: 'elInputNumber', attrs: { min: 0 } }" />
      <EditColumn field="email" title="邮箱" :edit-render="{ name: 'elInput' }" :edit-rules="emailRules" />
      <EditColumn field="status" title="状态" :edit-render="{ name: 'elSelect', options: statusOptions }" />
    </EditTable>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { EditTable, EditColumn } from '@tjs524/edit-table'
import type { EditTableInstance, TableRow } from '@tjs524/edit-table'

const tableRef = ref<EditTableInstance>()

const tableData = ref<TableRow[]>([
  { id: 1, name: '张三', age: 28, email: 'zhangsan@example.com', status: 'active' },
  { id: 2, name: '李四', age: 32, email: 'lisi@example.com', status: 'inactive' },
])

const statusOptions = [
  { label: '活跃', value: 'active' },
  { label: '禁用', value: 'inactive' },
]

const nameRules = [
  { required: true, message: '请输入姓名', trigger: 'blur' },
  { minLength: 2, maxLength: 20, message: '姓名长度2-20字符', trigger: 'blur' },
]

const emailRules = [
  { 
    pattern: /^[\w.-]+@[\w.-]+\.\w+$/, 
    message: '请输入有效邮箱', 
    trigger: 'blur' 
  },
]

const handleAdd = () => {
  tableRef.value?.insertRow({
    id: Date.now(),
    name: '',
    age: 0,
    email: '',
    status: 'active',
  })
}

const handleDelete = () => {
  const selected = tableRef.value?.getSelectedRows() || []
  if (selected.length === 0) {
    ElMessage.warning('请选择要删除的行')
    return
  }
  const indexes = selected.map(row => tableData.value.findIndex(r => r.id === row.id))
  tableRef.value?.removeRow(indexes)
}

const handleSubmit = async () => {
  const result = await tableRef.value?.validateAll()
  if (!result?.valid) {
    ElMessage.error('校验失败，请检查输入')
    return
  }

  const records = tableRef.value?.getEditRecords()
  console.log('新增:', records?.newRecords)
  console.log('更新:', records?.updateRecords)
  console.log('删除:', records?.removeRecords)

  // 提交到后端
  // await api.submit(records)

  ElMessage.success('提交成功')
}

const handleRevert = () => {
  tableRef.value?.revertEdit()
  ElMessage.info('已回滚所有修改')
}
</script>
```

## 📝 类型导出

组件导出以下 TypeScript 类型，可用于类型声明：

```typescript
import type {
  TableRow,
  TableColumn,
  EditTableProps,
  EditTableInstance,
  EditRenderConfig,
  ValidationRule,
  EditorName,
  EditTrigger,
  EditRecord,
  EditRecordResult,
  ValidationError,
} from '@tjs524/edit-table'
```

## 🚀 npm 发布流程

项目使用 Changesets 管理版本和发布记录。

### 记录变更

开发完成后先执行：

```bash
pnpm changeset
```

按提示选择版本类型并填写变更说明。

### 更新版本与 Changelog

发布前执行：

```bash
pnpm version:npm
```

该命令会根据 `.changeset` 记录更新 `package.json` 版本号，并生成或更新 `CHANGELOG.md`。

### 验证发布

正式发布前可先执行 dry-run，该命令使用 `pnpm publish --dry-run` 预检打包和发布配置，不会上传 npm：

```bash
pnpm release:npm:dry
```

### 正式发布

确认版本和构建产物无误后执行：

```bash
pnpm release:npm
```

该命令会依次执行代码检查、单元测试、生产构建，并由 `publishConfig.registry` 指定通过 `https://registry.npmjs.org/` 发布到官方 npm。

## 📄 许可证

Apache License 2.0

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📧 联系方式

如有问题或建议，欢迎提交 Issue 或发送邮件。