常见问题

安装与配置

安装后样式不生效？

确保在 main.ts 中引入了样式文件：

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

字典数据加载失败？

检查 setupPageTemplate 中的 dictLoader 配置：

setupPageTemplate({
  dependencies: {
    dictLoader: async (dictType) => {
      const res = await getDicts(dictType);
      // 确保返回格式正确
      return {
        success: true,
        data: res.data.map((item) => ({
          label: item.dictLabel,
          value: item.dictValue,
          elTagType: item.listClass,
        })),
        fromCache: false,
        loadTime: 0,
      };
    },
  },
});

上传组件报错 "oss 未配置"？

Upload 和 UploadCard 组件需要配置 OSS API：

setupPageTemplate({
  dependencies: {
    oss: {
      uploadOSS: async (file) => {
        const res = await uploadApi(file);
        return {
          url: res.data.url,
          fileName: res.data.fileName,
          ossId: res.data.ossId,
        };
      },
      deleteOSS: async (ossId) => {
        const res = await deleteApi(ossId);
        return { code: res.code, msg: res.msg };
      },
    },
  },
});

组件使用

表格高度计算不正确？

1. 检查是否配置了 calculateHeight：

setupPageTemplate({
  dependencies: {
    calculateHeight: (formHeight, otherHeight = 0) => {
      return window.innerHeight - formHeight - otherHeight - 200;
    },
  },
});

2. 如果页面有额外元素，使用 otherHeight 属性：

<Table :otherHeight="40" />

多表格场景高度互相干扰？

使用 instanceKey 隔离各表格实例：

<PageTemplate :instance-key="Symbol('table1')">
  <template #table>
    <Table />
  </template>
</PageTemplate>

表单验证不触发？

确保配置了 required 或 rules：

const formConfig = [
  // 简单必填
  { type: "input", prop: "name", label: "名称", required: true },

  // 自定义规则
  {
    type: "input",
    prop: "phone",
    label: "手机号",
    rules: [
      { required: true, message: "请输入手机号", trigger: "blur" },
      {
        pattern: /^1[3-9]\d{9}$/,
        message: "手机号格式不正确",
        trigger: "blur",
      },
    ],
  },
];

下拉选项不显示？

检查字典类型是否正确，或使用静态 options：

// 使用字典
{ type: 'select', prop: 'status', dictType: 'sys_status' }

// 使用静态选项
{
  type: 'select',
  prop: 'type',
  options: [
    { label: '类型A', value: 'a' },
    { label: '类型B', value: 'b' }
  ]
}

操作按钮不显示？

检查 show 条件或权限配置：

{
  title: '编辑',
  onClick: handleEdit,
  // 条件显示
  show: showWhen('status', '1'),
  // 权限控制
  hasPermi: ['system:user:edit']
}

字典相关

如何预加载常用字典？

在配置中设置预加载：

setupPageTemplate({
  dict: {
    preload: true,
    commonTypes: ["sys_status", "sys_yes_no", "sys_user_sex"],
  },
});

或手动预加载：

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

await preloadDicts(["sys_status", "sys_yes_no"]);

如何清除字典缓存？

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

// 清除单个
clearDictCache("sys_status");

// 清除全部
clearDictCache();

自定义适配器不生效？

确保在 setupPageTemplate 中注册：

setupPageTemplate({
  dependencies: {
    customAdapters: {
      user_list: {
        api: () => getUserList(),
        transform: (res) =>
          res.data.map((item) => ({
            label: item.name,
            value: String(item.id),
          })),
      },
    },
  },
});

权限相关

权限指令不生效？

1. 确保配置了权限数据源：

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

configurePermissionDirective({
  getPermissions: () => useUserStore().permissions,
  getRoles: () => useUserStore().roles,
});

2. 确保注册了指令：

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

registerPermissionDirectives(app);

超级管理员如何跳过权限检查？

配置 superPermission 或 superRoles：

configurePermissionDirective({
  getPermissions: () => useUserStore().permissions,
  getRoles: () => useUserStore().roles,
  superPermission: "*:*:*",
  superRoles: ["superadmin"],
});

TypeScript 相关

类型提示不正确？

确保正确导入类型：

import type {
  SearchConfigItem,
  FormConfigItem,
  ColumnConfigItem,
  PageTemplateExposed,
} from "vue-admin-kit";

defineXxxConfig 没有类型提示？

使用辅助函数包装配置：

import {
  defineSearchConfig,
  defineFormConfig,
  defineColumnsConfig,
} from "vue-admin-kit";

const searchConfig = defineSearchConfig([
  // 这里会有完整的类型提示
]);

性能相关

页面加载慢？

1. 预加载常用字典
2. 使用配置工具复用配置
3. 避免在 columnsConfig 中使用复杂的 formatter

表格渲染卡顿？

1. 减少列数量
2. 使用固定宽度而非 minWidth
3. 避免在单元格中渲染复杂组件