类型定义

导入类型

import type {
  // 配置类型
  SearchConfigItem,
  FormConfigItem,
  FormDialogConfigItem,
  ColumnConfigItem,
  PermissionConfig,
  ConfigOptions,

  // 组件类型
  SelectComponentDictType,
  SelectType,
  RadioComponentDictType,
  UploadComponent,
  SelectChange as SelectChangeConfig,
  BaseConfigItem,

  // 表格类型
  TableColumn,
  OperateColumn,
  OperateColumnBase,
  OperateColumnDropdown,
  TableOptions,
  VxeGridType,
  pageDataType,

  // 配置类型
  PageTemplateConfig,
  PageTemplateDependencies,
  PageTemplateDictOptions,
  PageTemplateUIOptions,
  PageTemplateExposed,
  InternalConfig,
  FormItemSizeType,
  CalculateHeightFn,

  // 字典类型
  DictAdapterConfig,
  DictDataOption,
  DictLoadOptions,
  DictLoadResult,
  DictStoreState,
  DictStoreStats,
  DictConfig,
  DictApiMap,
  DictTypeConstants,

  // 标签类型
  TagType,
  TagItem,
  TagData,
  TagConfig,

  // 权限类型
  PermissionGetter,
  RoleGetter,
  PermissionDirectiveConfig,

  // Hook 类型
  UseDialogOptions,
  UseDialogReturn,
  ConfirmOptions,
  ConfirmType,
  UseTableHeightOptions,
  TableHeightState,

  // useState 类型
  UseStateOptions,
  UseStateHandlers,
  UseStateLogger,
  UseStateErrorContext,
  UseStateSuccessContext,
  ActionType,
  CheckResOptions,
  WrappedConfig,
  MaybeConfig,
  ParamsProvider,

  // API 类型
  ApiResponse,
  OssUploadResult,
  OssApi,
  ComponentLibraryApis,
  PaginationConfig,
  QueryParams,
  ApiConfig,

  // Descriptions 类型
  DescriptionItemType,
  DescriptionItemConfig,
  DescriptionSectionConfig,
  FileItem,
} from "vue-admin-kit";

配置类型

SearchConfigItem

搜索配置项类型。

interface SearchConfigItem {
  type: "input" | "select" | "date" | "number" | "textarea" | "radio" | "time";
  prop: string;
  label: string;
  span?: number;
  placeholder?: string;
  dictType?: string;
  options?: DictDataOption[];
  filterable?: boolean;
  multiple?: boolean;
  remote?: boolean;
  remoteParam?: string;
  dateType?: "date" | "datetime" | "daterange" | "datetimerange";
  timeFormat?: "HH:mm:ss" | "HH:mm";
}

FormConfigItem

表单配置项类型。

interface FormConfigItem {
  type: string;
  prop: string;
  label: string;
  span?: number;
  required?: boolean;
  rules?: any[];
  dictType?: string;
  options?: DictDataOption[];
  // 数字类型
  min?: number;
  max?: number;
  precision?: number;
  step?: number;
  suffix?: string;
  suffixType?: string;
  // 上传类型
  uploadConfigList?: UploadConfig[];
  // 日期类型
  dateType?: string;
  // 时间类型
  timeFormat?: string;
  // 多行输入
  rows?: number;
  // 分割线
  btnClick?: () => void;
  btnTitle?: string;
  // 输入组
  children?: FormConfigItem[];
}

ColumnConfigItem

列配置项类型。

interface ColumnConfigItem {
  type?: "checkbox" | "seq";
  field?: string;
  title?: string;
  width?: number;
  minWidth?: number;
  fixed?: "left" | "right";
  sortable?: boolean;
  dictType?: string;
  displayType?: "text" | "tag";
  formatter?: (params: any) => string;
  tags?: TagConfig;
}

ConfigOptions

useState 配置选项类型。

