npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@go-wind/element-pro

v0.2.3

Published

Config-driven CRUD page components for Vue 3 + Element Plus + vxe-table: search bar, toolbar, dual-engine table, pagination, form modal, full-page orchestration.

Readme

@go-wind/element-pro

一套基于 Vue 3 + Element Plus + vxe-table 的企业级业务组件库,提供配置化驱动的 CRUD 页面开发体验。

核心思想:一个配置对象描述一个完整的列表页面(搜索 → 工具栏 → 表格 → 分页 → 弹窗),无需重复编写模板代码。

本文档的语言以中文为主;组件内置文案包含 zh-CN / en-US 两包。

安装与集成

pnpm add @go-wind/element-pro
// main.ts
import ElementPlus from "element-plus";
import "element-plus/dist/index.css";
import "element-plus/theme-chalk/dark/css-vars.css";
import VXETable from "vxe-table";
import "vxe-table/lib/style.css";
import "@go-wind/element-pro/style.css";

const app = createApp(App);
app.use(ElementPlus); // 注册 v-loading 等指令
app.use(VXETable); // vxe 引擎按宿主惯例全局注册

与后端约定解耦:本库不绑定任何 HTTP 客户端。列表/删除/提交都是你注入的 action 函数(listAction / deleteAction / submitAction),分页参数名、请求体包裹、响应形状由 action 自己适配(返回 { items, total } 或裸数组即可)。

主题集成:切换暗色时,除 Element Plus 的 html.dark 外,还需调用 vxe 的主题切换(与官方 vxe-table 集成方式一致):

import { VxeUI } from "vxe-table";

function onThemeChange(dark: boolean) {
  document.documentElement.classList.toggle("dark", dark);
  VxeUI.setTheme(dark ? "dark" : "light");
}

全局配置:用 ProConfigProvider 注入语言、权限判定、骨架屏开关与表格持久化 id:

<ProConfigProvider :config="{
  locale: 'zh-CN',
  hasAccess: (codes) => userStore.hasAny(codes),
  resolveTableId: () => route.path,
  skeleton: true,
}">
  <RouterView />
</ProConfigProvider>

| 配置 | 说明 | 缺省行为 | |------|------|----------| | locale | 'zh-CN' \| 'en-US' | zh-CN | | messages | 自定义文案,与内置包深合并 | — | | hasAccess | 权限码判定(按钮 auth 配置消费) | 全放行 | | resolveTableId | 返回表格持久化 id(如路由路径) | 不启用 vxe 列配置持久化 | | skeleton | 全局骨架屏开关(页面 config.skeleton 之外的总闸) | 允许 |

按需引入(tree-shaking):组件均从包内直接 import Element Plus 组件,不做全量依赖。

目录结构

Pro/
├── ProForm/          # 动态表单
├── ProSearch/        # 搜索栏
├── ProToolbar/       # 工具栏
├── ProTable/         # 双引擎表格(vxe-table / el-table)
├── ProPagination/    # 分页
├── ProModal/         # 弹窗(Dialog / Drawer)
├── ProPage/          # 页面编排(组合以上所有组件)
├── composables/      # 状态管理 hooks
│   ├── useTableState.ts
│   ├── useModalState.ts
│   ├── useProPage.ts   # Level 2: 命令式 Api 控制
│   ├── useProModal.ts  # Level 3: 弹窗抽离(connectedComponent)
│   └── ProPageApi.ts   # ProPage Api 类
├── constants/        # 默认值常量
├── index.ts          # 统一导出
└── README.md

快速开始

最小示例

<template>
  <ProPage :config="pageConfig" />
</template>

<script setup lang="ts">
import { ProPage, type ProPageConfig } from "@go-wind/element-pro";

const pageConfig: ProPageConfig = {
  table: {
    listAction: async (params) => {
      const { page, pageSize, ...query } = params;
      const res = await fetchList({ page, pageSize, ...query });
      return { items: res.items, total: res.total };
    },
    columns: [
      { type: "index", label: "序号", width: 60 },
      { prop: "name", label: "名称", minWidth: 120 },
      { prop: "status", label: "状态", minWidth: 80 },
    ],
  },
};
</script>

完整示例(租户管理)

<template>
  <ProPage ref="pageRef" :config="pageConfig" @add="handleAdd" @edit="handleEdit">
    <!-- 自定义列插槽(通过 prop 或 slotName 匹配) -->
    <template #status="scope">
      <ElTag :type="scope.row.status === 1 ? 'success' : 'danger'">
        {{ scope.row.status === 1 ? '启用' : '禁用' }}
      </ElTag>
    </template>
  </ProPage>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { ProPage, type ProPageConfig } from "@go-wind/element-pro";

const pageRef = ref();

