@quiteer/naive-extra 0.0.1

package/src/hooks/useTable.ts

@@ -0,0 +1,241 @@
+import type { DataTableColumn } from 'naive-ui'
+import type { QuiTable } from '../components/table'
+import { NImage } from 'naive-ui'
+import { h, ref } from 'vue'
+
+interface UseTableReturn<T> {
+  tableRef: ReturnType<typeof ref<InstanceType<typeof QuiTable>>>
+  refresh: (isReset?: boolean) => void
+  downloadCsv: (fileName?: string) => void
+  setActions: (columnOption: Partial<DataTableColumn<T>>) => void
+  setColumns: (columns: DataTableColumn<T>[]) => void
+  getColumns: () => DataTableColumn<T>[] | undefined
+  setSize: (size: 'small' | 'medium' | 'large') => void
+  setStriped: (striped: boolean) => void
+  getPagination: () => any
+  setPagination: (patch: Partial<{ page: number, pageSize: number }>) => void
+  getData: <TRow = any>() => TRow[] | undefined
+  setData: (rows: T[]) => void
+  setFetch: (fn: (pageInfo: { pageNum: number, pageSize: number }) => Promise<{ list: T[], total: number }>) => void
+  withSearch: (
+    getSearchParams: () => Record<string, any>,
+    remote: (args: { pageNum: number, pageSize: number } & Record<string, any>) => Promise<{ list: T[], total: number }>
+  ) => void
+  createImageColumn: (key: keyof T & string, title?: string, width?: number) => DataTableColumn<T>
+  createIndexColumn: (title?: string, width?: number) => DataTableColumn<T>
+  createTextColumn: (key: keyof T & string, title: string, width?: number) => DataTableColumn<T>
+  createMoneyColumn: (key: keyof T & string, title?: string, precision?: number) => DataTableColumn<T>
+}
+
+/**
+ * 表格辅助函数集合
+ *
+ * 提供对 `QuiTable` 实例的常用操作封装，以及常用列的构造器。
+ * 适合在业务或示例中快速调用刷新、导出、追加操作列等能力。
+ *
+ * @returns 一组表格操作与便捷列构造器
+ *
+ * @example
+ * ```ts
+ * const { tableRef, refresh, downloadCsv, setActions } = useTable()
+ * refresh(true)
+ * downloadCsv('export')
+ * setActions({ title: '操作', render: (row) => h('div', {}, '查看') })
+ * ```
+ *
+ * @remarks
+ * - 所有实例方法均基于 `QuiTable` 的 `defineExpose` 能力安全调用
+ * - 列构造器仅提供基础构造，仍可按需覆盖属性
+ *
+ * @security
+ * - 导出文件名由调用方决定，请避免包含敏感信息
+ *
+ * @performance
+ * - 方法本身为轻量封装，不引入额外复杂度
+ */
+export function useTable<T = Record<string, any>>(): UseTableReturn<T> {
+  const tableRef = ref<InstanceType<typeof QuiTable>>()
+
+  /**
+   * 刷新表格数据
+   *
+   * @param isReset - 是否重置到第一页
+   */
+  function refresh(isReset = false) {
+    tableRef.value?.updateTableData(isReset)
+  }
+
+  /**
+   * 导出 CSV
+   *
+   * @param fileName - 文件名（不含扩展名）
+   */
+  function downloadCsv(fileName = 'data-table') {
+    tableRef.value?.downloadCsv(fileName)
+  }
+
+  /**
+   * 追加操作列
+   *
+   * @param columnOption - 操作列的部分配置
+   */
+  function setActions(columnOption: Partial<DataTableColumn<T>>) {
+    tableRef.value?.setActions(columnOption as any)
+  }
+
+  /**
+   * 设置列集合
+   */
+  function setColumns(columns: DataTableColumn<T>[]) {
+    tableRef.value?.setColumns(columns as any)
+  }
+
+  /**
+   * 获取当前列集合
+   */
+  function getColumns(): DataTableColumn<T>[] | undefined {
+    return tableRef.value?.getColumns() as any
+  }
+
+  /**
+   * 设置尺寸
+   */
+  function setSize(size: 'small' | 'medium' | 'large') {
+    tableRef.value?.setSize(size as any)
+  }
+
+  /**
+   * 设置斑马纹
+   */
+  function setStriped(striped: boolean) {
+    tableRef.value?.setStriped(striped)
+  }
+
+  /**
+   * 获取分页信息快照
+   */
+  function getPagination() {
+    return tableRef.value?.getPagination()
+  }
+
+  /**
+   * 局部更新分页信息
+   */
+  function setPagination(patch: Partial<{ page: number, pageSize: number }>) {
+    tableRef.value?.setPagination(patch as any)
+  }
+
+  /**
+   * 获取当前数据
+   */
+  function getData<TRow = any>(): TRow[] | undefined {
+    return tableRef.value?.getData() as any
+  }
+
+  /**
+   * 覆盖当前数据行
+   */
+  function setData(rows: T[]) {
+    tableRef.value?.setData(rows as any)
+  }
+
+  /**
+   * 替换远端 fetch 函数
+   */
+  function setFetch(
+    fn: (pageInfo: { pageNum: number, pageSize: number }) => Promise<{ list: T[], total: number }>
+  ) {
+    tableRef.value?.setFetch(fn as any)
+  }
+
+  /**
+   * 绑定外部搜索条件到远端 fetch
+   *
+   * @param getSearchParams - 返回搜索条件对象的函数
+   * @param remote - 实际请求函数，接收合并后的参数
+   */
+  function withSearch(
+    getSearchParams: () => Record<string, any>,
+    remote: (args: { pageNum: number, pageSize: number } & Record<string, any>) => Promise<{ list: T[], total: number }>
+  ) {
+    setFetch(async ({ pageNum, pageSize }) => {
+      const params = getSearchParams() || {}
+      return remote({ pageNum, pageSize, ...params })
+    })
+  }
+
+  /**
+   * 构造图片列
+   *
+   * @param key - 数据字段
+   * @param title - 列标题
+   * @param width - 列宽
+   * @returns 图片列配置
+   */
+  function createImageColumn(key: keyof T & string, title = '图片', width = 80): DataTableColumn<T> {
+    return {
+      title,
+      key,
+      width,
+      render(row) {
+        return h(NImage, { width, src: (row as any)[key] })
+      }
+    }
+  }
+
+  /**
+   * 构造序号列
+   */
+  function createIndexColumn(title = '序号', width = 80): DataTableColumn<T> {
+    return {
+      title,
+      key: '__index__' as any,
+      width,
+      render(_: any, index: number) {
+        return index + 1
+      }
+    } as any
+  }
+
+  /**
+   * 构造纯文本列
+   */
+  function createTextColumn(key: keyof T & string, title: string, width?: number): DataTableColumn<T> {
+    return { title, key, width } as any
+  }
+
+  /**
+   * 金额列
+   */
+  function createMoneyColumn(key: keyof T & string, title = '金额', precision = 2): DataTableColumn<T> {
+    return {
+      title,
+      key,
+      render(row: T) {
+        const val = Number((row as any)[key] ?? 0)
+        return (val / 100).toFixed(precision)
+      }
+    } as any
+  }
+
+  return {
+    tableRef,
+    refresh,
+    downloadCsv,
+    setActions,
+    setColumns,
+    getColumns,
+    setSize,
+    setStriped,
+    getPagination,
+    setPagination,
+    getData,
+    setData,
+    setFetch,
+    withSearch,
+    createImageColumn,
+    createIndexColumn,
+    createTextColumn,
+    createMoneyColumn
+  }
+}