interface ConfigOptions {
  api: {
    list?: (params: any) => Promise<any>;
    add?: (data: any) => Promise<any>;
    edit?: (data: any) => Promise<any>;
    delete?: (id: any) => Promise<any>;
    detail?: (id: any) => Promise<any>;
    batchDelete?: (ids: any[]) => Promise<any>;
    export?: (params: any) => Promise<any>;
    import?: (file: any) => Promise<any>;
  };
  searchConfig?: SearchConfigItem[];
  formConfig?: FormConfigItem[];
  columnsConfig?: ColumnConfigItem[];
  tableOptions?: TableOptions;
}

组件类型

PageTemplateExposed

PageTemplate 组件暴露的方法。

interface PageTemplateExposed {
  handleAdd: (data?: object, row?: object) => void;
  handleEdit: (row: object) => void;
  handleDetail: (row: object) => void;
  handleDelete: (row: object | object[]) => void;
  handleSearch: () => void;
  handleReset: () => void;
  importFile: (
    api: Function,
    templateName: string,
    successCallback?: Function
  ) => void;
  downloadFile: (api: Function, fileName: string) => void;
}

OperateColumn

操作列配置类型。

interface OperateColumn {
  title: string;
  type?: "primary" | "success" | "warning" | "danger" | "info";
  link?: boolean;
  icon?: string;
  onClick: (row: any) => void;
  show?: (data: { row: any; params: any }) => boolean;
  hasPermi?: string[];
  hasRole?: string[];
  fixed?: "left" | "right";
}

TableOptions

表格选项类型。

interface TableOptions {
  tableOperationConfig?: OperateColumn[];
  operateColumns?: OperateColumn[];
}

字典类型

DictDataOption

字典选项类型。

interface DictDataOption {
  label: string;
  value: string;
  elTagType?: "success" | "warning" | "danger" | "info" | "";
  raw?: any;
}

DictAdapterConfig

字典适配器配置类型。

interface DictAdapterConfig {
  api: () => Promise<any>;
  params?: () => Record<string, any>;
  transform: (response: any) => DictDataOption[];
}

DictLoadResult

字典加载结果类型。

interface DictLoadResult {
  success: boolean;
  data: DictDataOption[];
  fromCache: boolean;
  loadTime: number;
}

Hook 类型

UseDialogOptions

useDialog Hook 选项类型。

interface UseDialogOptions {
  title?: string;
  visible?: boolean;
}

UseDialogReturn

useDialog Hook 返回类型。

interface UseDialogReturn {
  visible: Ref<boolean>;
  title: Ref<string>;
  openDialog: (newTitle?: string) => void;
  closeDialog: () => void;
  toggleDialog: () => void;
  setTitle: (newTitle: string) => void;
}

ConfirmOptions

确认操作选项类型。

interface ConfirmOptions {
  title?: string;
  type?: "warning" | "info" | "success" | "error";
  confirmButtonText?: string;
  cancelButtonText?: string;
}

type ConfirmType = "success" | "warning" | "info" | "error";

UseTableHeightOptions

表格高度 Hook 选项类型。

interface UseTableHeightOptions {
  instanceKey?: string | symbol;
}

interface TableHeightState {
  height: number;
  initialized: boolean;
}

CheckResOptions

响应检查选项类型。

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

UseStateOptions

useState Hook 配置选项类型。

interface UseStateOptions<TEntity = any, TSearchParams = any> {
  params?: Partial<TSearchParams>; // 初始查询参数
  tableOptions?: Record<string, any>; // 表格配置
  searchConfig?: MaybeConfig<SearchConfigItem[]>; // 搜索配置
  formConfig?: MaybeConfig<FormConfigItem[]>; // 表单配置
  columnsConfig?: ColumnConfigItem[]; // 列配置
  provideName?: string; // provide 名称
  requestHandlers?: UseStateHandlers; // 请求处理器
  logger?: UseStateLogger; // 日志器
  transformParams?: (params: TSearchParams) => any; // 参数转换钩子
  transformResponse?: (response: any) => { rows: TEntity[]; total: number }; // 响应转换钩子
}

UseStateHandlers

请求处理器类型。

interface UseStateHandlers {
  onError?: (context: UseStateErrorContext) => void;
  onSuccess?: (context: UseStateSuccessContext) => void;
}

interface UseStateErrorContext {
  action: ActionType; // 'list' | 'delete' | 'add' | 'update'
  params?: Record<string, any>;
  error?: unknown;
  response?: any;
  message?: string;
}

