@quiteer/naive-extra 0.0.1

package/src/components/layout/layout-parts/AppSidebar.vue

@@ -0,0 +1,174 @@
+<script setup lang="ts">
+import type { MenuInst, MenuOption } from 'naive-ui'
+// 解决 TS2742: The inferred type cannot be named without a reference to ...
+// 显式引用这些类型以确保生成的声明文件是可移植的
+import type {} from 'treemate'
+import type { Slots } from 'vue'
+import type {} from 'vueuc'
+import { computed, ref, unref, useSlots, watch } from 'vue'
+import { useRouter } from 'vue-router'
+import { hasSlotContent } from '../../../share/slot'
+import { SIDE_GROUP_LAYOUT_TYPES, SIDE_MIXED_LAYOUT_TYPES } from '../const'
+import { useContext } from '../context'
+
+import { findNodeByKey, renderMenuLabel, resolveMainSubFromActive, updateMenuTree } from '../utils'
+import AppLeftLogoInfo from './AppLeftLogoInfo.vue'
+
+const { isCollapsed, collapsedWidth, siderWidth, headerHeight, bordered, inverted, isLeftMain, isTopMain, activeKey, mainActiveKey, subActiveKey, type, menuOptions: options, mainMenuOptions, subMenuOptions, updateActiveKey, updateIsCollapsed, accordion, hasSiderLayout } = useContext()!
+
+const menuInstRef = ref<MenuInst | null>(null)
+
+const width = computed<number>(() => {
+  if (unref(isCollapsed))
+    return unref(collapsedWidth)!
+
+  return unref(siderWidth)!
+})
+
+function handleUpdateCollapsed(v: boolean) {
+  updateIsCollapsed(v)
+}
+
+const isSideMixedMenu = computed<boolean>(() => SIDE_MIXED_LAYOUT_TYPES.includes(unref(type)))
+const isSideGroupMenu = computed<boolean>(() => SIDE_GROUP_LAYOUT_TYPES.includes(unref(type)))
+
+const active = ref('')
+const expandedKeys = ref<string[]>([])
+
+function handleUpdateExpandedKeys(keys: string[]) {
+  expandedKeys.value = keys
+}
+
+// 统一处理激活状态和滚动/展开
+watch(() => unref(activeKey), (newKey) => {
+  if (!newKey)
+    return
+
+  const { mainKey, subKey } = resolveMainSubFromActive(unref(options) as any[], newKey)
+  mainActiveKey.value = mainKey || ''
+  subActiveKey.value = subKey || ''
+
+  if (unref(type) === 'side-menu' || unref(type) === 'side-group-menu' || unref(type) === 'side-mixed-menu') {
+    active.value = newKey
+  }
+  else {
+    if (unref(isLeftMain)) {
+      active.value = mainKey || ''
+    }
+
+    if (unref(isTopMain)) {
+      active.value = subKey || ''
+    }
+  }
+
+  // 只有在激活项变化时才调用 showOption，避免干扰手动展开/收起
+  if (active.value) {
+    menuInstRef.value?.showOption(active.value)
+  }
+}, { immediate: true })
+
+const router = useRouter()
+function handleUpdateValue(key: string) {
+  const node = findNodeByKey(unref(options) as any[], key)
+  if (node?.href || /^https?:\/\//.test(key)) {
+    return
+  }
+
+  updateActiveKey(key)
+  active.value = key
+  menuInstRef.value?.showOption(key)
+
+  if (unref(isLeftMain) && hasSiderLayout.value) {
+    const { subKey } = resolveMainSubFromActive(unref(options) as any[], key)
+    if (subKey) {
+      if (subKey.startsWith('/')) {
+        router.push(subKey)
+      }
+      else {
+        router.push({ name: subKey })
+      }
+    }
+  }
+}
+
+const menuOptions = computed(() => {
+  const transformToGroups = (items: MenuOption[]): MenuOption[] => {
+    return updateMenuTree(items as any[], (item) => {
+      if (item.children && item.children.length > 0) {
+        return { ...item, type: 'group' } as MenuOption
+      }
+      return item
+    }) as MenuOption[]
+  }
+
+  // 1. 获取基础菜单项
+  let baseOptions: MenuOption[] = []
+  const currentType = unref(type)
+  if (currentType === 'side-menu' || currentType === 'side-group-menu' || currentType === 'side-mixed-menu') {
+    // 如果是左侧主菜单类布局（非混合顶部），使用完整选项
+    baseOptions = unref(options) || []
+  }
+  else {
+    // 否则（如 top-menu/2, top-group-menu/2 等），根据主次关系选择子菜单
+    baseOptions = unref(isLeftMain) ? unref(mainMenuOptions) : unref(subMenuOptions)
+  }
+
+  // 2. 根据布局类型进行转换
+  if (isSideGroupMenu.value) {
+    return transformToGroups(baseOptions)
+  }
+
+  if (isSideMixedMenu.value) {
+    // 混合菜单：第一层保持原样（通常是图标），第二层开始转为 group
+    return baseOptions.map((item) => {
+      if (item.children && item.children.length) {
+        return {
+          ...item,
+          children: transformToGroups(item.children)
+        }
+      }
+      return item
+    })
+  }
+
+  return baseOptions
+})
+
+const slots: Slots = useSlots()
+const hasDefaultSlot = computed<boolean>(() => hasSlotContent(slots.default))
+</script>
+
+<template>
+  <n-layout-sider
+    class="transition-all duration-300 relative"
+    position="absolute"
+    collapse-mode="width"
+    show-trigger="bar"
+    :width="width"
+    :collapsed-width="collapsedWidth"
+    :bordered="bordered"
+    :inverted="inverted"
+    :collapsed="isCollapsed"
+    :native-scrollbar="false"
+    :style="{ top: unref(isTopMain) ? `${unref(headerHeight)}px` : 0 }"
+    @update:collapsed="handleUpdateCollapsed"
+  >
+    <div v-if="isLeftMain">
+      <slot v-if="hasDefaultSlot" />
+      <AppLeftLogoInfo v-else />
+    </div>
+
+    <n-menu
+      ref="menuInstRef"
+      :value="active"
+      :expanded-keys="expandedKeys"
+      :options="menuOptions"
+      :render-label="renderMenuLabel"
+      :collapsed-width="collapsedWidth"
+      :inverted="inverted"
+      :accordion="accordion"
+      @update:value="handleUpdateValue"
+      @update:expanded-keys="handleUpdateExpandedKeys"
+    />
+  </n-layout-sider>
+</template>

