@agile-team/mach-table-vue

@agile-team/mach-table-vue

MachTable 0.30.1 的官方 Vue 3 适配包。一个依赖即可获得 Core、泛型 <MachTable>、原生 slots、应用/路由配置、按需工作流、异步组件边界和自动生命周期清理。

pnpm add @agile-team/mach-table-vue

应用入口只引入一次样式：

import "@agile-team/mach-table-vue/styles.css";

局部接入

<script setup lang="ts">
import { h, ref } from "vue";
import {
  MachTable,
  defineVueColumns,
  defineVueTableConfig,
  indexColumn,
  useMachTable,
} from "@agile-team/mach-table-vue";

interface Row { id: string; name: string; status: "enabled" | "disabled" }
const table = useMachTable<Row>();
const rows = ref<Row[]>([{ id: "1", name: "MachTable", status: "enabled" }]);
const columns = defineVueColumns<Row>([
  indexColumn({ headerName: "序号" }),
  { field: "name", flex: 1, editable: true },
  {
    field: "status",
    headerName: "状态",
    render: (row) => h("span", { class: `status-${row.status}` }, row.status === "enabled" ? "启用" : "停用")
  }
]);
const tableConfig = defineVueTableConfig<Row>({
  rowKey: "id",
  enableColumnResize: true,
  stripedRows: true,
  persistence: { key: "customers:list", sections: ["columns"] }
});
</script>

<template>
  <div style="height: 520px">
    <MachTable
      v-bind="tableConfig"
      :ref="table.ref"
      :row-data="rows"
      :column-defs="columns"
    />
  </div>
</template>

业务列优先用 defineVueColumns() 的 render(row, index, params) 返回 VNode；它保留 Vue 应用上下文、支持原位刷新，并遵循全局、表格和单列对齐配置。复杂页面编排仍可使用 #cell-* 具名插槽，具名插槽会显式覆盖同列 render。多个稳定表格参数推荐放进页面 data.ts 或共享配置模块，模板通过一次 v-bind="tableConfig" 注入；rowData、columnDefs 和实例 ref 保持显式，便于看清数据来源。

未声明 #loading / #empty 时会直接使用 Core 的紧凑骨架加载态与插画空态；只有产品确实需要品牌化呈现时才提供 slot，避免每个页面重复维护同类状态组件。

单元格编辑在用户点击对勾/取消或执行 Enter、Escape、Tab 键盘命令前保持挂载，焦点变化和中文输入法组合输入不会提前提交。整行事务请设置 edit-type="fullRow" 并增加 rowActionsColumn()，该操作列会自动切换编辑、保存和取消状态。

全局接入

表格页面较多时，全局注册一次，页面模板直接使用 <MachTable>：

import { createApp } from "vue";
import { MachTablePlugin } from "@agile-team/mach-table-vue";
import machTableConfig from "@/config/mach-table.config";

createApp(App).use(MachTablePlugin, machTableConfig).mount("#app");

需要减少首屏代码时改用异步全局插件：

import AsyncMachTablePlugin, { preloadMachTable } from "@agile-team/mach-table-vue/async";

app.use(AsyncMachTablePlugin, machTableConfig);
void preloadMachTable(); // 可选：路由 hover 时预取

推荐把约定集中到独立文件：

// src/config/mach-table.config.ts
import { defineMachTableConfig, defineMachTablePreset } from "@agile-team/mach-table-vue";

export default defineMachTableConfig({
  defaults: {
    size: "compact",
    columnLayout: "fit",
    enableColumnResize: true,
    defaultColDef: { sortable: true, filter: true, resizable: true }
  },
  defaultPreset: "list",
  presets: {
    list: defineMachTablePreset({ stripedRows: true }),
    crud: defineMachTablePreset({ rowSelection: "multiple", editType: "fullRow" })
  }
});

布局或路由可用响应式 provideMachTableConfig() 叠加配置，表格 props 始终拥有最高优先级。

按需子入口

import { useMachTableQuery, useMachTableEditing } from "@agile-team/mach-table-vue/workflows";
import { MachTableToolbar } from "@agile-team/mach-table-vue/ui";
import { vueCellRenderer } from "@agile-team/mach-table-vue/adapters";
import { createElementPlusEditors } from "@agile-team/mach-table-vue/editors";
import { createWorkerDataProcessor } from "@agile-team/mach-table-vue/worker";

• /workflows：请求取消、防过期覆盖、服务端分页、跨页选择、脏数据和冲突保存；reset() 清空全部表格过滤且只请求一次。
• /ui：可选标准工具栏；需要全局组件时另行 app.use(MachTableUiPlugin)，其全局组件类型也只在导入该子入口后生效。
• /adapters：自定义 Vue renderer/editor/detail/overlay 桥接。
• /editors：可选 Element Plus 编辑器，Element Plus 由宿主注入。
• /worker：大型本地过滤/排序的独立 Worker 能力。

该包自动依赖 @agile-team/mach-table 并重导出 Core 类型；宿主只需提供 vue >= 3.2。

文档：Vue 指南 · 企业接入 · 配置中心

Source-available © ChenyCHENYU (Agile Team). 任何使用均须事先取得书面授权。详见 LICENSE 与授权流程。