interface UseStateSuccessContext {
  action: ActionType;
  params?: Record<string, any>;
  response: any;
}

type ActionType = "list" | "delete" | "add" | "update";

标签类型

TagConfig

标签配置类型。

interface TagConfig extends Partial<TagProps> {
  data?: TagData; // 静态标签数据
  field?: string; // 标签数据来源字段
  labelKey?: string; // 标签文本字段名，默认 'label'
  typeKey?: string; // 标签类型字段名，默认 'type'
  typeMap?: Record<string, TagType>; // 按文本映射类型
  propsMap?: Record<string, Partial<TagProps>>; // 按文本映射完整属性
  max?: number; // 最大显示数量
}

type TagType = "primary" | "success" | "warning" | "danger" | "info";
type TagData = string | string[] | TagItem[];

interface TagItem extends Partial<TagProps> {
  label: string; // 标签文本（必填）
}

使用示例

// 静态标签
const config: TagConfig = {
  data: [{ label: "VIP", type: "success" }],
};

// 从字段读取
const config: TagConfig = { field: "tagList" };

// 按文本映射类型
const config: TagConfig = {
  field: "riskTags",
  typeMap: { 高风险: "danger", VIP: "success" },
};

// 在列配置中使用
const columnsConfig = defineColumnsConfig([
  {
    field: "customerName",
    title: "客户名称",
    tags: {
      field: "tagList",
      typeMap: { VIP: "success", 高风险: "danger" },
      max: 3,
    },
  },
]);

权限类型

PermissionDirectiveConfig

权限指令配置类型。

interface PermissionDirectiveConfig {
  getPermissions: () => string[];
  getRoles: () => string[];
  superPermission?: string;
  superRoles?: string[];
}

type PermissionGetter = () => string[];
type RoleGetter = () => string[];

pageDataType

页面级共享数据类型，通过 inject('pageData') 获取。

interface pageDataType<TEntity = any, TSearchParams = any> {
  // 表格配置
  tableOptions?: {
    data?: TEntity[]; // 表格数据列表
    loading?: boolean; // 表格加载状态
    seqConfig?: any; // 序号列配置
    tableOperationConfig?: OperateColumn[]; // 工具栏按钮
    operateColumns?: OperateColumn[]; // 行操作按钮
    [key: string]: any;
  };

  // 查询参数
  params?: {
    pageNum: number; // 当前页码
    pageSize: number; // 每页条数
    [key: string]: any;
  } & Partial<TSearchParams>;

  // 数据总数
  total?: number;

  // 是否显示搜索栏
  showSearch?: boolean;

  // 分页配置
  paginationConfig?: {
    pageSizes: number[];
    size: "large" | "default" | "small";
  };

  // 已选中的数据
  checkTableData?: TEntity[];

  // 加载状态
  loading?: boolean;

  // API 配置
  api?: {
    list: (params: any) => Promise<any>;
    [key: string]: any;
  };

  // 配置
  searchConfig?: SearchConfigItem[];
  formConfig?: FormConfigItem[];
  columnsConfig?: ColumnConfigItem[];

  // 方法
  getData?: (api: any, callback?: any) => void;
  transformParams?: (params: TSearchParams) => any;
  transformResponse?: (response: any) => { rows: TEntity[]; total: number };
}

操作列类型

OperateColumn

操作列配置类型（支持下拉菜单）。

// 基础操作列
interface OperateColumnBase {
  title: string;
  type?: "primary" | "success" | "warning" | "danger" | "info";
  link?: boolean;
  icon?: string;
  onClick: (row: any) => void;
  show?: (data: { row: any; params: any }) => boolean;
  hasPermi?: string[];
  hasRole?: string[];
  fixed?: "left" | "right";
}

// 下拉菜单操作列
interface OperateColumnDropdown {
  title: string;
  type?: "primary" | "success" | "warning" | "danger" | "info";
  link?: boolean;
  icon?: string;
  dropdown: true;
  children: OperateColumnBase[];
  show?: (data: { row: any; params: any }) => boolean;
  hasPermi?: string[];
  hasRole?: string[];
}

