@cimom/vben-types

用于多个 app 公用的工具类型，继承了 @cimom/vben-core-typings 的所有能力。业务上有通用的类型定义可以放在这里。

安装

# 进入目标应用目录，例如 apps/xxxx-app
# cd apps/xxxx-app
pnpm add @cimom/vben-types

基本使用

// 推荐加上 type 关键字仅导入类型定义，不引入实际代码
import type { UserInfo } from '@cimom/vben-types';

// 使用类型定义声明变量
const userInfo: UserInfo = {
  id: '1',
  username: 'admin',
  realName: 'Admin User',
  avatar: 'https://example.com/avatar.jpg',
  desc: 'System Administrator',
  homePath: '/dashboard',
  token: 'xxx-xxx-xxx',
};

可用类型

用户相关类型

/**
 * 用户信息类型
 */
interface UserInfo extends BasicUserInfo {
  /**
   * 用户描述
   */
  desc: string;
  /**
   * 首页地址
   */
  homePath: string;

  /**
   * accessToken
   */
  token: string;
}

全局类型声明

该包还提供了全局类型声明，如应用配置和路由元数据的扩展：

// 应用配置原始类型
export interface VbenAdminProAppConfigRaw {
  VITE_GLOB_API_URL: string;
}

// 应用配置处理后的类型
export interface ApplicationConfig {
  apiURL: string;
}

// 全局窗口对象扩展
declare global {
  interface Window {
    _VBEN_ADMIN_PRO_APP_CONF_: VbenAdminProAppConfigRaw;
  }
}

// Vue Router 的路由元数据扩展
declare module 'vue-router' {
  interface RouteMeta extends IRouteMeta {}
}

继承的核心类型

该包继承了 @cimom/vben-core-typings 中的所有类型，下面是一些常用的核心类型：

基础类型

// 基础用户信息类型
interface BasicUserInfo {
  id: string;
  username: string;
  realName: string;
  avatar: string;
}

// 选项类型
interface SelectOption {
  label: string;
  value: string | number;
  disabled?: boolean;
  [key: string]: any;
}

// 分页参数类型
interface PaginationParams {
  page: number;
  pageSize: number;
  total?: number;
}

路由相关类型

// 路由元数据类型
interface RouteMeta {
  // 标题
  title: string;
  // 图标
  icon?: string;
  // 是否隐藏菜单
  hideMenu?: boolean;
  // 是否需要权限
  requiresAuth?: boolean;
  // 权限码
  permissions?: string[];
  // 是否保持活跃
  keepAlive?: boolean;
  // 外链
  href?: string;
  // 排序
  order?: number;
  // 是否是外链
  isExt?: boolean;
  // 是否在标签页中显示
  hideTab?: boolean;
}

使用示例

在组件中使用

<template>
  <div>
    <h1>{{ userInfo.realName }}</h1>
    <p>{{ userInfo.desc }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import type { UserInfo } from '@cimom/vben-types';

// 使用类型定义响应式数据
const userInfo = ref<UserInfo>({
  id: '1',
  username: 'admin',
  realName: 'Admin User',
  avatar: 'https://example.com/avatar.jpg',
  desc: 'System Administrator',
  homePath: '/dashboard',
  token: 'xxx-xxx-xxx',
});
</script>

在 API 请求中使用

import { request } from '@/utils/request';
import type { UserInfo } from '@cimom/vben-types';

// 定义 API 返回类型
export function getUserInfo(): Promise<UserInfo> {
  return request.get('/api/user/info');
}

// 使用 API
async function fetchUserInfo() {
  const userInfo = await getUserInfo();
  console.log(userInfo.realName);
  console.log(userInfo.homePath);
}

在路由配置中使用

import { createRouter, createWebHistory } from 'vue-router';
// 不需要显式导入 RouteMeta 类型，因为已经在全局扩展了 vue-router 模块

const routes = [
  {
    path: '/dashboard',
    component: () => import('@/views/dashboard/index.vue'),
    meta: {
      title: '仪表盘',
      icon: 'dashboard',
      requiresAuth: true,
      permissions: ['dashboard:view'],
      keepAlive: true,
      order: 1,
    },
  },
];

const router = createRouter({
  history: createWebHistory(),
  routes,
});

export default router;

扩展类型

如果需要添加新的类型定义，可以在项目中创建新的类型文件，然后导出：

// 在项目中创建 src/types/custom.ts
import type { UserInfo } from '@cimom/vben-types';

// 扩展用户信息类型
export interface ExtendedUserInfo extends UserInfo {
  department: string;
  role: string;
  permissions: string[];
}

// 定义其他自定义类型
export interface MenuItem {
  key: string;
  title: string;
  icon?: string;
  children?: MenuItem[];
  path?: string;
  disabled?: boolean;
}

类型声明最佳实践

1. 始终使用 type 关键字导入类型：

   import type { UserInfo } from '@cimom/vben-types';

2. 使用接口而非类型别名：

   // 推荐
   interface UserState {
     userInfo: UserInfo | null;
     token: string;
   }
   
   // 不推荐
   type UserState = {
     userInfo: UserInfo | null;
     token: string;
   };

3. 为函数添加返回类型：

   function getUserInfo(): Promise<UserInfo> {
     // ...
   }

4. 使用类型断言而非强制类型转换：

   // 推荐
   const userInfo = data as UserInfo;
   
   // 不推荐
   const userInfo = <UserInfo>data;

5. 利用类型推断：

   // 让 TypeScript 自动推断类型
   const user = {
     id: '1',
     username: 'admin',
     realName: 'Admin User',
     avatar: 'https://example.com/avatar.jpg',
     desc: 'System Administrator',
     homePath: '/dashboard',
     token: 'xxx-xxx-xxx',
   }; // TypeScript 会自动推断出类型