工具函数

配置定义函数

提供类型安全的配置定义辅助函数。

import {
  defineSearchConfig,
  defineFormConfig,
  defineColumnsConfig,
  defineApiConfig,
  definePermissions,
  defineTableOperations,
  defineOperateColumns,
  defineOptionsColumns,
  defineDescriptionsConfig
} from 'vue-admin-kit'

// 搜索配置
const searchConfig = defineSearchConfig([
  { type: 'input', prop: 'name', label: '名称' }
])

// 表单配置
const formConfig = defineFormConfig([
  { type: 'input', prop: 'name', label: '名称', required: true }
])

// 列配置
const columnsConfig = defineColumnsConfig([
  { field: 'name', title: '名称' }
])

// API 配置
const api = defineApiConfig({
  list: listApi,
  add: addApi,
  edit: editApi,
  delete: deleteApi,
  detail: detailApi
})

// 权限配置
const permissions = definePermissions({
  add: ['system:user:add'],
  edit: ['system:user:edit'],
  delete: ['system:user:remove']
})

// 工具栏按钮配置
const toolbarConfig = defineTableOperations([
  { title: '新增', icon: 'Plus', type: 'primary', onClick: handleAdd }
])

// 行操作按钮配置
const operateConfig = defineOperateColumns([
  { title: '编辑', onClick: handleEdit },
  { title: '删除', type: 'danger', onClick: handleDelete }
])

// Descriptions 配置
const descConfig = defineDescriptionsConfig([
  { title: '基本信息', children: [...] }
])

条件显示函数

用于操作按钮的条件显示。

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

// 单条件：status 等于 '1' 时显示
show: showWhen("status", "1");

// 多值匹配：status 为 '1' 或 '2' 时显示
show: showWhenIn("status", ["1", "2"]);

// AND 组合：status 为 '1' 且 role 为 'admin' 时显示
show: showAll(showWhen("status", "1"), showWhen("role", "admin"));

// OR 组合：status 为 '1' 或 isSuper 为 true 时显示
show: showAny(showWhen("status", "1"), showWhen("isSuper", true));

配置工具函数

列配置工具

import {
  col,
  withUnit,
  registerColumnConfig,
  registerColumnConfigs,
  getColumnConfig,
  clearColumnConfigs,
} from "vue-admin-kit";

// 创建列配置
const seqCol = col("序号", { type: "seq", minWidth: 100 });

// 带单位格式化
const priceCol = col("价格", { field: "price", formatter: withUnit("元") });

// 注册单个配置
registerColumnConfig(seqCol);

// 批量注册
registerColumnConfigs([seqCol, priceCol]);

// 获取配置
const columns = getColumnConfig(["序号", "价格"]);
const columns2 = getColumnConfig([
  "序号",
  ["价格", { minWidth: 120 }], // 覆盖属性
]);

// 清除所有配置
clearColumnConfigs();

表单配置工具

import {
  formCol,
  registerFormConfig,
  registerFormConfigs,
  getFormConfig,
  clearFormConfigs,
} from "vue-admin-kit";

// 创建表单配置
const nameCol = formCol("名称", {
  prop: "name",
  type: "input",
  required: true,
});

// 注册配置
registerFormConfigs([nameCol]);

// 获取配置
const formConfig = getFormConfig(["名称"]);
const formConfig2 = getFormConfig([
  ["名称", { span: 24 }], // 覆盖属性
]);

搜索配置工具

import {
  searchCol,
  registerSearchConfig,
  registerSearchConfigs,
  getSearchConfig,
  clearSearchConfigs,
  baseSearchConfigs,
} from "vue-admin-kit";

// 创建搜索配置
const nameSearch = searchCol("名称搜索", { prop: "name", type: "input" });

// 注册配置
registerSearchConfigs([nameSearch]);

// 获取配置
const searchConfig = getSearchConfig(["名称搜索"]);

// 访问基础配置（只读）
console.log(baseSearchConfigs); // Map<string, SearchConfigItem>

基础配置导出

组件库导出了三个基础配置 Map，用于查看已注册的配置：

import {
  baseColumnConfigs,
  baseFormConfigs,
  baseSearchConfigs,
} from "vue-admin-kit";

// 查看已注册的列配置
console.log(baseColumnConfigs); // Map<string, ColumnConfigItem>

// 查看已注册的表单配置
console.log(baseFormConfigs); // Map<string, FormConfigItem>

// 查看已注册的搜索配置
console.log(baseSearchConfigs); // Map<string, SearchConfigItem>

响应格式化

import { formatterRes, formatterListRes, checkRes } from "vue-admin-kit";

// 格式化通用响应（支持 {code, data} 和 [err, data] 两种格式）
const data = formatterRes(response);

// 格式化列表响应（自动提取 rows 和 total）
const { rows, total } = formatterListRes(response);

// 检查响应结果（自动处理错误提示）
if (checkRes(response, { logger: console })) {
  // 处理成功逻辑
}