const pageConfig: ProPageConfig = {
  engine: "vxe", // 默认 vxe,可选 "element"

  search: {
    grid: true,
    fields: [
      { type: "input", label: "名称", field: "name", attrs: { clearable: true } },
      { type: "select", label: "状态", field: "status",
        options: [{ label: "启用", value: 1 }, { label: "禁用", value: 0 }],
      },
    ],
  },

  table: {
    listAction: async (params) => {
      const { page, pageSize, ...query } = params;
      const res = await fetchList({ page, pageSize, ...query });
      return { items: res.items, total: res.total };
    },
    deleteAction: async (ids) => await deleteItem({ id: ids }),
    toolbar: ["add"],
    defaultToolbar: ["refresh", "filter", "search"],
    columns: [
      { type: "index", label: "序号", width: 60 },
      { prop: "name", label: "名称", minWidth: 120 },
      { prop: "status", label: "状态", minWidth: 80, slotName: "status" },
      {
        prop: "createdAt", label: "创建时间", minWidth: 160,
        cellType: "date", dateFormat: "YYYY-MM-DD HH:mm:ss",
      },
      {
        prop: "action", label: "操作", fixed: "right", width: 150,
        cellType: "tool",
        buttons: [
          { name: "edit", text: "编辑" },
          { name: "delete", text: "删除", attrs: { type: "danger" } },
        ],
      },
    ],
  },
};

function handleAdd() { /* 打开新增弹窗 */ }
function handleEdit(row: any) { /* 打开编辑弹窗 */ }
</script>

使用层级

Pro 组件库设计为渐进式,从 0 模板的配置驱动到完全自由的原生写法,开发者可按需选择合适的抽象层级。


Level 1:ProPage 开箱即用(标准 CRUD)

适用场景:标准增删改查页面,配置即页面,无需写模板。

只需提供一个配置对象,ProPage 自动编排搜索、工具栏、表格、分页、弹窗的完整生命周期。

<template>
  <ProPage :config="pageConfig" />
</template>

<script setup lang="ts">
import { ProPage, type ProPageConfig } from "@go-wind/element-pro";
import { fetchListTenants, useDeleteTenant } from "@/api/composables";
import { PaginationQuery } from "@/core/transport/rest";

const { mutateAsync: deleteTenant } = useDeleteTenant();

const pageConfig: ProPageConfig = {
  // 搜索配置
  search: {
    grid: true,
    fields: [
      { type: "input", label: "名称", field: "name", attrs: { clearable: true } },
      { type: "select", label: "状态", field: "status",
        options: [{ label: "启用", value: 1 }, { label: "禁用", value: 0 }],
      },
    ],
  },

  // 表格配置
  table: {
    listAction: async (query) => {
      const { page, pageSize, ...params } = query;
      const result = await fetchListTenants(
        new PaginationQuery({
          paging: { page: page || 1, pageSize: pageSize || 10 },
          formValues: params,
        })
      );
      return { items: result.items || [], total: result.total || 0 };
    },
    deleteAction: async (ids: string) => {
      await deleteTenant({ id: ids as any });
    },
    toolbar: ["add"],
    defaultToolbar: ["refresh", "filter", "search"],
    columns: [
      { type: "index", label: "序号", width: 60 },
      { prop: "name", label: "名称", minWidth: 120 },
      { prop: "status", label: "状态", minWidth: 80, cellType: "tag",
        labelMap: { 1: "启用", 0: "禁用" }, tagType: "success",
      },
      { prop: "createdAt", label: "创建时间", minWidth: 160, cellType: "date" },
      { prop: "action", label: "操作", fixed: "right", width: 150, cellType: "tool",
        buttons: [
          { name: "edit", text: "编辑" },
          { name: "delete", text: "删除", attrs: { type: "danger" } },
        ],
      },
    ],
  },

  // 弹窗配置(新增/编辑共用)
  modal: {
    component: "drawer",
    drawer: { title: "租户管理", size: "500px" },
    fields: [
      { type: "input", label: "名称", field: "name", rules: [{ required: true, message: "请输入名称" }] },
      { type: "input", label: "编码", field: "code", rules: [{ required: true, message: "请输入编码" }] },
      { type: "textarea", label: "备注", field: "remark" },
    ],
    submitAction: async (data) => {
      // 提交逻辑
    },
  },
};
</script>

要点:

  • 一个配置对象 = 一个完整的 CRUD 页面
  • 搜索、工具栏、表格、分页、弹窗全自动联动
  • 新增/编辑/删除/导出/导入均内置
  • 零模板代码,纯声明式

Level 2:useProPage 命令式控制(外部联动)

适用场景:需要在页面外部(其他组件、watch、定时器等)命令式控制 ProPage 的行为。

通过 useProPage(config) 返回 [Page, api], 通过 api 对象命令式控制刷新、弹窗、查询等,无需 ref + value。

<template>
  <div class="flex gap-4 h-full">
    <!-- 左侧部门树 -->
    <ElCard class="w-64 shrink-0" shadow="never">
      <ElTree :data="treeData" @node-click="handleNodeClick" />
    </ElCard>

    <!-- 右侧表格 -->
    <div class="flex-1 min-w-0">
      <Page #status="scope">
        <ElTag :type="scope.row.status === 1 ? 'success' : 'danger'">
          {{ scope.row.status === 1 ? '启用' : '禁用' }}
        </ElTag>
      </Page>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, watch } from "vue";
import { ElCard, ElTree, ElTag } from "element-plus";
import { useProPage, type ProPageConfig } from "@go-wind/element-pro";

// useProPage 返回 [组件, api]
const [Page, pageApi] = useProPage({
  table: {
    listAction: async (params) => {
      const { page, pageSize, ...query } = params;
      const res = await fetchList({ page, pageSize, ...query });
      return { items: res.items, total: res.total };
    },
    columns: [
      { type: "index", label: "序号", width: 60 },
      { prop: "name", label: "名称", minWidth: 120 },
      { prop: "status", label: "状态", minWidth: 80, slotName: "status" },
      { prop: "action", label: "操作", fixed: "right", width: 150, cellType: "tool",
        buttons: [{ name: "edit", text: "编辑" }, { name: "delete", text: "删除" }],
      },
    ],
  },
});

