@mtn-ui-z/utils 0.0.1

package/src/permission.ts

@@ -0,0 +1,165 @@
+/**
+ * 权限管理模块
+ * 提供统一的权限检查功能与 usePermission composable
+ */
+import {
+  inject,
+  computed,
+  toValue,
+  unref,
+  type InjectionKey,
+  type Ref,
+  type MaybeRefOrGetter,
+  type ComputedRef
+} from 'vue'
+
+/**
+ * 权限检查函数类型
+ * @param permission 权限码（支持单个或多个，多个时满足任一即可）
+ * @returns 是否有权限
+ */
+export type PermissionChecker = (permission: string | string[]) => boolean
+
+/**
+ * 权限行为类型
+ * - hide: 无权限时隐藏元素
+ * - disable: 无权限时禁用元素
+ */
+export type PermissionAction = 'hide' | 'disable'
+
+/** 将权限码规范为数组，供内部与 hasPermission / createPermissionChecker 复用 */
+function normalizePermissionList(permission: string | string[]): string[] {
+  return Array.isArray(permission) ? permission : [permission]
+}
+
+/**
+ * 默认权限检查函数
+ * 在未配置自定义检查函数时使用，默认返回 true（所有人都有权限）
+ */
+export const defaultPermissionChecker: PermissionChecker = (_permission) => {
+  if (import.meta.env.DEV) {
+    console.warn(
+      '[mtn-ui] 未配置权限检查函数，默认返回 true。' +
+        '请在应用根组件中通过 provide 提供 PERMISSION_CHECKER_KEY。'
+    )
+  }
+  return true
+}
+
+/**
+ * 权限检查函数的 Provide/Inject Key
+ * 在应用根组件中通过 provide 提供自定义的权限检查函数
+ *
+ * @example
+ * ```typescript
+ * import { provide, ref, computed } from 'vue'
+ * import { PERMISSION_CHECKER_KEY } from '@mtn-ui-z/utils'
+ *
+ * const userPermissions = ref(['user:add', 'user:edit'])
+ * provide(PERMISSION_CHECKER_KEY, computed(() => {
+ *   return (permission: string | string[]) => {
+ *     const permArray = Array.isArray(permission) ? permission : [permission]
+ *     return permArray.some((perm) => userPermissions.value.includes(perm))
+ *   }
+ * }))
+ * ```
+ */
+export const PERMISSION_CHECKER_KEY: InjectionKey<Ref<PermissionChecker>> = Symbol('permissionChecker')
+
+/**
+ * 用户权限列表的 Provide/Inject Key（可选）
+ * 如果使用 Pinia/Vuex 管理权限，可以不使用此 Key
+ */
+export const USER_PERMISSIONS_KEY: InjectionKey<Ref<string[]>> = Symbol('userPermissions')
+
+/**
+ * 创建默认的权限检查函数
+ * 基于权限列表进行检查
+ *
+ * @param permissions 用户权限列表
+ * @returns 权限检查函数
+ *
+ * @example
+ * ```typescript
+ * const userPermissions = ref(['user:add', 'user:edit'])
+ * const checker = createPermissionChecker(userPermissions)
+ *
+ * provide(PERMISSION_CHECKER_KEY, computed(() => checker))
+ * ```
+ */
+export function createPermissionChecker(permissions: Ref<string[]>): PermissionChecker {
+  return (permission) =>
+    normalizePermissionList(permission).some((perm) => permissions.value.includes(perm))
+}
+
+/**
+ * 工具函数：检查是否有指定权限
+ * 可用于非组件场景的权限判断
+ *
+ * @param userPermissions 用户权限列表
+ * @param requiredPermission 需要的权限
+ * @returns 是否有权限
+ */
+export function hasPermission(
+  userPermissions: string[],
+  requiredPermission: string | string[]
+): boolean {
+  return normalizePermissionList(requiredPermission).some((perm) =>
+    userPermissions.includes(perm)
+  )
+}
+
+// ==================== usePermission Composable ====================
+
+export interface UsePermissionOptions {
+  /** 权限码（支持响应式） */
+  permission?: MaybeRefOrGetter<string | string[] | undefined>
+  /** 无权限时的行为（支持响应式） */
+  permissionAction?: MaybeRefOrGetter<PermissionAction | undefined>
+}
+
+export interface UsePermissionReturn {
+  /** 是否有权限 */
+  hasPermission: ComputedRef<boolean>
+  /** 是否应该隐藏 */
+  shouldHide: ComputedRef<boolean>
+  /** 是否应该禁用 */
+  shouldDisable: ComputedRef<boolean>
+}
+
+/**
+ * 使用权限控制
+ * @param options 权限配置选项（支持响应式）
+ * @returns 权限状态
+ *
+ * @example
+ * ```typescript
+ * const { hasPermission, shouldHide, shouldDisable } = usePermission({
+ *   permission: props.permission,
+ *   permissionAction: props.permissionAction,
+ * })
+ * ```
+ */
+export function usePermission(options: UsePermissionOptions): UsePermissionReturn {
+  const permissionCheckerRef = inject<Ref<PermissionChecker> | null>(PERMISSION_CHECKER_KEY, null)
+
+  const hasPermission = computed(() => {
+    const p = toValue(options.permission)
+    if (!p) return true
+    const checker: PermissionChecker = permissionCheckerRef
+      ? unref(permissionCheckerRef)
+      : defaultPermissionChecker
+    return checker(p)
+  })
+
+  const action = computed(() => toValue(options.permissionAction) ?? 'hide')
+
+  const shouldHide = computed(() => !hasPermission.value && action.value === 'hide')
+  const shouldDisable = computed(() => !hasPermission.value && action.value === 'disable')
+
+  return {
+    hasPermission,
+    shouldHide,
+    shouldDisable
+  }
+}

