VTE

VTE 是一个面向 Vue 3 企业后台的配置化表格与列表页组件体系。

它的初衷不是再造一个普通表格，而是解决项目内高频列表页的三个问题：

1. 统一全项目的表格样式、行高、操作列、分页、空态和错误态。
2. 统一搜索字段、操作符和最终查询参数，减少每个页面重复拼接查询条件。
3. 统一表格配置的来源与保存方式：既可以从云端加载并持久化用户视图，也可以直接传入 view 和 data 参数快速渲染。

VTE 通过一份 VteViewConfig 描述字段、搜索、表格、分组、按钮、分页和个性化配置，让业务开发只关注“这张表有哪些字段、怎么查、怎么操作”，而不是在每个模块重复搭表格、搜索区和字段配置弹层。

The precise product scope is documented in VTE组件精准需求与功能说明.md.

Development

npm install
npm run dev
npm run build
npm run build:preview
npm run preview
npm run test

npm run build builds the VTE component library into dist/.

npm run preview builds the example application into dist-preview/ and starts a preview server. Open the printed local URL, normally http://localhost:4173, to inspect the VTE feature-mode demos.

Usage Modes

VTE 0.2.0 主推组合式根组件。Vte 负责配置、数据、API 和状态上下文，子组件负责各自模块渲染。

1. 完整页

适合完整列表页，包含视图、搜索、工具栏、表格、分页和设置能力。

<script setup lang="ts">
import { Vte, VtePage } from 'vte';
import type { VtePageData, VteViewConfig } from 'vte';

const view: VteViewConfig = {
  view_key: 'sales_order',
  name: '最近订单',
  cells: [
    {
      field: 'order_no',
      title: '订单编号',
      type: 'text',
      search: true,
      default_operator: 'like',
      operators: ['like']
    }
  ]
};

const data: VtePageData = {
  list: [{ order_no: 'SO-001' }],
  total: 1,
  page: 1,
  size: 10
};
</script>

<template>
  <Vte :view="view" :data="data" @query="fetchList" @command="handleCommand">
    <VtePage>
      <template #cell-order_no="{ value }">
        <a class="vte-link">{{ value }}</a>
      </template>
    </VtePage>
  </Vte>
</template>

2. 仅表格和分页

适合只需要表格展示和分页的场景。

<template>
  <Vte :view="view" :data="data">
    <VteTable>
      <template #cell-order_no="{ value }">
        <strong>{{ value }}</strong>
      </template>
    </VteTable>
    <VtePagination />
  </Vte>
</template>

3. 搜索和表格

搜索字段插槽写在 VteSearch 内，表格字段插槽写在 VteTable 内。

<template>
  <Vte :view="view" :data="data">
    <VteGroups />
    <VteSearch>
      <template #field-customer="{ cell, filter, setFilter }">
        <input
          class="vte-input"
          :placeholder="`请输入${cell.title}`"
          :value="String(filter?.value ?? '')"
          @input="setFilter({ field: cell.field, operator: 'like', value: ($event.target as HTMLInputElement).value })"
        />
      </template>
    </VteSearch>
    <VteTable>
      <template #cell-order_no="{ value }">
        <strong>{{ value }}</strong>
      </template>
    </VteTable>
    <VtePagination />
  </Vte>
</template>

4. 云端视图

适合需要用户自定义字段显隐、列宽、排序、行高和默认视图的项目。业务侧提供视图服务和列表服务，VTE 负责在用户调整配置后触发保存。

import type { VteViewConfig } from 'vte';

const view: VteViewConfig = {
  view_key: 'sales_order',
  name: '销售订单',
  table: {
    column_config_trigger: 'table-header',
    show_header_filter: true
  },
  source: {
    mode: 'api',
    storage_key: 'vte:sales_order',
    api: {
      list: listService,
      views: viewService,
      save: viewService
    }
  },
  cells: []
};

table.column_config_trigger 可选值：

• toolbar：默认值，在工具栏展示字段配置按钮。
• table-header：在最后一个可见字段表头 hover 时展示图标按钮。
• both：工具栏和表头都展示入口。
• none：隐藏字段配置入口。

字段配置浮层内置“恢复默认”，会将当前视图的字段顺序、显隐、固定列、列宽等 cells 配置恢复到输入视图默认值。该操作不会清空当前搜索、排序、分组、分页和行高。字段显隐会保留至少一个可见字段，避免用户把表格配置成无可见列。

table.show_header_filter 默认关闭。开启后，VTE 会使用 VXETable 的表头筛选面板承载自己的字段筛选控件：

• 面板中的筛选条件来自字段类型和 operators / default_operator 配置。
• 表头不启用 VXETable 原生排序按钮。
• 如果当前字段 sort 不为 false，面板底部会展示升序、降序和无排序。
• 筛选和排序都会进入 VTE 查询状态，并触发列表查询。

table.summary 默认关闭。开启后，VTE 会展示页尾合计行：

• 合计数据优先读取 data.summary，键名与字段 field 对应。
• 独立使用 <VteTable /> 时，也可以通过 summary prop 传入合计数据。
• 未传入合计数据时，VTE 会自动对当前可见数据中的 number 字段求和。
• 页尾合计行高度跟随 table.row_height 的低、中、高三档。

const view: VteViewConfig = {
  view_key: 'sales_order',
  table: {
    summary: true
  },
  cells: [
    { field: 'amount', title: '金额', type: 'number' }
  ]
};

const data = {
  list: rows,
  total: rows.length,
  page: 1,
  size: 10,
  summary: {
    amount: 1200
  }
};

VTE 已内置注册 VXETable 的 VxeTooltip 依赖，业务侧透传 tableProps 使用 showOverflow: 'tooltip' 时无需额外安装 vxe-tooltip 独立包。

0.2.0 起，视图可以保存运行时状态：

• active_group_key：当前选中的分组。
• search_filters：当前搜索条件。
• sort_orders：当前排序条件。
• pagination.page / pagination.size：当前页码和每页条数。

调用 saveCurrentView() 后，VTE 会把当前搜索、排序、分组和分页写回视图配置；再次切换到该视图时会自动恢复。

1.0 起，完整页面统一使用 <Vte> 根组件承载状态，<VtePage> 必须放在 <Vte> 内使用。独立表格场景继续使用 <VteTable :view="view" :data="rows" />。

Plugin Usage

import { createApp } from 'vue';
import VtePlugin from 'vte';
import 'vte/dist/style.css';

createApp(App).use(VtePlugin).mount('#app');

Ref Methods

<script setup lang="ts">
import { ref } from 'vue';
import { Vte, VtePage } from 'vte';
import type { VteRootExpose } from 'vte';

const rootRef = ref<VteRootExpose>();

function searchNow() {
  rootRef.value?.setSearchFilter({ field: 'order_no', operator: 'like', value: 'SO' });
  rootRef.value?.refresh();
}

function resetColumns() {
  rootRef.value?.resetCellsToDefault();
}
</script>

<template>
  <Vte ref="rootRef" :view="view" :data="data">
    <VtePage />
  </Vte>
</template>

See VTE组件精准需求与功能说明.md for the target component behavior and configuration model.

Preview Demo

The preview demo uses sales-order data to show feature modes:

1. 完整列表页：视图、搜索、工具栏、表格、分页和云端视图配置。
2. 根组件 Table：在 <Vte> 上下文中组合表格和分页。
3. 搜索和 Table：轻量搜索区、表格、分页和行操作。
4. 独立 Table 个性化：不包裹 <Vte> 时的字段配置和本地持久化。
5. 表头筛选和 Ref：表头筛选面板、排序、tableProps 透传和实例方法。