// 树节点点击时,通过 api 命令式查询
const treeData = ref([]);
function handleNodeClick(node: any) {
  pageApi.reload({ deptId: node.id }); // 重新查询
}

// 也可以在 watch / 定时器 / 其他组件回调中调用
// pageApi.refresh()     // 刷新当前页
// pageApi.openAdd()     // 打开新增弹窗
// pageApi.openEdit(row) // 打开编辑弹窗
// pageApi.query({ keyword: 'xxx' }) // 追加参数查询
// pageApi.getSelectionIds() // 获取选中行 ID
// pageApi.getSearchParams() // 获取当前搜索参数
</script>

ProPageApi 方法一览

| 方法 | 说明 | |------|------| | refresh() | 刷新当前页数据 | | reload(params?) | 重置到第 1 页重新查询,可选追加参数 | | query(params) | 追加查询参数并刷新当前页 | | getData() | 获取当前表格数据 | | getSelection() | 获取选中行 | | getSelectionIds() | 获取选中行 ID 数组 | | clearSelection() | 清空选中 | | isLoading() | 获取加载状态 | | getPagination() | 获取分页信息 { currentPage, pageSize, total } | | openAdd() | 打开新增弹窗 | | openEdit(row) | 打开编辑弹窗 | | openView(row) | 打开查看弹窗 | | closeModal() | 关闭弹窗 | | getSearchParams() | 获取当前搜索参数快照 | | setState(stateOrFn) | 响应式更新状态(mount 前后均可调用) | | useStore(selector?) | 获取 Store 状态的响应式引用 | | waitForMounted() | 等待组件挂载完成(异步) | | setConfig(config) | 响应式更新配置 |

要点:

  • useProPage 和 <ProPage :config> 完全等价,只是控制方式不同
  • 适合需要在外部联动控制表格的场景(树点击、Tab 切换、watch 联动等)
  • 无需 ref + value,api 直接调用方法
  • setState() 支持 mount 前预设配置、mount 后响应式更新
  • 插槽、事件、配置均与 Level 1 完全相同

setState 响应式状态更新

ProPageApi 内部使用 @tanstack/vue-store 管理响应式状态,setState 支持 mount 前后任意时刻调用:

const [Page, pageApi] = useProPage(config);

// 对象式更新
pageApi.setState({ loading: true });

// 函数式更新(基于前一个状态计算)
pageApi.setState(prev => ({
  searchParams: { ...prev.searchParams, extraParam: 1 },
}));

// mount 前预设配置
pageApi.setState({ config: overrideConfig });

// 获取响应式引用(在 setup 中使用)
const loading = pageApi.useStore(s => s.loading);
// loading 是 Readonly<Ref<boolean>>

Level 3:插槽定制(复杂交互)

适用场景:基础配置不满足时,通过插槽覆盖特定列的渲染,或接管事件处理。

Level 1 的配置 + 插槽 + 事件组合,可以覆盖大多数复杂场景,而无需放弃 ProPage 的自动编排能力。

自定义列渲染

通过 slotName 或 prop 匹配插槽,覆盖单元格渲染:

<template>
  <ProPage ref="pageRef" :config="pageConfig" @add="handleAdd" @edit="handleEdit">
    <!-- 类型列:自定义 Tag 配色 -->
    <template #type="scope">
      <ElTag size="small" effect="dark" round :color="typeToColor(scope.row.type)">
        {{ typeToName(scope.row.type) }}
      </ElTag>
    </template>

    <!-- 状态列:带 Switch 切换 -->
    <template #status="scope">
      <ElSwitch
        :model-value="scope.row.status === 1"
        @change="(val) => handleStatusChange(scope.row, val)"
      />
    </template>

    <!-- 展开行:复杂详情 -->
    <template #expand="scope">
      <div class="p-4">
        <ElDescriptions :column="2" border>
          <ElDescriptionsItem label="创建人">{{ scope.row.creator }}</ElDescriptionsItem>
          <ElDescriptionsItem label="创建时间">{{ scope.row.createdAt }}</ElDescriptionsItem>
        </ElDescriptions>
      </div>
    </template>

    <!-- 工具栏扩展 -->
    <template #toolbar-left>
      <ElButton type="warning" @click="handleBatchExport">批量导出</ElButton>
    </template>
  </ProPage>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { ElTag, ElSwitch, ElDescriptions, ElDescriptionsItem, ElButton } from "element-plus";
import { ProPage, type ProPageConfig } from "@go-wind/element-pro";

const pageRef = ref();

const pageConfig: ProPageConfig = {
  table: {
    listAction: async (params) => { /* ... */ return { items: [], total: 0 }; },
    columns: [
      { type: "index", label: "序号", width: 60 },
      { type: "expand", label: "详情", width: 50 },
      { prop: "name", label: "名称", minWidth: 120 },
      { prop: "type", label: "类型", minWidth: 100, slotName: "type" },
      { prop: "status", label: "状态", minWidth: 80, slotName: "status" },
    ],
  },
};

function handleAdd() { /* 打开自定义弹窗 */ }
function handleEdit(row: any) { /* 打开自定义弹窗 */ }
function handleStatusChange(row: any, val: boolean) { /* 调用接口 */ }
function handleBatchExport() { /* 批量导出逻辑 */ }
</script>