// 带自定义校验器
if (
  checkRes(response, {
    logger: console,
    validator: (data) => {
      // 返回 false 或抛出错误均视为校验失败
      if (!data.rows?.length) {
        throw new Error("数据为空");
      }
      return true;
    },
    onError: ({ message, response }) => {
      // 自定义错误处理
      console.error(message);
    },
  })
) {
  // 处理成功逻辑
}

checkRes 选项

interface CheckResOptions {
  logger: Logger; // 日志器，需包含 error 方法
  onError?: (context: { message: string; response: any }) => void; // 错误回调
  validator?: (data: any) => boolean | void; // 数据校验函数
}

验证工具

import {
  isPathMatch,
  isHttp,
  isExternal,
  validURL,
  validEmail,
  validPhone,
  validLowerCase,
  validUpperCase,
  validAlphabets,
  isString,
  isArray,
  isEmpty,
  isNotEmpty,
} from "vue-admin-kit";

// 路径匹配（支持通配符）
isPathMatch("/api/**", "/api/user/list"); // true
isPathMatch("/user/*", "/user/123"); // true

// URL 类型判断
isHttp("https://example.com"); // true
isExternal("mailto:test@example.com"); // true

// 格式验证
validURL("https://www.example.com"); // true
validEmail("test@example.com"); // true
validPhone("13812345678"); // true
validLowerCase("abc"); // true
validUpperCase("ABC"); // true
validAlphabets("abcABC"); // true

// 类型判断
isString("hello"); // true
isArray([1, 2, 3]); // true
isEmpty(null); // true
isEmpty(""); // true
isEmpty([]); // true
isEmpty({}); // true
isNotEmpty("hello"); // true

文件工具

import { downloadFile, handleFileChangeExcel } from "vue-admin-kit";

// 下载文件
await downloadFile(api.downloadTemplate, "导入模板");
await downloadFile(() => api.exportUsers({ status: "1" }), "用户列表", "xlsx");
await downloadFile(() => api.downloadContract(id), "合同文件", "pdf");
await downloadFile(() => api.downloadBatch(ids), "批量下载", "zip");

// 选择 Excel 文件
const file = await handleFileChangeExcel();
if (file) {
  const formData = new FormData();
  formData.append("file", file);
  await importApi(formData);
}

权限检查

import {
  hasPermission,
  hasRole,
  configurePermissionDirective,
  registerPermissionDirectives,
} from "vue-admin-kit";

// 配置权限数据源
configurePermissionDirective({
  getPermissions: () => useUserStore().permissions,
  getRoles: () => useUserStore().roles,
  superPermission: "*:*:*",
  superRoles: ["superadmin", "admin"],
});

// 注册指令
registerPermissionDirectives(app);

// 编程式检查
if (hasPermission(["system:user:add"])) {
  // 有权限
}

if (hasRole(["admin"])) {
  // 是管理员
}

字典管理

import {
  DictManager,
  getDictManager,
  resetDictManager,
  getCustomAdapter,
  getAllCustomAdapters,
  hasCustomAdapter,
} from "vue-admin-kit";

// 获取字典管理器实例
const manager = getDictManager();

// 预加载字典
await manager.preload(["sys_status", "sys_yes_no"]);

// 获取字典数据
const data = manager.get("sys_status");

// 设置字典数据
manager.set("sys_status", [
  { label: "启用", value: "1" },
  { label: "禁用", value: "0" },
]);

// 清除缓存
manager.clear("sys_status");
manager.clearAll();

// 重置管理器
resetDictManager();

// 自定义适配器
const adapter = getCustomAdapter("user_list");
const allAdapters = getAllCustomAdapters();
const hasAdapter = hasCustomAdapter("user_list");

配置管理函数

providePageTemplateConfig

设置或合并全局配置，多次调用会深度合并。

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

// 初始化配置
providePageTemplateConfig({
  ui: { formItemSize: "default" },
  dependencies: { dictLoader, oss },
  dict: { preload: true, commonTypes: ["sys_status"] },
});

// 后续合并配置（会与之前的配置深度合并）
providePageTemplateConfig({
  dependencies: { customAdapters: { user_list: {...} } }
});

usePageTemplateConfig

获取当前全局配置。

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

const config = usePageTemplateConfig();
console.log(config.ui.formItemSize);
console.log(config.dependencies.dictLoader);

resetPageTemplateConfig

重置配置为默认值，主要用于测试场景。

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

// 重置为默认配置
resetPageTemplateConfig();

// 重置并应用新配置
resetPageTemplateConfig({
  ui: { formItemSize: "small" },
});

确认操作

import { confirmAction, createStatusToggle } from "vue-admin-kit";

// 确认操作
await confirmAction("确定删除吗？", deleteFn);
await confirmAction("确定提交吗？", submitFn, "提交成功");

// 创建状态切换函数
const toggleStatus = createStatusToggle(updateStatusApi, refreshList);
await toggleStatus(id, "0", "确定下架吗？");