package/src/request-types.ts

@@ -0,0 +1,57 @@
+/*
+ * @Author: liaokt
+ * @Description: API 相关类型定义
+ * @Date: 2025-11-06 09:44:01
+ * @LastEditors: liaokt
+ * @LastEditTime: 2025-12-10 09:12:22
+ */
+
+/** API 响应基础类型（Result 是 ApiResponse 的别名，保持向后兼容） */
+export interface Result<T = unknown> {
+  code: number
+  message?: string
+  msg?: string
+  data: T
+  success?: boolean
+}
+
+/** ApiResponse 作为 Result 的别名，保持向后兼容 */
+export type ApiResponse<T = unknown> = Result<T>
+
+/** 分页请求参数 */
+export interface PaginationParams {
+  page: number
+  page_size: number
+  [key: string]: unknown
+}
+
+/** 分页响应数据 */
+export interface PaginationData<T> {
+  list: T[]
+  total: number
+  page: number
+  page_size: number
+}
+
+/** 分页响应类型 */
+export interface PaginationResponse<T> extends Result<PaginationData<T>> {}
+
+/** 列表响应类型 */
+export interface ListResponse<T> extends Result<T[]> {}
+
+/** 响应处理结果接口 */
+export interface ResponseResult<T = unknown> {
+  success: boolean
+  data: T | null
+  message: string
+  code: number
+}
+
+/** 请求配置扩展 */
+export interface RequestConfig {
+  hiddenError?: boolean
+  showLoading?: boolean
+}
+
+/** 默认成功码（与后端约定一致时可覆盖） */
+export const DEFAULT_API_SUCCESS_CODE = 10200

package/src/request.ts