外部接管弹窗(ref 方式)

当内置 ProModal 不满足需求时,可以不配置 modal,完全自行控制弹窗:

<template>
  <ProPage ref="pageRef" :config="pageConfig" @add="handleAdd" @edit="handleEdit">
    <!-- 列插槽 ... -->
  </ProPage>

  <!-- 自定义 Drawer,不受 ProPage 管控 -->
  <TenantDrawer ref="drawerRef" @success="handleSuccess" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { ProPage } from "@go-wind/element-pro";
import TenantDrawer from "./tenant-drawer.vue";

const pageRef = ref();
const drawerRef = ref();

const pageConfig = {
  table: {
    listAction: async () => { /* ... */ },
    columns: [ /* ... */ ],
  },
  // 不配置 modal → ProPage 不会渲染内置弹窗
};

function handleAdd() {
  drawerRef.value?.open(); // 完全自行控制
}
function handleEdit(row: any) {
  drawerRef.value?.open(row);
}
function handleSuccess() {
  pageRef.value?.refresh(); // 手动刷新表格
}
</script>

要点:

  • 插槽和配置可以混合使用,不冲突
  • 不需要的功能不配置即可(如不配 modal 就不渲染弹窗)
  • ProPage 的事件(@add、@edit)让你完全控制后续流程
  • 通过 pageRef.value?.refresh() 可随时刷新数据

外部接管弹窗(connectedComponent 方式)

使用 useProModal + connectedComponent 将弹窗抽离为独立的 .vue 文件,通过 provide/inject 自动连接,无需手动管理 ref:

列表页(user-list.vue):

<template>
  <ProPage ref="pageRef" :config="pageConfig" @add="handleAdd" @edit="handleEdit">
    <!-- 列插槽 ... -->
  </ProPage>

  <!-- 弹窗组件自动连接 -->
  <UserDrawer />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { ProPage, useProModal, type ProPageConfig } from "@go-wind/element-pro";
import UserDrawer from "./user-drawer.vue";

const pageRef = ref();

const pageConfig: ProPageConfig = {
  table: {
    listAction: async () => { /* ... */ return { items: [], total: 0 }; },
    columns: [ /* ... */ ],
  },
  // 不配置 modal → ProPage 不会渲染内置弹窗
};

// useProModal 连接 UserDrawer 组件
const [UserDrawer, modalApi] = useProModal({
  connectedComponent: UserDrawer,
  onOpenChange(isOpen) {
    if (!isOpen) pageRef.value?.refresh(); // 关闭时刷新
  },
});

function handleAdd() {
  modalApi.open({ create: true }); // 传递数据给弹窗
}
function handleEdit(row: any) {
  modalApi.open({ create: false, row });
}
</script>

弹窗组件(user-drawer.vue):

<template>
  <ElDrawer v-model="visible" :title="title" size="500px" destroy-on-close append-to-body>
    <ElForm ref="formRef" :model="form" label-width="auto">
      <ElFormItem label="名称" prop="name" :rules="[{ required: true, message: '必填' }]">
        <ElInput v-model="form.name" />
      </ElFormItem>
    </ElForm>
    <template #footer>
      <ElButton @click="handleCancel">取消</ElButton>
      <ElButton type="primary" :loading="submitting" @click="handleSubmit">确定</ElButton>
    </template>
  </ElDrawer>
</template>

<script setup lang="ts">
import { ref, reactive, computed } from "vue";
import { injectProModalApi } from "@go-wind/element-pro";

// 通过 inject 获取列表页传入的 modalApi
const modalApi = injectProModalApi();

const data = computed(() => modalApi.getData());
const title = computed(() => data.value.create ? '新增' : '编辑');
const visible = computed({
  get: () => modalApi.store.state.isOpen,
  set: (v) => { if (!v) modalApi.close(); },
});

const form = reactive({ name: '' });
const submitting = ref(false);

function handleCancel() { modalApi.close(); }
async function handleSubmit() {
  submitting.value = true;
  try {
    // 提交逻辑...
    modalApi.close();
  } finally {
    submitting.value = false;
  }
}
</script>

要点:

  • 列表页无需 ref 管理弹窗,useProModal 自动通过 provide/inject 桥接
  • 弹窗组件通过 injectProModalApi() 获取 api,访问共享数据
  • 弹窗组件完全自包含,可复用、可测试
  • modalApi.open(data) 可传递任意数据,弹窗内 modalApi.getData() 获取

Level 4:原子组件自由组合(完全控制)

适用场景:非标准页面布局、特殊交互流程,需要完全控制页面结构。

跳过 ProPage 编排层,直接使用原子组件(ProSearch、ProToolbar、ProTable、ProModal 等)+ Composables(useTableState、useModalState)自行组装。