package/src/components/layout/layout-parts/LayoutTransition.vue

@@ -0,0 +1,366 @@
+<script setup lang="ts">
+/**
+ * 通用布局过渡组件
+ *
+ * 为侧边栏、头部、底部、内容区域提供统一的进场/出场动画能力，
+ * 通过 `mode` 控制动画类型，适配宽度/高度/位移/透明等常见过渡。
+ *
+ * @param props.mode - 动画模式：'fade' | 'slide-x' | 'slide-y' | 'scale' | 'width' | 'height'
+ * @param props.duration - 过渡时长（毫秒），默认 250
+ * @param props.easing - 缓动函数，默认 cubic-bezier(0.25,0.46,0.45,0.94)
+ * @returns 无返回值（渲染一个 <Transition> 包裹的插槽）
+ *
+ * @example
+ * ```vue
+ * <LayoutTransition mode="width">
+ *   <AppSidebar v-if="showSider" />
+ * </LayoutTransition>
+ * ```
+ *
+ * @remarks
+ * - width/height 模式使用 scrollWidth/scrollHeight 进行展开动画，before-leave 固定当前尺寸避免抖动
+ * - slide-x/slide-y 使用 transform 与 opacity 联合过渡
+ * - scale 使用轻微缩放与透明度过渡
+ *
+ * @security
+ * - 仅修改元素内联样式；不涉及外部副作用
+ *
+ * @performance
+ * - 依赖浏览器原生过渡；时间复杂度与节点尺寸无关
+ */
+const props = withDefaults(defineProps<{
+  mode?: 'fade' | 'slide-x' | 'slide-y' | 'scale' | 'width' | 'height'
+  duration?: number
+  easing?: string
+  appear?: boolean
+}>(), {
+  mode: 'fade',
+  duration: 250,
+  easing: 'cubic-bezier(0.25, 0.46, 0.45, 0.94)',
+  appear: true
+})
+
+/**
+ * 设置通用过渡样式
+ * 将 transition 应用于节点，按需组合属性。
+ */
+function setTransition(node: HTMLElement, propsList: string[]) {
+  node.style.transition = propsList.map(p => `${p} ${props.duration}ms ${props.easing}`).join(', ')
+}
+
+/**
+ * 宽度入场动画（展开）
+ *
+ * 初始 width=0，随后过渡到 scrollWidth，实现展开效果。
+ *
+ * @param el - 进入的元素
+ */
+function widthEnter(el: Element) {
+  const node = el as HTMLElement
+  const computedStyle = window.getComputedStyle(node)
+  const target
+    = Number.parseFloat(computedStyle.width || '0')
+      || node.getBoundingClientRect().width
+      || node.offsetWidth
+      || node.scrollWidth
+  if (!target || target <= 0) {
+    node.style.transition = ''
+    node.style.overflow = ''
+    node.style.width = ''
+    return
+  }
+  node.style.overflow = 'hidden'
+  node.style.width = '0px'
+  setTransition(node, ['width'])
+  requestAnimationFrame(() => {
+    node.style.width = `${target}px`
+  })
+}
+
+/**
+ * 宽度离场前动画（收起）
+ *
+ * 固定当前宽度，然后过渡到 0。
+ *
+ * @param el - 离场的元素
+ */
+function widthBeforeLeave(el: Element) {
+  const node = el as HTMLElement
+  const current = node.offsetWidth
+  node.style.overflow = 'hidden'
+  node.style.width = `${current}px`
+  setTransition(node, ['width'])
+  requestAnimationFrame(() => {
+    node.style.width = '0px'
+  })
+}
+
+/**
+ * 高度入场动画（展开）
+ *
+ * 初始 height=0，随后过渡到 scrollHeight，实现展开效果。
+ *
+ * @param el - 进入的元素
+ */
+function heightEnter(el: Element) {
+  const node = el as HTMLElement
+  const target = node.scrollHeight
+  node.style.overflow = 'hidden'
+  node.style.height = '0px'
+  setTransition(node, ['height'])
+  requestAnimationFrame(() => {
+    node.style.height = `${target}px`
+  })
+}
+
+/**
+ * 高度离场前动画（收起）
+ *
+ * 固定当前高度，然后过渡到 0。
+ *
+ * @param el - 离场的元素
+ */
+function heightBeforeLeave(el: Element) {
+  const node = el as HTMLElement
+  const current = node.offsetHeight
+  node.style.overflow = 'hidden'
+  node.style.height = `${current}px`
+  setTransition(node, ['height'])
+  requestAnimationFrame(() => {
+    node.style.height = '0px'
+  })
+}
+
+/**
+ * 透明入场动画
+ *
+ * opacity: 0 -> 1
+ *
+ * @param el - 进入的元素
+ */
+function fadeEnter(el: Element) {
+  const node = el as HTMLElement
+  node.style.opacity = '0'
+  setTransition(node, ['opacity'])
+  requestAnimationFrame(() => {
+    node.style.opacity = '1'
+  })
+}
+
+/**
+ * 透明离场前动画
+ *
+ * opacity: 1 -> 0
+ *
+ * @param el - 离场的元素
+ */
+function fadeBeforeLeave(el: Element) {
+  const node = el as HTMLElement
+  node.style.opacity = '1'
+  setTransition(node, ['opacity'])
+  requestAnimationFrame(() => {
+    node.style.opacity = '0'
+  })
+}
+
+/**
+ * 横向位移入场动画
+ *
+ * transform: translateX(-8px) -> 0, opacity: 0 -> 1
+ *
+ * @param el - 进入的元素
+ */
+function slideXEnter(el: Element) {
+  const node = el as HTMLElement
+  node.style.opacity = '0'
+  node.style.transform = 'translateX(-8px)'
+  setTransition(node, ['transform', 'opacity'])
+  requestAnimationFrame(() => {
+    node.style.opacity = '1'
+    node.style.transform = 'translateX(0)'
+  })
+}
+
+/**
+ * 横向位移离场前动画
+ *
+ * transform: 0 -> translateX(-8px), opacity: 1 -> 0
+ *
+ * @param el - 离场的元素
+ */
+function slideXBeforeLeave(el: Element) {
+  const node = el as HTMLElement
+  node.style.opacity = '1'
+  node.style.transform = 'translateX(0)'
+  setTransition(node, ['transform', 'opacity'])
+  requestAnimationFrame(() => {
+    node.style.opacity = '0'
+    node.style.transform = 'translateX(-8px)'
+  })
+}
+
+/**
+ * 纵向位移入场动画
+ *
+ * transform: translateY(-6px) -> 0, opacity: 0 -> 1
+ *
+ * @param el - 进入的元素
+ */
+function slideYEnter(el: Element) {
+  const node = el as HTMLElement
+  node.style.opacity = '0'
+  node.style.transform = 'translateY(-6px)'
+  setTransition(node, ['transform', 'opacity'])
+  requestAnimationFrame(() => {
+    node.style.opacity = '1'
+    node.style.transform = 'translateY(0)'
+  })
+}
+
+/**
+ * 纵向位移离场前动画
+ *
+ * transform: 0 -> translateY(-6px), opacity: 1 -> 0
+ *
+ * @param el - 离场的元素
+ */
+function slideYBeforeLeave(el: Element) {
+  const node = el as HTMLElement
+  node.style.opacity = '1'
+  node.style.transform = 'translateY(0)'
+  setTransition(node, ['transform', 'opacity'])
+  requestAnimationFrame(() => {
+    node.style.opacity = '0'
+    node.style.transform = 'translateY(-6px)'
+  })
+}
+
+/**
+ * 轻微缩放入场动画
+ *
+ * scale: 0.98 -> 1, opacity: 0 -> 1
+ *
+ * @param el - 进入的元素
+ */
+function scaleEnter(el: Element) {
+  const node = el as HTMLElement
+  node.style.opacity = '0'
+  node.style.transform = 'scale(0.98)'
+  setTransition(node, ['transform', 'opacity'])
+  requestAnimationFrame(() => {
+    node.style.opacity = '1'
+    node.style.transform = 'scale(1)'
+  })
+}
+
+/**
+ * 轻微缩放离场前动画
+ *
+ * scale: 1 -> 0.98, opacity: 1 -> 0
+ *
+ * @param el - 离场的元素
+ */
+function scaleBeforeLeave(el: Element) {
+  const node = el as HTMLElement
+  node.style.opacity = '1'
+  node.style.transform = 'scale(1)'
+  setTransition(node, ['transform', 'opacity'])
+  requestAnimationFrame(() => {
+    node.style.opacity = '0'
+    node.style.transform = 'scale(0.98)'
+  })
+}
+
+/**
+ * 清理动画样式
+ *
+ * 移除过渡、溢出、尺寸、透明度、位移等，避免影响后续布局。
+ *
+ * @param el - 离场后的元素
+ */
+function afterLeave(el: Element) {
+  const node = el as HTMLElement
+  node.style.transition = ''
+  node.style.overflow = ''
+  node.style.width = ''
+  node.style.height = ''
+  node.style.opacity = ''
+  node.style.transform = ''
+}
+
+/**
+ * 统一进场处理
+ *
+ * 根据 `mode` 分派具体动画。
+ *
+ * @param el - 进入元素
+ */
+function handleEnter(el: Element) {
+  switch (props.mode) {
+    case 'width':
+      widthEnter(el)
+      break
+    case 'height':
+      heightEnter(el)
+      break
+    case 'slide-x':
+      slideXEnter(el)
+      break
+    case 'slide-y':
+      slideYEnter(el)
+      break
+    case 'scale':
+      scaleEnter(el)
+      break
+    default:
+      fadeEnter(el)
+  }
+}
+
+/**
+ * 统一离场前处理
+ *
+ * 根据 `mode` 分派具体动画。
+ *
+ * @param el - 离场元素
+ */
+function handleBeforeLeave(el: Element) {
+  switch (props.mode) {
+    case 'width':
+      widthBeforeLeave(el)
+      break
+    case 'height':
+      heightBeforeLeave(el)
+      break
+    case 'slide-x':
+      slideXBeforeLeave(el)
+      break
+    case 'slide-y':
+      slideYBeforeLeave(el)
+      break
+    case 'scale':
+      scaleBeforeLeave(el)
+      break
+    default:
+      fadeBeforeLeave(el)
+  }
+}
+</script>
+
+<template>
+  <Transition
+    :appear="props.appear"
+    @enter="handleEnter"
+    @before-leave="handleBeforeLeave"
+    @after-leave="afterLeave"
+  >
+    <slot />
+  </Transition>
+  <!-- 用法：
+    <LayoutTransition mode="width"><AppSidebar v-if="hasSider"/></LayoutTransition>
+    <LayoutTransition mode="height"><AppHeader v-if="showHeader"/></LayoutTransition>
+    <LayoutTransition mode="fade"><AppMain v-if="ready"/></LayoutTransition>
+  -->
+</template>
+
+<style scoped></style>

