配置

本文档详细介绍 vue-admin-kit 的各项配置，包含每个参数的完整示例。

搜索配置 (searchConfig)

搜索配置用于定义搜索表单的字段，支持多种组件类型。

完整参数示例

import { defineSearchConfig } from "vue-admin-kit";

const searchConfig = defineSearchConfig([
  // ========== 输入框 ==========
  {
    type: "input",
    prop: "customerName",        // 字段名（必填）
    label: "客户名称",            // 标签文本
    span: 8,                     // 栅格占比（24栅格系统，默认8）
    placeholder: "请输入客户名称", // 占位文本
    defaultValue: "",            // 默认值
    disabled: false,             // 是否禁用
    labelWidth: "100px",         // 标签宽度
    show: true,                  // 是否显示（支持函数）
  },

  // ========== 下拉选择（字典） ==========
  {
    type: "select",
    prop: "status",
    label: "状态",
    dictType: "sys_status",      // 字典类型（从 DictManager 获取）
    filterable: true,            // 是否可搜索
    multiple: false,             // 是否多选
    placeholder: "请选择状态",
  },

  // ========== 下拉选择（静态选项） ==========
  {
    type: "select",
    prop: "category",
    label: "分类",
    options: [                   // 静态选项列表
      { label: "全部", value: "" },
      { label: "分类A", value: "a" },
      { label: "分类B", value: "b" },
    ],
    filterable: true,
  },

// ========== 下拉选择（远程搜索） ========== { type: "select", prop: "userId", label: "负责人", dictType: "user_list", // 自定义适配器 filterable: true, remote: true, // 开启远程搜索 remoteParam: "userName", // 搜索关键词参数名 },

// ========== 日期选择 ========== { type: "date", prop: "createDate", label: "创建日期", dateType: "date", // 日期类型：date/datetime/daterange/datetimerange/month/year/week },

// ========== 日期范围 ========== { type: "date", prop: "dateRange", label: "日期范围", dateType: "daterange", span: 12, // 日期范围通常需要更宽 },

// ========== 时间选择 ========== { type: "time", prop: "workTime", label: "工作时间", timeFormat: "HH:mm", // 时间格式：HH:mm:ss/HH:mm/mm:ss },

// ========== 数字输入 ========== { type: "number", prop: "minPrice", label: "最低价格", min: 0, // 最小值 max: 999999, // 最大值 precision: 2, // 小数位数 },

// ========== 条件显示 ========== { type: "input", prop: "remark", label: "备注", // 函数形式：根据其他参数动态显示 show: (params) => params.status === "1", }, ]);

表单配置 (formConfig)

表单配置用于定义新增/编辑弹窗的表单字段。

完整参数示例

import { defineFormConfig } from "vue-admin-kit";

const formConfig = defineFormConfig([
  // ========== 输入框 ==========
  {
    type: "input",
    prop: "name",                // 字段名（必填）
    label: "名称",               // 标签文本
    span: 12,                    // 栅格占比（24栅格，默认12）
    required: true,              // 是否必填
    placeholder: "请输入名称",
    defaultValue: "",            // 新增时的默认值
    disabled: false,             // 是否禁用
    readonly: false,             // 是否只读
    editDisabled: false,         // 编辑时禁用（新增可用）
    rules: [                     // 自定义校验规则
      { min: 2, max: 50, message: "长度在 2 到 50 个字符", trigger: "blur" },
      { pattern: /^[a-zA-Z0-9]+$/, message: "只能包含字母和数字", trigger: "blur" },
    ],
    suffix: "",                  // 后缀内容
    suffixType: "text",          // 后缀类型：text/icon/component
  },

  // ========== 动态必填 ==========
  {
    type: "input",
    prop: "reason",
    label: "原因",
    // 函数形式：根据表单数据动态判断是否必填
    required: ({ formData }) => formData.status === "0",
  },

  // ========== 多行文本 ==========
  {
    type: "textarea",
    prop: "description",
    label: "描述",
    span: 24,                    // 占满一行
    rows: 4,                     // 显示行数
    placeholder: "请输入详细描述",
  },

// ========== 数字输入 ========== { type: "number", prop: "price", label: "价格", span: 12, required: true, min: 0, // 最小值 max: 999999.99, // 最大值 precision: 2, // 小数位数 step: 0.01, // 步长 stepStrictly: false, // 是否只能输入步长的倍数 suffix: "元", // 后缀文本 width: "200px", // 组件宽度 defaultValue: 0, },

// ========== 下拉选择（字典） ========== { type: "select", prop: "status", label: "状态", dictType: "sys_status", // 字典类型 required: true, filterable: true, // 可搜索 multiple: false, // 是否多选 defaultValue: "1", // 默认值 },

// ========== 下拉选择（静态选项） ========== { type: "select", prop: "type", label: "类型", options: [ { label: "类型 A", value: "a" }, { label: "类型 B", value: "b" }, { label: "类型 C", value: "c" }, ], multiple: true, // 多选 filterable: true, },

// ========== 下拉选择（带变化回调） ========== { type: "select", prop: "provinceId", label: "省份", dictType: "province_list", // 值变化时的回调 change: ({ pageData, formData, value, dictItem }) => { // 清空城市选择 formData.cityId = ""; // 可以访问选中项的完整数据 console.log("选中省份:", dictItem.label, dictItem.raw); }, },

// ========== 单选框 ========== { type: "radio", prop: "sex", label: "性别", dictType: "sys_user_sex", // 使用字典 required: true, defaultValue: "1", },

// ========== 单选框（静态选项） ========== { type: "radio", prop: "isVip", label: "是否 VIP", options: [ { label: "是", value: "1" }, { label: "否", value: "0" }, ], defaultValue: "0", },

// ========== 日期选择 ========== { type: "date", prop: "birthday", label: "生日", dateType: "date", // date/datetime/daterange/datetimerange/month/year/week },

// ========== 日期时间选择 ========== { type: "date", prop: "appointmentTime", label: "预约时间", dateType: "datetime", required: true, },

// ========== 时间选择 ========== { type: "time", prop: "workStartTime", label: "上班时间", timeFormat: "HH:mm", // HH:mm:ss/HH:mm/mm:ss },

// ========== 分割线 ========== { type: "line", label: "附件信息", // 分割线标题 span: 24, },

// ========== 分割线（带按钮） ========== { type: "line", label: "联系人信息", btnTitle: "添加联系人", // 按钮文本 btnClick: ({ formData }) => { // 点击按钮的回调 formData.contacts = formData.contacts || []; formData.contacts.push({ name: "", phone: "" }); }, },

// ========== 文件上传 ========== { type: "upload", prop: "files", label: "附件", span: 24, uploadConfigList: [ { prop: "contractFile", // 字段名 label: "合同文件", // 标签 bizType: "contract", // 业务类型 limit: 5, // 最大文件数 accept: ".pdf,.doc,.docx", // 允许的文件类型 multiple: true, // 是否支持多选 drag: false, // 是否启用拖拽上传 required: true, // 是否必填 disabled: false, // 是否禁用 compress: false, // 是否压缩图片 }, ], },

// ========== 卡片式上传（图片） ========== { type: "uploadCard", prop: "images", label: "图片", span: 24, uploadConfigList: [ { prop: "coverImage", label: "封面图", bizType: "cover", limit: 1, accept: "image/*", required: true, }, { prop: "gallery", label: "图片集", bizType: "gallery", limit: 9, accept: ".jpg,.jpeg,.png,.gif", compress: true, // 压缩图片 }, ], },

// ========== 富文本编辑器 ========== { type: "editor", prop: "content", label: "详细内容", span: 24, required: true, },

// ========== 输入组 ========== { type: "inputGroup", prop: "address", label: "地址", span: 24, children: [ { type: "input", prop: "province", label: "省" }, { type: "input", prop: "city", label: "市" }, { type: "input", prop: "district", label: "区" }, { type: "input", prop: "detail", label: "详细地址" }, ], },

// ========== 条件显示 ========== { type: "input", prop: "rejectReason", label: "拒绝原因", span: 24, required: ({ formData }) => formData.auditStatus === "2", // 仅当审核状态为"拒绝"时显示 show: ({ formData }) => formData.auditStatus === "2", }, ]);

列配置 (columnsConfig)

列配置用于定义表格的列。

完整参数示例

import { defineColumnsConfig } from "vue-admin-kit";

const columnsConfig = defineColumnsConfig([
  // ========== 复选框列 ==========
  {
    type: "checkbox",            // 列类型
    width: 50,                   // 列宽度（固定）
    fixed: "left",               // 固定位置：left/right
  },

  // ========== 序号列 ==========
  {
    type: "seq",
    title: "序号",
    width: 60,
    fixed: "left",
  },

  // ========== 普通列 ==========
  {
    field: "customerName",       // 字段名
    title: "客户名称",           // 列标题
    minWidth: 150,               // 最小宽度（自适应）
    showOverflow: "tooltip",     // 溢出处理：true/false/'tooltip'
    align: "left",               // 对齐方式：left/center/right
    sortable: false,             // 是否可排序
  },

  // ========== 固定宽度列 ==========
  {
    field: "orderNo",
    title: "订单号",
    width: 180,                  // 固定宽度
    fixed: "left",               // 固定在左侧
  },

  // ========== 字典列（文本显示） ==========
  {
    field: "status",
    title: "状态",
    width: 100,
    dictType: "sys_status",      // 字典类型
    displayType: "text",         // 显示类型：text（默认）
  },

  // ========== 字典列（标签显示） ==========
  {
    field: "auditStatus",
    title: "审核状态",
    width: 100,
    dictType: "audit_status",
    displayType: "tag",          // 显示为带颜色的标签
  },

// ========== 自定义格式化 ========== { field: "price", title: "价格", width: 120, align: "right", formatter: ({ cellValue }) => { if (cellValue === null || cellValue === undefined) return "-"; return ¥${Number(cellValue).toFixed(2)}; }, },

// ========== 日期格式化 ========== { field: "createTime", title: "创建时间", width: 160, sortable: true, // 可排序 formatter: ({ cellValue }) => { if (!cellValue) return "-"; return new Date(cellValue).toLocaleString("zh-CN"); }, },

// ========== 条件显示列 ========== { field: "adminRemark", title: "管理员备注", minWidth: 200, // 仅管理员可见 show: ({ pageData }) => pageData.params?.isAdmin === true, },

// ========== 标签列 ========== { field: "customerName", title: "客户名称", minWidth: 200, tags: { field: "customerTags", // 标签数据来源字段 typeMap: { // 按文本映射标签类型 "VIP": "success", "高风险": "danger", "新客户": "info", "重点客户": "warning", }, max: 3, // 最多显示 3 个标签 size: "small", // 标签尺寸 effect: "light", // 标签主题：dark/light/plain }, },

// ========== 标签列（静态数据） ========== { field: "vipLevel", title: "VIP 等级", width: 120, tags: { data: [ // 静态标签数据 { label: "VIP", type: "success" }, ], }, },

// ========== 标签列（完整属性映射） ========== { field: "riskLevel", title: "风险等级", width: 120, tags: { field: "riskTags", propsMap: { // 按文本映射完整 Tag 属性 "高风险": { type: "danger", effect: "dark" }, "中风险": { type: "warning", effect: "light" }, "低风险": { type: "success", effect: "plain" }, }, }, }, ]);

API 配置

API 配置定义 CRUD 操作的接口。

完整参数示例

import { defineApiConfig } from "vue-admin-kit";

const api = defineApiConfig({
  // 列表查询（必填）
  list: (params) => request.get("/api/customer/list", { params }),

  // 新增
  add: (data) => request.post("/api/customer/add", data),

  // 编辑
  edit: (data) => request.put("/api/customer/edit", data),

  // 删除（单条）
  delete: (id) => request.delete(`/api/customer/delete/${id}`),

  // 详情
  detail: (id) => request.get(`/api/customer/detail/${id}`),

  // 批量删除
  batchDelete: (ids) =>
    request.delete("/api/customer/batch", { data: { ids } }),

  // 导出
  export: (params) =>
    request.get("/api/customer/export", {
      params,
      responseType: "blob",
    }),

  // 导入
  import: (formData) =>
    request.post("/api/customer/import", formData, {
      headers: { "Content-Type": "multipart/form-data" },
    }),
});

权限配置

权限配置定义各操作按钮的权限码。

完整参数示例

import { definePermissions } from "vue-admin-kit";

const permissions = definePermissions({
  add: ["system:customer:add"], // 新增权限
  edit: ["system:customer:edit"], // 编辑权限
  delete: ["system:customer:remove"], // 删除权限
  detail: ["system:customer:query"], // 详情权限
  batchDelete: ["system:customer:remove"], // 批量删除权限
  export: ["system:customer:export"], // 导出权限
  import: ["system:customer:import"], // 导入权限
  template: ["system:customer:import"], // 模板下载权限
  // 自定义权限
  audit: ["system:customer:audit"],
  assign: ["system:customer:assign"],
});

工具栏按钮配置

工具栏按钮显示在表格上方。

完整参数示例

import { defineTableOperations } from "vue-admin-kit";

const tableOperationConfig = defineTableOperations([
  // ========== 新增按钮 ==========
  {
    title: "新增", // 按钮文本
    type: "primary", // 按钮类型：primary/success/warning/danger/info
    icon: "Plus", // 图标名称（Element Plus 图标）
    fixed: "left", // 固定位置：left/right
    hasPermi: ["system:customer:add"], // 权限码
    onClick: () => {
      pageTemplateRef.value?.handleAdd();
    },
  },

  // ========== 批量删除按钮 ==========
  {
    title: "批量删除",
    type: "danger",
    icon: "Delete",
    fixed: "left",
    hasPermi: ["system:customer:remove"],
    // 条件显示：有选中数据时才显示
    show: (data) => data.checkTableData?.length > 0,
    onClick: (data) => {
      const rows = data.checkTableData;
      if (rows?.length) {
        pageTemplateRef.value?.handleDelete(rows);
      }
    },
  },

  // ========== 导出按钮 ==========
  {
    title: "导出",
    type: "warning",
    icon: "Download",
    fixed: "right",
    hasPermi: ["system:customer:export"],
    onClick: () => {
      pageTemplateRef.value?.downloadFile(api.export, "客户列表");
    },
  },

  // ========== 导入按钮 ==========
  {
    title: "导入",
    type: "info",
    icon: "Upload",
    fixed: "right",
    hasPermi: ["system:customer:import"],
    onClick: () => {
      pageTemplateRef.value?.importFile(api.import, "客户导入模板");
    },
  },
]);

行操作按钮配置

行操作按钮显示在表格每行的操作列。

完整参数示例

import {
  defineOperateColumns,
  showWhen,
  showWhenIn,
  showAll,
  showAny,
} from "vue-admin-kit";

const operateColumns = defineOperateColumns([
  // ========== 详情按钮 ==========
  {
    title: "详情",
    type: "info",                // 按钮类型
    link: true,                  // 链接样式
    onClick: (row) => {
      pageTemplateRef.value?.handleDetail(row);
    },
  },

  // ========== 编辑按钮（带权限和条件显示） ==========
  {
    title: "编辑",
    type: "primary",
    link: true,
    hasPermi: ["system:customer:edit"],  // 权限控制
    hasRole: ["admin", "manager"],       // 角色控制（可选）
    // 条件显示：状态为"正常"时显示
    show: showWhen("status", "1"),
    onClick: (row) => {
      pageTemplateRef.value?.handleEdit(row);
    },
  },

  // ========== 删除按钮 ==========
  {
    title: "删除",
    type: "danger",
    link: true,
    hasPermi: ["system:customer:remove"],
    // 条件显示：状态为"正常"或"停用"时显示
    show: showWhenIn("status", ["0", "1"]),
    onClick: (row) => {
      pageTemplateRef.value?.handleDelete(row);
    },
  },

  // ========== 启用按钮 ==========
  {
    title: "启用",
    type: "success",
    link: true,
    hasPermi: ["system:customer:edit"],
    // 仅状态为"停用"时显示
    show: showWhen("status", "0"),
    onClick: (row) => {
      toggleStatus(row.id, "1", "确定启用该客户吗？");
    },
  },

  // ========== 停用按钮 ==========
  {
    title: "停用",
    type: "warning",
    link: true,
    hasPermi: ["system:customer:edit"],
    // 仅状态为"正常"时显示
    show: showWhen("status", "1"),
    onClick: (row) => {
      toggleStatus(row.id, "0", "确定停用该客户吗？");
    },
  },

// ========== 组合条件（AND） ========== { title: "高级编辑", type: "primary", link: true, // 状态为"正常" 且 是 VIP 客户 时显示 show: showAll( showWhen("status", "1"), (data) => data.row?.isVip === true ), onClick: (row) => handleAdvancedEdit(row), },

// ========== 组合条件（OR） ========== { title: "特殊操作", type: "warning", link: true, // 是管理员 或 是创建者 时显示 show: showAny( (data) => data.params?.isAdmin === true, (data) => data.row?.createBy === currentUser.value ), onClick: (row) => handleSpecialAction(row), },

// ========== 下拉菜单 ========== { title: "更多", dropdown: true, // 启用下拉菜单 children: [ { title: "复制", onClick: (row) => handleCopy(row), }, { title: "转移", onClick: (row) => handleTransfer(row), hasPermi: ["system:customer:transfer"], }, { title: "归档", type: "warning", onClick: (row) => handleArchive(row), show: showWhen("status", "1"), }, ], }, ]);