<template>
  <div class="custom-page">
    <!-- 搜索栏 -->
    <ProSearch
      :fields="searchFields"
      :grid="true"
      @search="handleSearch"
      @reset="handleReset"
    />

    <!-- 中间区域:左侧树 + 右侧表格 -->
    <div class="flex gap-4 flex-1 min-h-0">
      <!-- 左侧部门树 -->
      <ElCard class="w-64 shrink-0" shadow="never">
        <ElTree :data="treeData" @node-click="handleNodeClick" />
      </ElCard>

      <!-- 右侧表格区 -->
      <div class="flex-1 flex flex-col min-w-0">
        <ProToolbar
          :left-buttons="toolbarButtons"
          @button-click="handleToolbarClick"
        />

        <ProTable
          ref="tableRef"
          :columns="columns"
          :data="tableState.data.value"
          :loading="tableState.loading.value"
          :total="tableState.pagination.total"
          :current-page="tableState.pagination.currentPage"
          :page-size="tableState.pagination.pageSize"
          @selection-change="tableState.handleSelectionChange"
          @current-change="(p) => { tableState.pagination.currentPage = p; tableState.fetch(params); }"
          @size-change="(s) => { tableState.pagination.pageSize = s; tableState.fetch(params, true); }"
        >
          <!-- 自定义列插槽 -->
          <template #status="scope">
            <ElSwitch :model-value="scope.row.status === 1" />
          </template>
        </ProTable>
      </div>
    </div>

    <!-- 弹窗 -->
    <ProModal
      v-model:visible="modalState.visible.value"
      :mode="modalState.mode.value"
      :config="modalConfig"
      :form-data="modalState.formData"
      @submit="tableState.fetch(params)"
    />
  </div>
</template>

<script setup lang="ts">
import { reactive, ref } from "vue";
import { ElCard, ElTree, ElSwitch } from "element-plus";
import {
  ProSearch,
  ProToolbar,
  ProTable,
  ProModal,
  useTableState,
  useModalState,
  type ProFormField,
  type ProTableColumn,
  type ProModalConfig,
  type ToolbarButton,
} from "@go-wind/element-pro";

// === 搜索 ===
const searchFields: ProFormField[] = [
  { type: "input", label: "名称", field: "name" },
  { type: "select", label: "状态", field: "status",
    options: [{ label: "启用", value: 1 }, { label: "禁用", value: 0 }],
  },
];
const params = reactive<Record<string, any>>({});

function handleSearch(p: any) {
  Object.assign(params, p);
  tableState.fetch(params, true);
}
function handleReset(p: any) {
  Object.keys(params).forEach((k) => delete params[k]);
  tableState.fetch(params, true);
}

// === 表格 ===
const tableState = useTableState({
  indexAction: async (query) => { /* ... */ return { items: [], total: 0 }; },
});
tableState.fetch(params);

const columns: ProTableColumn[] = [
  { type: "selection" },
  { type: "index", label: "序号", width: 60 },
  { prop: "name", label: "名称", minWidth: 120 },
  { prop: "status", label: "状态", minWidth: 80, slotName: "status" },
];

// === 工具栏 ===
const toolbarButtons: ToolbarButton[] = [
  { name: "add", text: "新增", attrs: { type: "success" } },
  { name: "delete", text: "删除", attrs: { type: "danger" } },
];

// === 弹窗 ===
const modalState = useModalState("id");
const modalConfig: ProModalConfig = {
  component: "drawer",
  drawer: { title: "编辑", size: "500px" },
  fields: [
    { type: "input", label: "名称", field: "name", rules: [{ required: true, message: "必填" }] },
  ],
  submitAction: async (data) => { /* ... */ },
};

function handleToolbarClick(name: string) {
  if (name === "add") modalState.open("add");
}

// === 树 ===
const treeData = ref([]);
function handleNodeClick(node: any) {
  params.deptId = node.id;
  tableState.fetch(params, true);
}
</script>

要点:

  • 各原子组件完全独立,可按需组合
  • useTableState 和 useModalState 提供开箱即用的状态管理
  • 自由安排页面布局(树 + 表格、多表格、嵌套布局等)
  • 所有组件 Props/Events/Slots 完全透明,没有黑盒

层级对比

| | Level 1 | Level 2 | Level 3 | Level 4 | |---|---|---|---|---| | 核心 | <ProPage :config /> | useProPage(config) → [Page, api] | ProPage + 插槽 + 事件 | 原子组件 + Composables | | 模板代码 | 零 | 零 | 少量(插槽模板) | 中等(自行组装) | | 配置化程度 | 完全配置 | 完全配置 + 命令式 api | 配置为主、插槽补充 | 配置 + 自由编排 | | 控制方式 | 声明式(ref) | 命令式(api) | 声明式 + 事件 | 完全自行控制 | | 适用场景 | 标准 CRUD | 外部联动控制 | 带特殊列/交互的 CRUD | 非标准布局/复杂交互 | | 外部操作 | pageRef.value?.refresh() | pageApi.refresh() | 同 Level 1 | 完全自行控制 | | 弹窗控制 | 内置 ProModal | 内置 + api 命令式 | 外部接管 / connectedComponent | 完全自行控制 | | 学习成本 | 最低 | 低 | 低 | 中 |

建议:70% 的页面用 Level 1,15% 用 Level 2(外部联动),10% 用 Level 3,5% 用 Level 4。


组件 API

ProPage

页面编排组件,通过一个配置对象驱动搜索、工具栏、表格、分页、弹窗的完整生命周期。

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | config | ProPageConfig | 必填 | 页面配置对象,详见下方 |

Events

| 事件 | 参数 | 说明 | |------|------|------| | search | (params) | 搜索触发 | | reset | (params) | 重置触发 | | add | () | 新增按钮点击 | | edit | (row) | 编辑按钮点击 | | view | (row) | 查看按钮点击 | | delete | (ids) | 删除完成 | | operate | ({ name, row, $index }) | 操作列自定义按钮点击 | | toolbar | (name) | 自定义工具栏按钮点击 |