type OperateColumn = OperateColumnBase | OperateColumnDropdown;

下拉菜单示例

const operateColumns = defineOperateColumns([
  {
    title: "编辑",
    onClick: (row) => handleEdit(row),
  },
  {
    title: "更多",
    dropdown: true,
    children: [
      { title: "详情", onClick: (row) => handleDetail(row) },
      { title: "删除", type: "danger", onClick: (row) => handleDelete(row) },
    ],
  },
]);

PageTemplate 配置类型

PageTemplateConfig

全局配置类型。

interface PageTemplateConfig {
  ui?: PageTemplateUIOptions;
  dependencies?: PageTemplateDependencies;
  dict?: PageTemplateDictOptions;
  VXETableConfig?: VxeGlobalConfig; // VXE-Table 全局配置
}

PageTemplateUIOptions

UI 配置选项类型。

interface PageTemplateUIOptions {
  formItemSize?:
    | "small"
    | "default"
    | "large"
    | (() => "small" | "default" | "large");
}

type FormItemSizeType = "small" | "default" | "large";

PageTemplateDependencies

依赖注入配置类型。

interface PageTemplateDependencies {
  oss?: OssApi; // OSS 文件操作 API
  permissionChecker?: (value?: string[]) => boolean; // 权限检查函数
  dictLoader?: (
    dictType: string,
    options: DictLoadOptions
  ) => Promise<DictLoadResult>; // 字典加载函数
  calculateHeight?: CalculateHeightFn; // 表格高度计算函数
  calculateWidth?: (options?: {
    waitForVisible?: boolean;
  }) => Promise<number> | number; // 表格宽度计算函数
  customAdapters?: Record<string, DictAdapterConfig>; // 自定义字典适配器
}

CalculateHeightFn

表格高度计算函数类型。

type CalculateHeightFn = (formHeight: number, otherHeight: number) => number;

PageTemplateDictOptions

字典配置选项类型。

interface PageTemplateDictOptions extends DictLoadOptions {
  preload?: boolean; // 是否自动预加载
  commonTypes?: string[]; // 预加载的字典类型
  cacheTime?: number; // 缓存时间（毫秒）
}

InternalConfig

内部配置类型（完整配置结构）。

interface InternalConfig {
  dict: PageTemplateDictOptions;
  dependencies: PageTemplateDependencies;
  ui: {
    formItemSize: FormItemSizeType | (() => FormItemSizeType);
  };
}

OssApi

OSS API 类型。

interface OssApi {
  uploadOSS: (file: File | FormData) => Promise<{
    url: string;
    fileName: string;
    ossId?: string | number;
  }>;
  deleteOSS: (ossId: string | number) => Promise<{
    code: number;
    msg?: string;
  }>;
}

Descriptions 组件类型

DescriptionSectionConfig

描述分组配置类型。

interface DescriptionSectionConfig {
  title?: string;
  column?: number;
  children: DescriptionItemConfig[];
  labelWidth?: string;
  width?: number;
  align?: "left" | "center" | "right";
  labelAlign?: "left" | "center" | "right";
  style?: Record<string, unknown>;
}

DescriptionItemConfig

描述项配置类型。

interface DescriptionItemConfig {
  label: string;
  value: string;
  span?: number;
  type?: "file" | "richText";
  dictType?: string;
  options?: DictDataOption[];
  format?: (value: any, row: any) => string;
  labelWidth?: string;
  align?: "left" | "center" | "right";
  labelAlign?: "left" | "center" | "right";
}

类型守卫函数

vue-admin-kit 导出了两个类型守卫函数，用于运行时类型检查：

isDictDataOption

检查对象是否为 DictDataOption 类型。

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

const obj = { label: "启用", value: "1" };

if (isDictDataOption(obj)) {
  // obj 被推断为 DictDataOption 类型
  console.log(obj.label, obj.value);
}

isDictLoadResult

检查对象是否为 DictLoadResult 类型。

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

const result = await fetchDict("sys_status");

if (isDictLoadResult(result)) {
  // result 被推断为 DictLoadResult 类型
  console.log(result.success, result.data);
}