package/src/hooks/useThemeOverrides.ts

@@ -0,0 +1,18 @@
+import type { Ref } from 'vue'
+import { lightTheme } from 'naive-ui'
+import { ref } from 'vue'
+
+/**
+ * 获取 Naive UI 特定组件的主题覆盖配置
+ * 核心价值在于提供完整的 TypeScript 类型提示，方便用户在业务代码中访问或动态计算样式。
+ *
+ */
+export function useThemeOverrides<K extends keyof typeof lightTheme>(
+  componentName: K
+): Ref<(typeof lightTheme)[K]> {
+  const theme = lightTheme
+
+  const overrides = ref(theme[componentName]) as Ref<(typeof lightTheme)[K]>
+
+  return overrides
+}

package/src/hooks/useUpload.ts

@@ -0,0 +1,82 @@
+import type { UploadProps } from 'naive-ui'
+import type { Props as QuiUploadProps } from '../components/upload/props'
+import { AcceptType } from '../components/upload/enum'
+
+/**
+ * 上传组件属性辅助函数
+ *
+ * 提供一组便捷的方法来生成不同类型的上传组件属性配置（如图片、视频、音频）。
+ *
+ * @param config - 基础上传配置
+ * @returns 包含获取不同类型上传属性的方法对象
+ *
+ * @example
+ * ```ts
+ * const { getImageUploadProps } = useUploadProps({ max: 5 })
+ * const props = getImageUploadProps({ action: '/upload' })
+ * ```
+ */
+export function useUploadProps(config: QuiUploadProps) {
+  const uploadComponentProps: QuiUploadProps = {
+    defaultUpload: true,
+    max: 1,
+    accept: undefined,
+    ...config
+  }
+
+  /**
+   * 获取通用上传属性
+   *
+   * @param option - 额外的上传配置
+   * @returns 合并后的上传属性
+   */
+  const getUploadProps = (option?: UploadProps): UploadProps => {
+    return { ...uploadComponentProps, ...option }
+  }
+
+  /**
+   * 获取图片上传属性
+   *
+   * @param option - 额外的上传配置
+   * @returns 图片上传配置
+   */
+  const getImageUploadProps = (option?: UploadProps): UploadProps => {
+    return {
+      ...getUploadProps({ accept: AcceptType.Image }),
+      ...option
+    }
+  }
+
+  /**
+   * 获取视频上传属性
+   *
+   * @param option - 额外的上传配置
+   * @returns 视频上传配置
+   */
+  const getVedioUploadProps = (option?: UploadProps): UploadProps => {
+    return {
+      ...getUploadProps({ accept: AcceptType.Video }),
+      ...option
+    }
+  }
+
+  /**
+   * 获取音频上传属性
+   *
+   * @param option - 额外的上传配置
+   * @returns 音频上传配置
+   */
+  const getAudioUploadProps = (option?: UploadProps): UploadProps => {
+    return {
+      ...getUploadProps({ accept: AcceptType.Audio }),
+      ...option
+    }
+  }
+
+  return {
+    getUploadProps,
+    getImageUploadProps,
+    getVedioUploadProps,
+    getAudioUploadProps
+  }
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+import type { DialogApi, LoadingBarApi, MessageApi, NotificationApi } from 'naive-ui'
+
+import { QuiActionButton, QuiBaseButton } from './components/button'
+import { QuiForm } from './components/form'
+import { QuiIcon, QuiIconPicker } from './components/icon'
+import { DEFAULT_LAYOUT_TYPE, QuiLayout } from './components/layout'
+import { QuiProvider } from './components/provider'
+import { QuiSearchBar } from './components/search-bar'
+import { QuiTable } from './components/table'
+
+import { AcceptType, QuiUpload } from './components/upload'
+import 'virtual:uno.css'
+
+export {
+  QuiActionButton,
+  QuiBaseButton,
+  QuiForm,
+  QuiIcon,
+  QuiIconPicker,
+  QuiLayout,
+  QuiProvider,
+  QuiSearchBar,
+  QuiTable,
+  QuiUpload
+}
+
+export {
+  AcceptType
+}
+
+export { DEFAULT_LAYOUT_TYPE }
+
+export type { ActionItem, BaseButtonProps } from './components/button'
+export type { CustomSwitchProps, FormProps, FormSchema } from './components/form'
+export type { LayoutProps, LayoutType, RouteMeta } from './components/layout'
+
+export type { ProviderProps } from './components/provider'
+export type { SearchBarProps } from './components/search-bar'
+export type {
+  TableColumn,
+  TableColumns,
+  TableExportType,
+  TableFetchFn,
+  TableProps,
+  TableSettings,
+  TableSize
+} from './components/table'
+export type { UploadProps } from './components/upload'
+export * from './context'
+export * from './hooks'
+
+declare global {
+  interface Window {
+    $message?: MessageApi
+    $dialog?: DialogApi
+    $notification?: NotificationApi
+    $loadingBar?: LoadingBarApi
+  }
+}

package/src/share/compact.ts

@@ -0,0 +1,35 @@
+/**
+ * 格式化像素值
+ *
+ * 将数字转换为带 px 单位的字符串，如果输入已带单位则保持不变。
+ *
+ * @param val - 数值或字符串
+ * @returns 格式化后的字符串或 undefined
+ */
+export function formatPx(val?: number | string): string | undefined {
+  if (val === undefined || val === null || val === '')
+    return undefined
+  if (typeof val === 'string' && (val.endsWith('px') || val.endsWith('%') || val.endsWith('vh') || val.endsWith('vw') || val.endsWith('rem') || val.endsWith('em'))) {
+    return val
+  }
+  return `${val}px`
+}
+
+/**
+ * 移除对象中值为 undefined 或 null 的属性 (浅压缩)
+ *
+ * @param obj - 目标对象
+ * @returns 清理后的新对象
+ */
+export function compact<T extends object>(obj: T): Partial<T> {
+  const result: any = {}
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      const value = obj[key]
+      if (value !== undefined && value !== null) {
+        result[key] = value
+      }
+    }
+  }
+  return result as Partial<T>
+}