Expose

| 方法 | 说明 | |------|------| | refresh() | 刷新表格数据 | | tableRef | 表格组件引用 | | tableState | useTableState 实例 | | modalState | useModalState 实例 | | searchParams | 当前搜索参数 |


ProPageConfig

interface ProPageConfig<T, Q> {
  exportFilename?: string;       // 导出文件名(不含扩展名)
  engine?: "vxe" | "element";   // 表格引擎,默认 "vxe"
  rowKey?: string;               // 主键字段名,默认 "id"

  search?: {                     // 搜索配置(省略则不显示搜索栏)
    fields?: ProFormField[];
    isExpandable?: boolean;      // 是否支持展开/收起,默认 true
    showNumber?: number;         // 默认显示字段数,默认 3
    colon?: boolean;             // 标签后显示冒号
    grid?: boolean | "left" | "right"; // 自适应网格布局
  };

  table: {                       // 表格配置(必填)
    columns: ProTableColumn[];
    tableAttrs?: Record<string, any>; // 透传表格属性
    pagination?: boolean;        // 是否分页,默认 true
    toolbar?: Array<string | ToolsButton>;    // 左侧工具栏
    toolbarRight?: Array<string | ToolsButton>; // 右侧自定义按钮
    defaultToolbar?: Array<string | ToolsButton>; // 右侧图标按钮
    listAction: ListAction;      // 列表请求函数(必填)
    request?: { pageName: string; limitName: string }; // 分页参数名
    modifyAction?: (data) => Promise<any>; // 行内修改
    deleteAction?: (ids) => Promise<any>;  // 删除
    exportAction?: (params) => Promise<any>; // 导出
    importAction?: (file) => Promise<any>;   // 导入
    importTemplate?: string | (() => Promise<any>); // 导入模板
  };

  modal?: {                      // 弹窗配置(省略则不显示弹窗)
    component?: "dialog" | "drawer"; // 弹窗类型,默认 "dialog"
    dialog?: Partial<DialogProps>;
    drawer?: Partial<DrawerProps>;
    form?: Record<string, any>;
    colon?: boolean;
    fields: ProFormField[];
    beforeSubmit?: (data) => void;
    submitAction?: (data) => Promise<any>;
  };
}

ProTable

双引擎表格,支持 vxe-table(默认)和 el-table。

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | columns | ProTableColumn[] | 必填 | 列配置 | | data | T[] | [] | 表格数据 | | loading | boolean | false | 加载状态 | | engine | "vxe" \| "element" | "vxe" | 表格引擎 | | rowKey | string | "id" | 行主键 | | table | Record<string, any> | {} | 透传表格属性 | | pagination | boolean | — | 是否显示分页 | | total | number | 0 | 数据总条数 | | currentPage | number | 1 | 当前页码 | | pageSize | number | 20 | 每页条数 | | pageSizes | number[] | [10,20,30,50,100] | 可选每页条数 |

Events

| 事件 | 参数 | 说明 | |------|------|------| | selection-change | (rows) | 选中行变化 | | modify | ({ row, field, value }) | 行内编辑(switch) | | operate | ({ name, row, $index }) | 操作列按钮点击 | | current-change | (page) | 页码变化 | | size-change | (size) | 每页条数变化 |

Expose

| 方法 | 说明 | |------|------| | getSelectionRows() | 获取选中行 | | clearSelection() | 清空选中 | | toggleRowSelection(row, selected?) | 切换行选中状态 |


ProTableColumn

interface ProTableColumn<T> {
  type?: "default" | "selection" | "index" | "expand"; // 列类型
  label?: string;                    // 列标题
  prop?: keyof T & string;           // 字段名
  width?: string | number;           // 列宽
  minWidth?: string | number;        // 最小列宽
  fixed?: "left" | "right" | boolean; // 固定列
  align?: "left" | "center" | "right";
  sortable?: boolean | "custom";     // 排序
  show?: boolean;                    // 是否显示,默认 true
  treeNode?: boolean;                // 树节点列

  // === 单元格渲染 ===
  cellType?: CellType;               // 渲染类型(见下表)
  slotName?: string;                 // 自定义插槽名

  // cellType: "image"
  imageWidth?: number;               // 默认 40
  imageHeight?: number;              // 默认 40
  // cellType: "tag"
  labelMap?: Record<string, any>;    // 值-标签映射
  tagType?: string;
  // cellType: "switch"
  activeValue?: any;                 // 默认 1
  inactiveValue?: any;               // 默认 0
  activeText?: string;
  inactiveText?: string;
  // cellType: "date"
  dateFormat?: string;               // 默认 "YYYY-MM-DD HH:mm:ss"
  // cellType: "price"
  pricePrefix?: string;              // 价格前缀,如 "¥"
  // cellType: "tool"
  buttons?: Array<{ name: string; text?: string; auth?: string | string[]; attrs?: any; visible?: (row) => boolean }>;

  attrs?: Record<string, any>;       // 透传原生属性
  initFn?: (item) => void;           // 初始化函数
  reserveSelection?: boolean;        // 跨页保留选中
}

cellType 类型