package/src/components/layout/props.ts

@@ -0,0 +1,36 @@
+import type { MenuOption } from 'naive-ui'
+import type { RouteRecordRaw } from 'vue-router'
+import type { LayoutType } from './types'
+
+export type Props = Partial<{
+  /** @description 布局类型 */
+  type: LayoutType
+  /** @description 是否显示边框 */
+  bordered: boolean
+  /** @description 反色样式（Header/Sider/Footer/Menu） */
+  inverted: boolean
+  /** @description 是否折叠侧边栏 */
+  isCollapsed: boolean
+  /** @description 是否显示底部 */
+  showFooter: boolean
+  /** @description 头部高度 */
+  headerHeight: number
+  /** @description 底部高度 */
+  footerHeight: number
+  /** @description 底部是否占满宽度 */
+  footerFull: boolean
+  /** @description 侧边栏宽度 */
+  siderWidth: number
+  /** @description 侧边栏混合模式的宽度 */
+  siderMixedWidth: number
+  /** @description 折叠侧边栏宽度 */
+  collapsedWidth: number
+  /** @description 当前激活的路由键 */
+  activeKey: string
+  /** @description 菜单路由 */
+  menuOptions: MenuOption[]
+  /** @description 基础路由 */
+  baseRoutes: RouteRecordRaw[]
+  /** @description 是否开启手风琴模式 */
+  accordion: boolean
+}>

