快速开始

安装

npm install vue-admin-kit
# 或
pnpm add vue-admin-kit

依赖要求

需要安装以下 peerDependencies：

{
  "vue": "^3.4.0",
  "element-plus": "^2.0.0",
  "vxe-pc-ui": "^4.0.0",
  "vxe-table": "^4.0.0",
  "xe-utils": "^3.0.0",
  "@element-plus/icons-vue": "^2.0.0",
  "@vueuse/core": "^10.0.0"
}

引入样式

// main.ts
import "vue-admin-kit/style.css";

初始化配置

// src/config/pageTemplate/index.ts
import { setupPageTemplate } from "vue-admin-kit";
import { getDicts } from "@/api/system/dict/data";
import { uploadOSS, deleteOSS } from "@/api/system/oss";

export function setupPageTemplateConfig() {
  setupPageTemplate({
    ui: {
      formItemSize: "default", // 'small' | 'default' | 'large'
    },
    dependencies: {
      // 字典加载器
      dictLoader: async (dictType) => {
        const res = await getDicts(dictType);
        const data = (res.data || []).map((item: any) => ({
          label: item.dictLabel,
          value: item.dictValue,
          elTagType: item.listClass,
          raw: item,
        }));
        return { success: true, data, fromCache: false, loadTime: 0 };
      },
      // OSS 文件上传/删除 API
      oss: {
        uploadOSS: async (file: File | FormData) => {
          const formData =
            file instanceof FormData
              ? file
              : (() => {
                  const fd = new FormData();
                  fd.append("files", file);
                  return fd;
                })();
          const res = await uploadOSS(formData);
          return {
            url: res.data?.url || "",
            fileName: res.data?.fileName || "",
            ossId: res.data?.ossId || "",
          };
        },
        deleteOSS: async (ossId: string | number) => {
          const res = await deleteOSS(ossId);
          return { code: res.code, msg: res.msg };
        },
      },
      // 表格高度计算（可选）
      calculateHeight: (formHeight, otherHeight = 0) => {
        return window.innerHeight - formHeight - otherHeight - 200;
      },
    },
    // 字典预加载配置（可选）
    dict: {
      preload: true,
      commonTypes: ["sys_status", "sys_yes_no"],
      cacheTime: 24 * 60 * 60 * 1000, // 24小时
    },
    // VXE-Table 全局配置（可选）
    VXETableConfig: {
      size: "medium",
      zIndex: 3000,
      table: {
        border: true,
        stripe: true,
        showOverflow: true,
      },
      grid: {
        toolbarConfig: {
          refresh: true,
          zoom: true,
        },
      },
    },
  });
}

VXETableConfig 说明

VXETableConfig 用于配置 VXE-Table 的全局选项，会调用 VXETable.setConfig() 进行设置。常用配置：

VXETableConfig: {
  size: 'medium',           // 全局尺寸
  zIndex: 3000,             // 弹窗层级
  table: {
    border: true,           // 边框
    stripe: true,           // 斑马纹
    showOverflow: true,     // 溢出隐藏
    highlightHoverRow: true // 高亮悬停行
  },
  grid: {
    toolbarConfig: {
      refresh: true,        // 刷新按钮
      zoom: true            // 全屏按钮
    }
  }
}

在 main.ts 中调用

// main.ts
import { setupPageTemplateConfig } from "@/config/pageTemplate";

// 在 app.use(store) 之后调用
setupPageTemplateConfig();

基础用法

<script setup lang="ts">
import { useState, PageTemplate, Table } from "vue-admin-kit";
import type { PageTemplateExposed } from "vue-admin-kit";

const pageTemplateRef = ref<PageTemplateExposed>();

useState({
  api: {
    list: (params) => getList(params),
    add: (data) => addItem(data),
    edit: (data) => updateItem(data),
    delete: (id) => deleteItem(id),
    detail: (id) => getDetail(id),
  },
  searchConfig: [
    { type: "input", prop: "name", label: "名称" },
    { type: "select", prop: "status", label: "状态", dictType: "sys_status" },
  ],
  formConfig: [
    { type: "input", prop: "name", label: "名称", required: true },
    { type: "select", prop: "status", label: "状态", dictType: "sys_status" },
  ],
  columnsConfig: [
    { field: "name", title: "名称" },
    { field: "status", title: "状态", dictType: "sys_status" },
  ],
  tableOptions: {
    operateColumns: [
      {
        title: "编辑",
        onClick: (row) => pageTemplateRef.value?.handleEdit(row),
      },
      {
        title: "删除",
        onClick: (row) => pageTemplateRef.value?.handleDelete(row),
      },
    ],
  },
});
</script>

<template>
  <PageTemplate ref="pageTemplateRef">
    <template #table>
      <Table />
    </template>
  </PageTemplate>
</template>