| 值 | 说明 | 附加属性 | |----|------|----------| | text | 默认文本(可省略) | — | | image | 图片预览 | imageWidth, imageHeight | | tag | 标签 | labelMap, tagType | | switch | 开关(触发 modify 事件) | activeValue, inactiveValue, activeText, inactiveText | | date | 日期格式化 | dateFormat | | link | 超链接 | — | | price | 价格 | pricePrefix | | percent | 百分比 | — | | icon | 图标 | — | | tool | 操作列按钮 | buttons | | custom | 自定义插槽 | slotName 或 prop 作为插槽名 |


ProSearch

搜索栏组件,支持 inline/flex/grid 三种布局模式。

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | fields | ProFormField[] | 必填 | 搜索字段配置 | | colon | boolean | false | 标签冒号 | | grid | boolean \| "left" \| "right" | false | 自适应网格布局 | | inline | boolean | true | 行内表单模式 | | isExpandable | boolean | true | 支持展开/收起 | | showNumber | number | 3 | 默认显示字段数 |

Events

| 事件 | 参数 | 说明 | |------|------|------| | search | (params) | 搜索 | | reset | (params) | 重置 | | expand | (expanded) | 展开/收起 |


ProToolbar

工具栏组件,管理左侧操作按钮和右侧快捷工具。

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | leftButtons | ToolbarButton[] | [] | 左侧按钮 | | rightButtons | ToolbarButton[] | [] | 右侧自定义按钮 | | defaultToolbar | ("refresh" \| "filter" \| "search" \| "exports" \| "imports")[] | ["refresh","filter","search"] | 右侧图标按钮 | | visible | boolean | true | 是否显示 |

Events

| 事件 | 参数 | 说明 | |------|------|------| | button-click | (name, data?) | 按钮点击 | | refresh | () | 刷新 | | search | () | 搜索切换 | | filter | () | 筛选 | | export | () | 导出 | | import | () | 导入 |


ProModal

弹窗组件,支持 Dialog 和 Drawer 两种模式,内置表单。

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | visible | boolean | 必填 | 是否显示 | | mode | "add" \| "edit" \| "view" | "add" | 弹窗模式 | | config | ProModalConfig | 必填 | 弹窗配置 | | formData | T | 必填 | 表单数据(reactive 对象) |

Events

| 事件 | 参数 | 说明 | |------|------|------| | update:visible | (boolean) | 显示状态变化 | | submit | () | 提交成功 |


ProForm

动态表单,通过字段配置自动渲染表单组件。

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | modelValue | T | 必填 | 表单数据对象 | | fields | ProFormField[] | 必填 | 字段配置 | | colon | boolean | false | 标签冒号 | | disabled | boolean | false | 禁用所有字段 |

Expose

| 方法 | 说明 | |------|------| | validate() | 表单校验 | | resetFields() | 重置表单 |


ProFormField

表单字段配置,被 ProForm、ProSearch、ProModal 共用。

interface ProFormField<T> {
  type?: FormValueType;    // 组件类型(见下表)
  label: string;           // 标签文本
  field: keyof T & string; // 字段名
  tips?: string;           // 标签提示
  attrs?: Record<string, any>; // 组件属性(placeholder、clearable 等)
  options?: { label: string; value: any }[]; // 选项列表
  rules?: FormItemRule[];  // 校验规则
  initialValue?: any;      // 初始值
  slotName?: string;       // 自定义插槽名
  hidden?: boolean;        // 是否隐藏
  span?: number;           // 栅格占位(默认 24)
  events?: Record<string, Function>; // 组件事件
  initFn?: (item) => void; // 初始化回调
  api?: () => Promise<any[]>; // 异步数据源(api-tree-select)
}

FormValueType 类型

| 值 | 说明 | |----|------| | input | 输入框 | | textarea | 文本域 | | select | 下拉选择 | | radio | 单选 | | checkbox | 多选 | | switch | 开关 | | date-picker / date | 日期选择 | | time-picker | 时间选择 | | time-select | 时间选择(固定选项) | | input-number / number | 数字输入 | | cascader | 级联选择 | | tree-select | 树选择 | | api-tree-select | 异步树选择 | | input-tag | 标签输入 | | icon-select | 图标选择 | | custom | 自定义插槽 |


ProPagination

分页组件,自动计算 layout。

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | total | number | 0 | 总条数 | | showTotal | boolean | true | 显示总条数 | | showSizes | boolean | true | 显示页大小选择 | | showJump | boolean | true | 显示跳转 | | background | boolean | true | 按钮背景色 | | hideOnSinglePage | boolean | false | 单页隐藏 |


Composables

useTableState

表格数据状态管理,处理分页、加载、选中。

import { useTableState } from "@go-wind/element-pro";

const tableState = useTableState({
  indexAction: (params) => fetchList(params), // 必填
  rowKey: "id",          // 默认 "id"
  pagination: true,      // 默认 true
  request: { pageName: "page", limitName: "pageSize" }, // 自定义参数名
});

// 返回值
tableState.data           // ShallowRef<T[]> 表格数据
tableState.loading        // Ref<boolean>    加载状态
tableState.pagination     // Reactive        分页状态 { currentPage, pageSize, total, ... }
tableState.selection      // ShallowRef<T[]> 选中行
tableState.showPagination // boolean         是否显示分页
tableState.fetch(params?, resetPage?) // 请求数据
tableState.handleSelectionChange(rows) // 处理选中
tableState.getSelectionIds() // 获取选中行 ID

useModalState