package/src/share/index.ts

@@ -0,0 +1,2 @@
+export * from './compact'
+export * from './slot'

package/src/share/slot.ts

@@ -0,0 +1,29 @@
+import type { Slot, VNode } from 'vue'
+import { Comment, Fragment, Text } from 'vue'
+
+/**
+ * 判断插槽是否有内容（忽略注释和空文本）
+ * @param slot - 插槽函数
+ */
+export function hasSlotContent(slot: Slot | undefined | null): boolean {
+  if (!slot)
+    return false
+  const nodes = slot()
+  return nodes.some(isVNodeNotEmpty)
+}
+
+function isVNodeNotEmpty(vnode: VNode): boolean {
+  if (vnode.type === Comment)
+    return false
+  if (vnode.type === Text) {
+    return typeof vnode.children === 'string' && vnode.children.trim().length > 0
+  }
+  if (vnode.type === Fragment) {
+    if (!Array.isArray(vnode.children))
+      return false
+    if (vnode.children.length === 0)
+      return false
+    return vnode.children.some(child => isVNodeNotEmpty(child as VNode))
+  }
+  return true
+}

package/src/utils/transformRoutes.ts

@@ -0,0 +1,163 @@
+import type { ComputedRef } from 'vue'
+import type { RouteRecordRaw } from 'vue-router'
+import type { RouteMeta } from '../components/layout/types'
+import { computed } from 'vue'
+
+export interface RouteNode {
+  path: string
+  name?: string
+  meta?: RouteMeta
+  children?: RouteNode[]
+}
+
+function joinPath(parent: string, p: string) {
+  const full = p?.startsWith('/') ? p : (parent ? `${parent}/${p}` : `/${p}`)
+  const single = full.replace(/\/+/g, '/')
+  return single.length > 1 && single.endsWith('/') ? single.slice(0, -1) : single
+}
+
+function sortRaw(list: RouteRecordRaw[]): RouteRecordRaw[] {
+  const getOrder = (r: RouteRecordRaw) => {
+    const m = r.meta as RouteMeta | undefined
+    const o = m?.order
+    const v = typeof o === 'number' ? o : Number(o)
+    return Number.isFinite(v) ? v : Number.POSITIVE_INFINITY
+  }
+  const getTitle = (r: RouteRecordRaw) => {
+    const m = r.meta as RouteMeta | undefined
+    return String(m?.title ?? r.path.split('/').filter(Boolean).pop() ?? '')
+  }
+  return [...list].sort((a, b) => {
+    const oa = getOrder(a)
+    const ob = getOrder(b)
+    if (oa !== ob)
+      return oa - ob
+    return getTitle(a).localeCompare(getTitle(b))
+  })
+}
+
+/**
+ * 标准化路由并自动生成重定向
+ *
+ * 递归处理路由树，拼接父子路径，并为包含子路由但未定义重定向的父路由自动生成指向第一个子路由的重定向。
+ *
+ * @param raw - 原始路由配置数组
+ * @param parent - 父级路径，用于递归拼接完整路径
+ * @returns 标准化后的路由数组，包含完整路径和自动生成的 redirect
+ *
+ * @remarks
+ * - 会自动拼接父级路径，确保 path 为绝对路径
+ * - 如果父路由没有 redirect 且有子路由，会自动将 redirect 设置为第一个子路由（优先 index 或空路径）
+ */
+export function normalizeAndRedirect(raw: RouteRecordRaw[], parent = ''): RouteRecordRaw[] {
+  const childrenSorted = sortRaw(raw)
+  return childrenSorted.map((r): RouteRecordRaw => {
+    const curPathAbs = joinPath(parent, r.path)
+    const kidsRaw = Array.isArray(r.children) ? (r.children as RouteRecordRaw[]) : []
+    const kids = kidsRaw.length ? normalizeAndRedirect(kidsRaw, curPathAbs) : undefined
+    let redirect = r.redirect as string | undefined
+    if (!redirect && kids && kids.length) {
+      const idx = kids.find(c => c.path === 'index' || c.path === '')
+      const target = idx ?? kids[0]
+      if (target) {
+        redirect = joinPath(curPathAbs, target.path)
+      }
+    }
+    return {
+      ...r,
+      ...(kids ? { children: kids } : {}),
+      ...(redirect ? { redirect } : {})
+    } as RouteRecordRaw
+  })
+}
+
+/**
+ * 将路由配置转换为简化的路由树结构
+ *
+ * 过滤掉 hideMenu 的路由，并提取用于菜单或导航展示的关键信息。
+ *
+ * @param raw - 原始路由配置数组
+ * @param parent - 父级路径
+ * @returns 简化后的路由节点树
+ */
+export function toRouteTree(raw: RouteRecordRaw[], parent = ''): RouteNode[] {
+  return raw
+    .filter(r => (r.meta as RouteMeta | undefined)?.hideMenu !== true)
+    .map<RouteNode>((r) => {
+      const meta = r.meta ? { ...(r.meta as RouteMeta) } : undefined
+      const abs = joinPath(parent, r.path)
+      const children = Array.isArray(r.children) ? toRouteTree(r.children as RouteRecordRaw[], abs) : []
+      return { path: abs, name: r.name as string | undefined, meta, children }
+    })
+}
+
+/**
+ * 对路由树进行排序
+ *
+ * 根据 meta.order (数字) 升序排序，若 order 相同则按 title 或路径名进行字母顺序排序。
+ *
+ * @param tree - 路由节点树
+ * @returns 排序后的新路由树
+ */
+export function sortRouteTree(tree: RouteNode[]): RouteNode[] {
+  const sorted = [...tree].sort((a, b) => {
+    const oa = typeof a.meta?.order === 'number' ? (a.meta?.order as number) : Number(a.meta?.order)
+    const ob = typeof b.meta?.order === 'number' ? (b.meta?.order as number) : Number(b.meta?.order)
+    const av = Number.isFinite(oa) ? oa : Number.POSITIVE_INFINITY
+    const bv = Number.isFinite(ob) ? ob : Number.POSITIVE_INFINITY
+    if (av !== bv)
+      return av - bv
+    const at = String(a.meta?.title ?? a.path.split('/').filter(Boolean).pop() ?? '')
+    const bt = String(b.meta?.title ?? b.path.split('/').filter(Boolean).pop() ?? '')
+    return at.localeCompare(bt)
+  })
+  return sorted.map(n => ({
+    ...n,
+    children: n.children ? sortRouteTree(n.children) : []
+  }))
+}
+
+/**
+ * 过滤路由树
+ *
+ * 移除在 excludePaths 列表中的路径及其子路径。
+ *
+ * @param tree - 路由节点树
+ * @param excludePaths - 需要排除的路径列表（支持 glob 风格匹配逻辑的简化版，即前缀匹配）
+ * @returns 过滤后的新路由树
+ */
+export function filterRouteTree(tree: RouteNode[], excludePaths: string[] = []): RouteNode[] {
+  const norm = (p: string) => {
+    const s = p.startsWith('/') ? p : `/${p}`
+    const single = s.replace(/\/+/g, '/')
+    return single.length > 1 && single.endsWith('/') ? single.slice(0, -1) : single
+  }
+  const excludes = excludePaths.map(norm)
+  const match = (p: string) => {
+    const np = norm(p)
+    return excludes.some(ex => np === ex || np.startsWith(`${ex}/`))
+  }
+  return tree
+    .filter(n => !match(n.path))
+    .map(n => ({
+      ...n,
+      children: n.children ? filterRouteTree(n.children, excludePaths) : []
+    }))
+}
+
+/**
+ * 从原始路由配置生成可用的路由树（Composition API 钩子）
+ *
+ * 组合了标准化、转换树形结构、排序和过滤等步骤，返回一个计算属性。
+ *
+ * @param raw - 原始路由配置数组
+ * @param option - 配置选项
+ * @param option.excludePaths - 需要排除的路径列表
+ * @returns 包含响应式路由树的对象
+ */
+export function useRoutesTreeFromRaw(raw: RouteRecordRaw[], option?: { excludePaths?: string[] }): { routesTree: ComputedRef<RouteNode[]> } {
+  const normalized = normalizeAndRedirect(raw)
+  const baseTree = toRouteTree(normalized)
+  const routesTree = computed(() => sortRouteTree(filterRouteTree(baseTree, option?.excludePaths ?? [])))
+  return { routesTree }
+}

package/src/utils/tree.ts

@@ -0,0 +1,31 @@
+/**
+ * 递归遍历树结构，将节点的 children 字段为空数组时改为 null。
+ * @param arr 树节点数组
+ * @returns 处理后的新数组（不修改入参引用）
+ */
+export function convertEmptyChildrenToNull<T extends Record<string, any>>(arr: T[]): T[] {
+  if (!Array.isArray(arr))
+    return []
+
+  return arr.map((item) => {
+    if (!item || typeof item !== 'object')
+      return item
+
+    const children = (item as any).children
+
+    if (!Array.isArray(children))
+      return item
+
+    if (children.length === 0) {
+      return {
+        ...item,
+        children: null
+      }
+    }
+
+    return {
+      ...item,
+      children: convertEmptyChildrenToNull(children as any[])
+    } as T
+  })
+}