@@ -0,0 +1,178 @@
+/*
+ * @Author: liaokt
+ * @Description: 基于 axios 的请求封装，支持拦截器与可配置错误/401 处理
+ * @Date: 2025-11-06 09:14:28
+ * @LastEditors: liaokt
+ * @LastEditTime: 2025-12-26 10:23:57
+ */
+import axios from 'axios'
+import type { AxiosError, AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios'
+import { getStorage, removeStorage } from './storage'
+import type { Result } from './request-types'
+import { DEFAULT_API_SUCCESS_CODE } from './request-types'
+
+/**
+ * 扩展 AxiosRequestConfig
+ */
+declare module 'axios' {
+  export interface AxiosRequestConfig {
+    hiddenError?: boolean
+  }
+}
+
+export interface CreateRequestOptions {
+  baseURL?: string
+  timeout?: number
+  /** 业务成功码，默认 10200 */
+  successCode?: number
+  /** 获取 token，用于请求头 Authorization */
+  getToken?: () => string | undefined
+  /** 显示错误提示，不传则仅 console */
+  showError?: (msg: string) => void
+  /** 401 未授权时的回调（如清 token、跳转登录） */
+  onUnauthorized?: (message?: string) => void
+  /** 存储 key：token、用户信息等，用于 401 时清除 */
+  storageKeysToClearOn401?: string[]
+  /** 响应头带 key 时保存（如验证码 key），不传则不处理 */
+  onSaveCaptchaKey?: (key: string) => void
+}
+
+let errorMessageTimer: ReturnType<typeof setTimeout> | null = null
+
+function debouncedShowError(showErrorFn: (msg: string) => void, errorMsg: string): void {
+  if (errorMessageTimer) clearTimeout(errorMessageTimer)
+  errorMessageTimer = setTimeout(() => showErrorFn(errorMsg), 300)
+}
+
+/**
+ * 创建请求实例（可传入 showError、onUnauthorized 等与 UI/路由对接）
+ */
+export function createRequest(options: CreateRequestOptions = {}) {
+  const {
+    baseURL = '',
+    timeout = 10000,
+    successCode = DEFAULT_API_SUCCESS_CODE,
+    getToken,
+    showError = (msg) => console.error(msg),
+    onUnauthorized,
+    storageKeysToClearOn401 = ['token', 'userInfo'],
+    onSaveCaptchaKey
+  } = options
+
+  const service: AxiosInstance = axios.create({
+    baseURL,
+    timeout,
+    headers: {
+      'Content-Type': 'application/json;charset=UTF-8'
+    }
+  })
+
+  service.interceptors.request.use(
+    (config) => {
+      const token = getToken?.() ?? getStorage<string>('token')
+      if (token) {
+        const h = config.headers as Record<string, string>
+        if (!h.Authorization) h.Authorization = `JWT ${token}`
+      }
+      const headers = config.headers as Record<string, string>
+      headers['X-Timestamp'] = String(Math.floor(Date.now() / 1000))
+      const csrfToken = typeof document !== 'undefined' && document.cookie
+        ? document.cookie
+            .split('; ')
+            .find((row) => row.startsWith('csrftoken='))
+            ?.split('=')[1]
+        : undefined
+      if (csrfToken) headers['X-CSRFToken'] = csrfToken
+      return config
+    },
+    (error: AxiosError) => {
+      console.error('请求错误:', error.message)
+      return Promise.reject(error)
+    }
+  )
+
+  service.interceptors.response.use(
+    (response: AxiosResponse) => {
+      const headers = response.headers as Record<string, string>
+      if (headers && 'key' in headers && onSaveCaptchaKey) {
+        onSaveCaptchaKey(headers.key as string)
+      }
+      if (response.config.responseType === 'blob') {
+        return response
+      }
+
+      const body = response.data as Result
+      const code = body?.code
+      const msg = body?.message ?? body?.msg
+
+      if (code === successCode) {
+        return response.data
+      }
+
+      if (!response.config.hiddenError) {
+        debouncedShowError(showError, msg ?? '请求失败')
+      }
+      return Promise.reject(response.data)
+    },
+    (error: AxiosError) => {
+      const status = error.response?.status
+      const errorData = error.response?.data as Result | undefined
+      let errorMessage: string | undefined
+      if (errorData && typeof errorData === 'object') {
+        errorMessage = (errorData as Result).message ?? (errorData as Result).msg
+      }
+
+      switch (status) {
+        case 401: {
+          storageKeysToClearOn401.forEach((key) => removeStorage(key))
+          const msg = errorMessage ?? '登录已失效，请重新登录'
+          if (!error?.config?.hiddenError) debouncedShowError(showError, msg)
+          onUnauthorized?.(msg)
+          return Promise.reject(error)
+        }
+        case 403:
+          errorMessage = errorMessage ?? '无访问权限'
+          break
+        case 404:
+          errorMessage = errorMessage ?? '请求地址不存在'
+          break
+        case 500:
+          errorMessage = errorMessage ?? '服务器内部错误'
+          break
+        default:
+          errorMessage = errorMessage ?? '网络请求失败'
+      }
+
+      if (!error?.config?.hiddenError && status !== 401 && status !== 404) {
+        debouncedShowError(showError, errorMessage ?? '网络请求失败')
+      }
+      return Promise.reject(error)
+    }
+  )
+
+  const request = {
+    get<T = unknown>(url: string, config?: AxiosRequestConfig): Promise<T> {
+      return service.get(url, config)
+    },
+    post<T = unknown>(url: string, data?: object, config?: AxiosRequestConfig): Promise<T> {
+      return service.post(url, data, config)
+    },
+    put<T = unknown>(url: string, data?: object, config?: AxiosRequestConfig): Promise<T> {
+      return service.put(url, data, config)
+    },
+    patch<T = unknown>(url: string, data?: object, config?: AxiosRequestConfig): Promise<T> {
+      return service.patch(url, data, config)
+    },
+    delete<T = unknown>(url: string, config?: AxiosRequestConfig): Promise<T> {
+      return service.delete(url, config)
+    }
+  }
+
+  return { request, axiosInstance: service }
+}
+
+/** 默认实例（无 UI/路由注入，仅控制台报错），应用内建议使用 createRequest 传入 showError/onUnauthorized */
+const { request, axiosInstance } = createRequest()
+
+export { request, axiosInstance }
+export default axiosInstance

package/src/state.d.ts

@@ -0,0 +1,6 @@
+export {
+  useToggle,
+  useCounter,
+  useLocalStorage,
+  useSessionStorage
+} from '@vueuse/core'

package/src/state.ts

@@ -0,0 +1,11 @@
+/**
+ * 状态管理工具
+ * 响应式状态管理相关的工具函数
+ */
+
+export {
+  useToggle,
+  useCounter,
+  useLocalStorage,
+  useSessionStorage
+} from '@vueuse/core'

package/src/storage.ts

@@ -0,0 +1,143 @@
+/*
+ * @Author: liaokt
+ * @Description: 本地存储工具函数
+ * @Date: 2025-12-10
+ */
+
+function getStorageImpl(): Storage | null {
+  return typeof localStorage !== 'undefined' ? localStorage : null
+}
+
+function getSessionImpl(): Storage | null {
+  return typeof sessionStorage !== 'undefined' ? sessionStorage : null
+}
+
+/**
+ * 获取本地存储数据
+ * @param key 键名
+ * @param defaultValue 默认值
+ */
+export function getStorage<T = unknown>(key: string, defaultValue?: T): T | undefined {
+  try {
+    const storage = getStorageImpl()
+    if (!storage) return defaultValue
+    const item = storage.getItem(key)
+    if (item === null) return defaultValue
+    return JSON.parse(item) as T
+  } catch {
+    return defaultValue
+  }
+}
+
+/**
+ * 设置本地存储数据
+ * @param key 键名
+ * @param value 数据值
+ */
+export function setStorage<T = unknown>(key: string, value: T): void {
+  try {
+    const storage = getStorageImpl()
+    if (storage) storage.setItem(key, JSON.stringify(value))
+  } catch (error) {
+    console.error('存储数据失败:', error)
+  }
+}
+
+/**
+ * 移除本地存储数据
+ * @param key 键名
+ */
+export function removeStorage(key: string): void {
+  try {
+    const storage = getStorageImpl()
+    if (storage) storage.removeItem(key)
+  } catch (error) {
+    console.error('删除数据失败:', error)
+  }
+}
+
+/**
+ * 清空所有本地存储数据
+ */
+export function clearStorage(): void {
+  try {
+    const storage = getStorageImpl()
+    if (storage) storage.clear()
+  } catch (error) {
+    console.error('清空存储失败:', error)
+  }
+}
+
+/**
+ * 检查本地存储中是否存在某个键
+ * @param key 键名
+ */
+export function hasStorage(key: string): boolean {
+  const storage = getStorageImpl()
+  return storage ? storage.getItem(key) !== null : false
+}
+
+/**
+ * 获取会话存储数据
+ * @param key 键名
+ * @param defaultValue 默认值
+ */
+export function getSession<T = unknown>(key: string, defaultValue?: T): T | undefined {
+  try {
+    const storage = getSessionImpl()
+    if (!storage) return defaultValue
+    const item = storage.getItem(key)
+    if (item === null) return defaultValue
+    return JSON.parse(item) as T
+  } catch {
+    return defaultValue
+  }
+}
+
+/**
+ * 设置会话存储数据
+ * @param key 键名
+ * @param value 数据值
+ */
+export function setSession<T = unknown>(key: string, value: T): void {
+  try {
+    const storage = getSessionImpl()
+    if (storage) storage.setItem(key, JSON.stringify(value))
+  } catch (error) {
+    console.error('存储数据失败:', error)
+  }
+}
+
+/**
+ * 移除会话存储数据
+ * @param key 键名
+ */
+export function removeSession(key: string): void {
+  try {
+    const storage = getSessionImpl()
+    if (storage) storage.removeItem(key)
+  } catch (error) {
+    console.error('删除数据失败:', error)
+  }
+}
+
+/**
+ * 清空所有会话存储数据
+ */
+export function clearSession(): void {
+  try {
+    const storage = getSessionImpl()
+    if (storage) storage.clear()
+  } catch (error) {
+    console.error('清空存储失败:', error)
+  }
+}
+
+/**
+ * 检查会话存储中是否存在某个键
+ * @param key 键名
+ */
+export function hasSession(key: string): boolean {
+  const storage = getSessionImpl()
+  return storage ? storage.getItem(key) !== null : false
+}

package/src/theme.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 运行时主题色类型声明
+ * 避免在部分环境下 TS 解析 node_modules 内 .ts 失败
+ */
+import type { Ref } from 'vue'
+
+export interface ThemeColorOverrides {
+  primary?: string
+  primaryHover?: string
+  primaryActive?: string
+  success?: string
+  successHover?: string
+  warning?: string
+  warningHover?: string
+  danger?: string
+  dangerHover?: string
+  dangerActive?: string
+  info?: string
+  infoHover?: string
+}
+
+export type ThemeMode = 'light' | 'dark'
+export type DensityMode = 'default' | 'compact'
+
+export declare const MTN_THEME_PRESETS: readonly ['default', 'ocean']
+
+export type MtnThemePreset = (typeof MTN_THEME_PRESETS)[number]
+
+export interface MtnAntThemeToken {
+  colorPrimary?: string
+  colorPrimaryHover?: string
+  colorPrimaryActive?: string
+  colorLink?: string
+  colorLinkHover?: string
+  colorLinkActive?: string
+  borderRadius?: number
+  colorBgBase?: string
+  colorText?: string
+  colorTextSecondary?: string
+  colorBorder?: string
+  colorSuccess?: string
+  colorWarning?: string
+  colorError?: string
+  colorInfo?: string
+  controlHeight?: number
+  fontSize?: number
+  padding?: number
+  paddingXS?: number
+  paddingSM?: number
+  paddingLG?: number
+  margin?: number
+  marginXS?: number
+  marginSM?: number
+  marginLG?: number
+}
+
+export const themeModeRef: Ref<ThemeMode>
+export const densityModeRef: Ref<DensityMode>
+export const antThemeConfigRef: Ref<{ token: MtnAntThemeToken }>
+
+export function syncAntTokensFromCssVars(): void
+
+export interface ApplyMtnThemeOptions {
+  mode?: ThemeMode
+  density?: DensityMode
+  preset?: MtnThemePreset | string | null
+  colors?: ThemeColorOverrides
+  antToken?: Partial<MtnAntThemeToken>
+}
+
+export function applyMtnTheme(opts: ApplyMtnThemeOptions): void
+
+export function setThemeColors(colors: ThemeColorOverrides): void
+export function setThemePrimary(
+  primary: string,
+  hoverLighten?: number,
+  activeDarken?: number
+): void
+export function setThemeMode(
+  mode: ThemeMode,
+  options?: { persist?: boolean; storageKey?: string }
+): void
+export function toggleThemeMode(options?: {
+  persist?: boolean
+  storageKey?: string
+}): ThemeMode
+export function getThemeMode(): ThemeMode
+export function setDensityMode(
+  mode: DensityMode,
+  options?: { persist?: boolean; storageKey?: string }
+): void
+export function getDensityMode(): DensityMode
+export function toggleDensityMode(options?: {
+  persist?: boolean
+  storageKey?: string
+}): DensityMode
+export function initDensityFromStorage(options?: { storageKey?: string }): DensityMode
+export function persistDensityMode(mode: DensityMode, options?: { storageKey?: string }): void
+export function initThemeFromStorage(options?: { storageKey?: string }): ThemeMode
+export function persistThemeMode(mode: ThemeMode, options?: { storageKey?: string }): void
+export function initTheme(options?: {
+  storageKey?: string
+  densityStorageKey?: string
+  preferColorScheme?: boolean
+}): ThemeMode
+export function setThemePreset(preset: MtnThemePreset | string | null | undefined): void
+export function getThemePreset(): string | null