MagicTable 高级表格

一个功能强大、高度可配置的企业级表格组件，内置排序、筛选、分页、编辑、导入/导出等高级功能。

何时使用

• 需要展示复杂的数据集合。
• 需要对数据进行客户端的排序、筛选和分页。
• 需要在表格内直接进行数据编辑。
• 需要支持行选择、批量操作、数据导入/导出。
• 需要在桌面端和移动端都有良好的展示效果。

代码演示

基础用法

最简单的用法，仅需传入 columns (列定义) 和 v-model (数据)。

<template>
  <MagicTable
    :columns="columns"
    v-model="data"
    title="基础表格"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import MagicTable, { type Column } from './components/MagicTable.vue';

const columns = ref<Column[]>([
  { key: 'name', title: '姓名' },
  { key: 'age', title: '年龄' },
  { key: 'address', title: '地址' },
]);

const data = ref([
  { id: 1, name: '张三', age: 32, address: '北京' },
  { id: 2, name: '李四', age: 42, address: '上海' },
  { id: 3, name: '王五', age: 28, address: '广州' },
]);
</script>

交互功能

通过配置 selectable, pagination, sortable, filterable 来开启行选择、分页、排序和筛选功能。

<template>
  <MagicTable
    :columns="columns"
    v-model="data"
    v-model:selected="selectedKeys"
    title="交互功能表格"
    :selectable="true"
    :pagination="true"
    :page-size="5"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import MagicTable, { type Column } from './components/MagicTable.vue';

const columns = ref<Column[]>([
  { key: 'name', title: '姓名', sortable: true, filterable: true, width: 150 },
  { key: 'age', title: '年龄', sortable: true, filterable: true, type: 'number', width: 120 },
  { key: 'email', title: '邮箱', filterable: true },
]);

const data = ref(/* ... some data ... */);
const selectedKeys = ref([]); // 用于存储选中行的 ID
</script>

单元格编辑

设置列的 editable: true 属性，即可在表格中直接编辑该单元格。

<template>
  <MagicTable
    :columns="columns"
    v-model="data"
    title="可编辑表格"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import MagicTable, { type Column } from './components/MagicTable.vue';

const columns = ref<Column[]>([
  { key: 'name', title: '姓名', editable: true },
  { key: 'role', title: '角色', editable: true, type: 'select', options: [
    { label: '管理员', value: 'admin' },
    { label: '开发者', value: 'developer' },
    { label: '访客', value: 'guest' },
  ]},
  { key: 'is_active', title: '是否启用', editable: true, type: 'boolean' },
]);

const data = ref([
  { id: 1, name: '张三', role: 'admin', is_active: true },
  { id: 2, name: '李四', role: 'developer', is_active: false },
]);
</script>

固定列与高度

当表格列数太多时，可以设置 fixed 属性将列固定在左侧或右侧。设置 height 属性可以使表头固定，内容区域垂直滚动。

<template>
  <MagicTable
    :columns="columns"
    v-model="data"
    title="固定列表格"
    height="300px"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import MagicTable, { type Column } from './components/MagicTable.vue';

const columns = ref<Column[]>([
  { key: 'id', title: 'ID', fixed: 'left', width: 80 },
  { key: 'col1', title: '很长的列1', width: 200 },
  { key: 'col2', title: '很长的列2', width: 200 },
  { key: 'col3', title: '很长的列3', width: 200 },
  { key: 'col4', title: '很长的列4', width: 200 },
  { key: 'action', title: '操作', fixed: 'right', width: 120 },
]);

const data = ref(/* ... some data ... */);
</script>

自定义渲染

使用插槽 (Slot) 来自定义特定列的显示方式。插槽名为列的 key。

<template>
  <MagicTable :columns="columns" v-model="data">
    <!-- 自定义 status 列 -->
    <template #status="{ row }">
      <span :class="row.status === 'active' ? 'text-green-600' : 'text-red-600'">
        {{ row.status === 'active' ? '活跃' : '禁用' }}
      </span>
    </template>

    <!-- 自定义 action 列 -->
    <template #action="{ row }">
      <button @click="handleEdit(row)">编辑</button>
      <button @click="handleDelete(row)">删除</button>
    </template>
  </MagicTable>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import MagicTable, { type Column } from './components/MagicTable.vue';

const columns = ref<Column[]>([
  { key: 'name', title: '姓名' },
  { key: 'status', title: '状态' },
  { key: 'action', title: '操作' },
]);

const data = ref([
  { id: 1, name: '张三', status: 'active' },
  { id: 2, name: '李四', status: 'inactive' },
]);

function handleEdit(row) {
  console.log('编辑:', row);
}
function handleDelete(row) {
  console.log('删除:', row);
}
</script>

API

MagicTable Props

| 属性名 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | columns | Column[] | [] | 必需，表格的列配置数组。 | | modelValue | Record<string, any>[] | [] | 必需，表格显示的数据，通常与 v-model 绑定。 | | title | string | undefined | 表格的标题。 | | loading | boolean | false | 是否显示加载状态。 | | pagination | boolean | false | 是否启用分页。 | | pageSize | number | 10 | 每页显示条数，可通过 v-model:pageSize 绑定。 | | pageSizes | number[] | [10, 20, 50] | 每页显示条数选项。 | | selectable | boolean | false | 是否启用行选择。 | | selected | (string \| number)[] | [] | 选中行的 id 数组，可通过 v-model:selected 绑定。 | | height | string | 'auto' | 表格容器的高度，如 '500px'。 |

MagicTable Events

| 事件名 | 参数 | 说明 | | --- | --- | --- | | update:modelValue | (data: Record<string, any>[]) | 表格数据变更时触发，用于 v-model。 | | update:selected | (selected: (string \| number)[]) | 选中行变更时触发，用于 v-model:selected。 | | update:pageSize | (size: number) | 每页显示条数变更时触发，用于 v-model:pageSize。 | | update:columns | (columns: Column[]) | 列配置变更时触发。 |

MagicTable Slots

| 插槽名 | 参数 | 说明 | | --- | --- | --- | | [column.key] | { row: Record<string, any>, value: any, rowIndex: number } | 自定义列内容的渲染，[column.key] 是动态的，对应列配置中的 key。 | | bulk-actions | { selectedRows: Set<string \| number> } | 自定义工具栏中的批量操作区域。 | | empty | - | 自定义表格无数据时的显示内容。 | | title | - | 自定义表格标题区域。 |

类型定义 (Types)

Column

export type ColumnType =
  | 'string' | 'number' | 'boolean' | 'currency' | 'percentage' | 'date'
  | 'datetime' | 'time' | 'select' | 'multoselect' | 'image' | 'link' | 'progress'
  | 'rating' | 'action' | 'custom';

export interface Column {
  key: string;
  title: string;
  align?: 'left' | 'center' | 'right';
  type?: ColumnType;
  editable?: boolean;
  options?: { label: string; value: any }[];
  sortable?: boolean;
  filterable?: boolean;
  width?: number;
  minWidth?: number;
  fixed?: 'left' | 'right';
}