弹窗状态管理。

import { useModalState } from "@go-wind/element-pro";

const modalState = useModalState("id"); // 传入 rowKey

// 返回值
modalState.visible  // Ref<boolean>        是否显示
modalState.mode     // Ref<"add"|"edit"|"view"> 弹窗模式
modalState.formData // Reactive             表单数据
modalState.open(mode, row?) // 打开弹窗

useProPage

命令式 Api 控制。

import { useProPage } from "@go-wind/element-pro";

const [Page, pageApi] = useProPage({
  table: {
    listAction: (params) => fetchList(params),
    columns: [ /* ... */ ],
  },
});

// api 方法
pageApi.refresh()              // 刷新当前页
pageApi.reload({ deptId: 1 })  // 重置到第 1 页重新查询
pageApi.query({ keyword: '' }) // 追加参数查询
pageApi.getData()              // 获取表格数据
pageApi.getSelection()         // 获取选中行
pageApi.getSelectionIds()      // 获取选中行 ID
pageApi.clearSelection()       // 清空选中
pageApi.isLoading()            // 加载状态
pageApi.getPagination()        // 分页信息
pageApi.openAdd()              // 打开新增弹窗
pageApi.openEdit(row)          // 打开编辑弹窗
pageApi.openView(row)          // 打开查看弹窗
pageApi.closeModal()           // 关闭弹窗
pageApi.getSearchParams()      // 获取搜索参数

// setState 响应式状态更新
pageApi.setState({ loading: true })            // 对象式
pageApi.setState(prev => ({                     // 函数式
  searchParams: { ...prev.searchParams, extra: 1 },
}))
pageApi.useStore(s => s.loading)                // 响应式引用
pageApi.waitForMounted()                        // 等待组件挂载

useProModal

弹窗抽离,通过 connectedComponent + provide/inject 将弹窗组件自包含。

import { useProModal, injectProModalApi } from "@go-wind/element-pro";

// === 列表页 ===
const [Modal, modalApi] = useProModal({
  connectedComponent: UserDrawer,  // 弹窗组件
  onOpenChange(isOpen) {
    if (!isOpen) pageRef.value?.refresh();
  },
});

modalApi.open({ create: true })  // 打开弹窗,传递数据
modalApi.open({ create: false, row })
modalApi.close()                 // 关闭弹窗
modalApi.getData()               // 获取共享数据
modalApi.setData({ key: value }) // 设置共享数据
modalApi.setLoading(true)        // 设置确认按钮 loading
modalApi.store.state.isOpen      // 直接访问 Store 状态

// === 弹窗组件内部 ===
const modalApi = injectProModalApi();
const data = modalApi.getData();
// ... 自定义渲染和提交逻辑

表格引擎

ProTable 内置两种渲染引擎,通过 engine prop 切换:

| 引擎 | 值 | 说明 | |------|-----|------| | vxe-table | "vxe" | 默认,功能丰富(虚拟滚动、树形等) | | el-table | "element" | Element Plus 原生表格,轻量 |

引擎差异自动映射:

| 功能 | vxe-table | el-table | |------|-----------|----------| | 复选框列 | type: "checkbox" | type: "selection" | | 序号列 | type: "seq" | type: "index" | | 列字段 | field | prop | | 列标题 | title | label | | 行索引 | scope.rowIndex | scope.$index | | 获取选中 | getCheckboxRecords() | getSelectionRows() | | 清空选中 | clearCheckboxRow() | clearSelection() |


工具栏按钮

内置按钮

ProPage 的 toolbar 和 defaultToolbar 支持字符串快捷方式:

// 左侧工具栏
toolbar: ["add", "delete", "import", "export"]

// 右侧图标按钮
defaultToolbar: ["refresh", "filter", "search", "exports", "imports"]

自定义按钮

toolbar: [
  {
    name: "custom-action",
    text: "自定义操作",
    auth: "sys:user:create",    // 完整权限标识(角色码或权限码均可)
    attrs: { type: "warning" }, // ElButton 属性
    visible: (row) => true,   // 动态显隐
  },
]

插槽

ProPage 插槽

表格自定义列插槽通过 prop 或 slotName 匹配:

<ProPage :config="pageConfig">
  <!-- 通过 prop 匹配 -->
  <template #status="scope">
    <ElTag>{{ scope.row.status }}</ElTag>
  </template>

  <!-- 通过 slotName 匹配 -->
  <template #customSlot="scope">
    <span>{{ scope.row }} {{ scope.column }} {{ scope.index }}</span>
  </template>
</ProPage>

在 columns 中配置:

columns: [
  { prop: "status", label: "状态", slotName: "status" },   // 或 cellType: "custom"
  { prop: "custom", label: "自定义", slotName: "customSlot" },
]

ProToolbar 插槽

| 插槽名 | 说明 | |--------|------| | left | 左侧按钮区末尾 | | right | 右侧按钮区末尾 | | filter | 筛选弹出框内容 |


设计原则

  1. 配置化驱动:通过 TypeScript 类型安全的配置对象描述页面,减少模板代码
  2. 按需使用:ProPage 是编排层,各子组件可独立使用
  3. 双引擎支持:vxe-table / el-table 一键切换,API 统一
  4. 插槽开放:所有渲染点都支持插槽覆盖,配置化与自定义并存
  5. 平滑迁移:API 设计与现有 CURD 组件对齐,迁移成本低