package/src/components/layout/types.ts

@@ -0,0 +1,79 @@
+/**
+ * 应用布局类型枚举（格式：[主要]-[侧边栏模式]-[菜单选项]）
+ * 用于动态切换页面整体结构，省略 "layout" 后缀以保持简洁
+ */
+export type LayoutType
+  = | 'side-menu'
+    | 'side-menu/2'
+    | 'side-mixed-menu'
+    | 'side-group-menu'
+    | 'top-menu'
+    | 'top-menu/2'
+    | 'top-group-menu/2'
+    | 'top-mixed-menu/2'
+    | 'blank'
+
+export interface RouteMeta {
+  /**
+   * 页面标题（用于 document.title 或 tab 标签）
+   */
+  title?: string
+
+  /**
+   * 是否需要认证（true: 需登录，false: 免登录）
+   * @default true
+   */
+  requiresAuth?: boolean
+
+  /**
+   * 所需权限（字符串数组或字符串）
+   */
+  permissions?: string | string[]
+
+  /**
+   * 所属角色（如 'admin', 'user'）
+   */
+  roles?: string[]
+
+  /**
+   * 是否在侧边栏菜单中显示
+   * @default false
+   */
+  hideMenu?: boolean
+
+  /**
+   * 侧边栏菜单选中
+   * @default string
+   */
+  activeMenu?: import('vue-router').RouteRecordRedirectOption
+
+  /**
+   * 菜单图标（Iconify 格式，如 'mdi:home'）
+   */
+  icon?: string
+
+  /**
+   * 使用的布局名称（如 'blank', 'main'）
+   */
+  layout?: LayoutType
+
+  /**
+   * 是否开启 keep-alive 缓存
+   */
+  keepAlive?: boolean
+
+  /**
+   * 页面过渡动画名
+   */
+  transition?: string
+
+  /**
+   * 排序
+   */
+  order?: number
+
+  /**
+   * 外链
+   */
+  href?: string
+}