@mindbase/vue3-app-shell 1.0.0

package/README.md

@@ -0,0 +1,116 @@
+# @mindbase/vue3-app-shell
+
+Vue 3 通用应用壳基础包，提供响应式布局和 PWA 支持。
+
+## 特性
+
+- ✅ **插槽化布局**：灵活的插槽系统，支持自定义顶栏、侧边栏、内容区
+- ✅ **响应式设计**：自适应 PC 和移动端，断点优化
+- ✅ **抽屉式侧边栏**：PC 固定显示，移动端全屏抽屉（无遮罩）
+- ✅ **PWA 支持**：完整的 PWA 配置和安装引导
+- ✅ **移动端优化**：Element Plus 触摸优化、手势支持
+- ✅ **主题集成**：与 @mindbase/vue3-kit 主题系统集成
+
+## 安装
+
+```bash
+npm install @mindbase/vue3-app-shell
+```
+
+## 依赖
+
+```json
+{
+  "peerDependencies": {
+    "@mindbase/vue3-kit": "workspace:*",
+    "vue": "^3.4.0",
+    "pinia": "^2.1.0",
+    "vue-router": "^4.2.0",
+    "element-plus": "^2.5.0",
+    "hammerjs": "^2.0.8"
+  }
+}
+```
+
+## 使用
+
+### 基础用法
+
+```typescript
+import { createAppShell } from '@mindbase/vue3-app-shell'
+import '@mindbase/vue3-app-shell/dist/style.css'
+
+const { app, router } = createAppShell({
+  el: '#app',
+  pwa: {
+    title: '我的应用',
+    description: '添加到主屏幕，获得更好的体验'
+  }
+})
+
+app.mount('#app')
+```
+
+### 注册插槽
+
+```vue
+<script setup>
+import { useAppShellSlotsStore, AppShellSlotLocation } from '@mindbase/vue3-app-shell'
+
+const slotsStore = useAppShellSlotsStore()
+
+// 注册组件到顶栏左侧
+slotsStore.registerSlot({
+  location: AppShellSlotLocation.HEADER_LEFT,
+  component: MyCustomComponent
+})
+</script>
+```
+
+### 自定义侧边栏
+
+```vue
+<script setup>
+import { useAppShellSlotsStore, AppShellSlotLocation } from '@mindbase/vue3-app-shell'
+import MyMenu from './MyMenu.vue'
+
+const slotsStore = useAppShellSlotsStore()
+
+slotsStore.registerSlot({
+  location: AppShellSlotLocation.SIDEBAR,
+  component: MyMenu
+})
+</script>
+```
+
+## 插槽位置
+
+- `HEADER_LEFT`：顶栏左侧
+- `HEADER_CENTER`：顶栏中间
+- `HEADER_RIGHT`：顶栏右侧
+- `SIDEBAR`：侧边栏
+- `CONTENT_TOP`：内容区顶部
+- `CONTENT_BOTTOM`：内容区底部
+
+## 响应式断点
+
+- 小屏：< 768px（抽屉式侧边栏）
+- 中屏：768px - 1199px（固定侧边栏）
+- 大屏：≥ 1200px（固定侧边栏）
+
+## PWA 配置
+
+```typescript
+const pwaConfig = {
+  title: '安装应用',
+  description: '添加到主屏幕，获得更好的体验',
+  installButtonText: '安装',
+  cancelButtonText: '暂不安装',
+  dontShowAgainText: '不再提示',
+  autoShow: true
+}
+```
+
+## License
+
+MIT

package/composables/index.ts

@@ -0,0 +1,3 @@
+export * from './useBreakpoint'
+export * from './useDrawer'
+export * from './useTouchGesture'

package/composables/useBreakpoint.ts

@@ -0,0 +1,64 @@
+import { ref, computed, onMounted, onUnmounted } from 'vue'
+import type { Breakpoint } from '../types'
+
+// 断点阈值
+const BREAKPOINTS = {
+  small: 768,
+  medium: 1200
+}
+
+/**
+ * 响应式断点检测
+ */
+export function useBreakpoint() {
+  const windowWidth = ref(typeof window !== 'undefined' ? window.innerWidth : 1024)
+
+  // 更新窗口宽度
+  const updateWidth = () => {
+    windowWidth.value = window.innerWidth
+  }
+
+  // 当前断点
+  const breakpoint = computed<Breakpoint>(() => {
+    if (windowWidth.value < BREAKPOINTS.small) {
+      return 'small'
+    } else if (windowWidth.value < BREAKPOINTS.medium) {
+      return 'medium'
+    } else {
+      return 'large'
+    }
+  })
+
+  // 是否为小屏
+  const isSmall = computed(() => breakpoint.value === 'small')
+
+  // 是否为中屏
+  const isMedium = computed(() => breakpoint.value === 'medium')
+
+  // 是否为大屏
+  const isLarge = computed(() => breakpoint.value === 'large')
+
+  // 是否为移动端（小屏）
+  const isMobile = computed(() => breakpoint.value === 'small')
+
+  // 是否为桌面端（中屏或大屏）
+  const isDesktop = computed(() => breakpoint.value === 'medium' || breakpoint.value === 'large')
+
+  onMounted(() => {
+    window.addEventListener('resize', updateWidth)
+  })
+
+  onUnmounted(() => {
+    window.removeEventListener('resize', updateWidth)
+  })
+
+  return {
+    breakpoint,
+    windowWidth: computed(() => windowWidth.value),
+    isSmall,
+    isMedium,
+    isLarge,
+    isMobile,
+    isDesktop
+  }
+}

package/composables/useDrawer.ts

@@ -0,0 +1,66 @@
+import { computed } from 'vue'
+import { useAppShellLayoutStore } from '../store'
+import { useBreakpoint } from './useBreakpoint'
+
+/**
+ * 抽屉控制
+ * 统一管理 PC 端折叠和移动端抽屉
+ */
+export function useDrawer() {
+  const layoutStore = useAppShellLayoutStore()
+  const { isMobile } = useBreakpoint()
+
+  // PC 端：折叠状态
+  const collapsed = computed(() => layoutStore.collapsed)
+
+  // 移动端：抽屉可见状态
+  const visible = computed(() => layoutStore.drawerVisible)
+
+  // 是否为抽屉模式（移动端）
+  const isDrawerMode = computed(() => isMobile.value)
+
+  // 切换状态
+  const toggle = () => {
+    if (isMobile.value) {
+      layoutStore.toggleDrawer()
+    } else {
+      layoutStore.toggleCollapse()
+    }
+  }
+
+  // 打开
+  const open = () => {
+    if (isMobile.value) {
+      layoutStore.openDrawer()
+    } else {
+      layoutStore.setCollapse(false)
+    }
+  }
+
+  // 关闭
+  const close = () => {
+    if (isMobile.value) {
+      layoutStore.closeDrawer()
+    }
+    // PC 端不需要"关闭"操作，只能折叠
+  }
+
+  // 设置状态
+  const setState = (value: boolean) => {
+    if (isMobile.value) {
+      layoutStore.setDrawerVisible(value)
+    } else {
+      layoutStore.setCollapse(!value) // PC 端 false = 展开
+    }
+  }
+
+  return {
+    collapsed,
+    visible,
+    isDrawerMode,
+    toggle,
+    open,
+    close,
+    setState
+  }
+}

package/composables/useTouchGesture.ts

@@ -0,0 +1,165 @@
+import { onMounted, onUnmounted, type Ref } from 'vue'
+import Hammer from 'hammerjs'
+
+export interface GestureHandlers {
+  onSwipeLeft?: (event: Hammer.Input) => void
+  onSwipeRight?: (event: Hammer.Input) => void
+  onSwipeUp?: (event: Hammer.Input) => void
+  onSwipeDown?: (event: Hammer.Input) => void
+  onTap?: (event: Hammer.Input) => void
+  onDoubleTap?: (event: Hammer.Input) => void
+  onPan?: (event: Hammer.Input) => void
+  onPanStart?: (event: Hammer.Input) => void
+  onPanEnd?: (event: Hammer.Input) => void
+  onPress?: (event: Hammer.Input) => void
+}
+
+/**
+ * 触摸手势 composable
+ * 使用 Hammer.js 库
+ */
+export function useTouchGesture(
+  targetRef: Ref<HTMLElement | undefined | null>,
+  handlers: GestureHandlers,
+  options?: {
+    // 是否识别滑动手势
+    recognizeSwipe?: boolean
+    // 是否识别点击手势
+    recognizeTap?: boolean
+    // 是否识别双击手势
+    recognizeDoubleTap?: boolean
+    // 是否识别拖拽手势
+    recognizePan?: boolean
+    // 是否识别长按手势
+    recognizePress?: boolean
+    // 滑动阈值
+    swipeThreshold?: number
+  }
+) {
+  let hammerInstance: Hammer.Manager | null = null
+
+  const {
+    recognizeSwipe = true,
+    recognizeTap = true,
+    recognizeDoubleTap = false,
+    recognizePan = false,
+    recognizePress = false,
+    swipeThreshold = 10
+  } = options || {}
+
+  onMounted(() => {
+    const element = targetRef.value
+    if (!element) return
+
+    // 创建 Hammer 实例
+    hammerInstance = new Hammer.Manager(element, {
+      touchAction: 'auto'
+    })
+
+    // 添加滑动手势识别器
+    if (recognizeSwipe) {
+      const swipe = new Hammer.Swipe({ threshold: swipeThreshold })
+      hammerInstance.add(swipe)
+
+      if (handlers.onSwipeLeft) {
+        swipe.recognizeWith(hammerInstance.get('swipe'))
+        hammerInstance.on('swipeleft', handlers.onSwipeLeft)
+      }
+      if (handlers.onSwipeRight) {
+        hammerInstance.on('swiperight', handlers.onSwipeRight)
+      }
+      if (handlers.onSwipeUp) {
+        hammerInstance.on('swipeup', handlers.onSwipeUp)
+      }
+      if (handlers.onSwipeDown) {
+        hammerInstance.on('swipedown', handlers.onSwipeDown)
+      }
+    }
+
+    // 添加点击手势识别器
+    if (recognizeTap) {
+      const tap = new Hammer.Tap()
+      hammerInstance.add(tap)
+
+      if (handlers.onTap) {
+        hammerInstance.on('tap', handlers.onTap)
+      }
+    }
+
+    // 添加双击手势识别器
+    if (recognizeDoubleTap) {
+      const doubleTap = new Hammer.Tap({ event: 'doubletap', taps: 2 })
+      hammerInstance.add(doubleTap)
+
+      if (handlers.onDoubleTap) {
+        hammerInstance.on('doubletap', handlers.onDoubleTap)
+      }
+    }
+
+    // 添加拖拽手势识别器
+    if (recognizePan) {
+      const pan = new Hammer.Pan()
+      hammerInstance.add(pan)
+
+      if (handlers.onPan) {
+        hammerInstance.on('pan', handlers.onPan)
+      }
+      if (handlers.onPanStart) {
+        hammerInstance.on('panstart', handlers.onPanStart)
+      }
+      if (handlers.onPanEnd) {
+        hammerInstance.on('panend', handlers.onPanEnd)
+      }
+    }
+
+    // 添加长按手势识别器
+    if (recognizePress) {
+      const press = new Hammer.Press({ time: 500 })
+      hammerInstance.add(press)
+
+      if (handlers.onPress) {
+        hammerInstance.on('press', handlers.onPress)
+      }
+    }
+  })
+
+  onUnmounted(() => {
+    if (hammerInstance) {
+      hammerInstance.destroy()
+      hammerInstance = null
+    }
+  })
+
+  return {
+    hammerInstance
+  }
+}
+
+/**
+ * 抽屉手势 composable
+ * 专门用于抽屉的滑动手势
+ */
+export function useDrawerGesture(
+  targetRef: Ref<HTMLElement | undefined | null>,
+  onOpen: () => void,
+  onClose: () => void,
+  isOpen: boolean
+) {
+  useTouchGesture(targetRef, {
+    onSwipeRight: (event) => {
+      // 右滑打开抽屉
+      if (!isOpen) {
+        onOpen()
+      }
+    },
+    onSwipeLeft: (event) => {
+      // 左滑关闭抽屉
+      if (isOpen) {
+        onClose()
+      }
+    }
+  }, {
+    recognizeSwipe: true,
+    swipeThreshold: 30
+  })
+}

package/createAppShell.ts

@@ -0,0 +1,82 @@
+import type { App } from 'vue'
+import { createBaseApp, type CreateBaseAppOptions } from '@mindbase/vue3-kit'
+import { AppShellLayout } from './layout'
+import { useAppShellPWAStore } from './store'
+import type { AppShellOptions, AppShellResult } from './types'
+
+/**
+ * 创建 App Shell 应用
+ */
+export function createAppShell(options: AppShellOptions = {}): AppShellResult {
+  const {
+    el = '#app',
+    router: routerOptions = {},
+    pwa: pwaConfig = {},
+    layout: layoutConfig = {},
+    setupPinia = true,
+    setupRouter = true
+  } = options
+
+  // 创建基础应用（复用 vue3-kit 的 createBaseApp）
+  const result = createBaseApp({
+    el,
+    router: routerOptions,
+    setupPinia,
+    setupRouter
+  })
+
+  const { app, router, pinia } = result
+
+  // 封装 mount 函数，在 mounted 后执行初始化
+  const originalMount = app.mount
+  app.mount = (mountEl: HTMLElement | string) => {
+    const mountResult = originalMount(mountEl)
+
+    // 在 mounted 状态执行初始化
+    if (setupPinia && pinia) {
+      // 设置 PWA 配置
+      if (pwaConfig && Object.keys(pwaConfig).length > 0) {
+        const pwaStore = useAppShellPWAStore()
+        pwaStore.setConfig(pwaConfig.installPrompt || {})
+        setupPWA(pwaStore)
+      }
+    }
+
+    return mountResult
+  }
+
+  return {
+    app,
+    router,
+    pinia
+  }
+}
+
+/**
+ * 设置 PWA
+ */
+function setupPWA(pwaStore: ReturnType<typeof useAppShellPWAStore>) {
+  if (typeof window === 'undefined') return
+
+  // 监听 beforeinstallprompt 事件
+  window.addEventListener('beforeinstallprompt', (event) => {
+    // 阻止默认的安装提示
+    event.preventDefault()
+
+    // 保存事件，稍后触发
+    pwaStore.setDeferredPrompt(event)
+    pwaStore.setCanInstall(true)
+
+    // 如果配置了自动显示，则显示提示
+    if (pwaStore.config.autoShow) {
+      pwaStore.showPrompt()
+    }
+  })
+
+  // 监听 appinstalled 事件
+  window.addEventListener('appinstalled', () => {
+    pwaStore.setIsInstalled(true)
+    pwaStore.setCanInstall(false)
+    pwaStore.hidePrompt()
+  })
+}

package/index.ts

@@ -0,0 +1,20 @@
+// 核心函数
+export { createAppShell } from './createAppShell'
+
+// 类型定义
+export * from './types'
+
+// 布局组件
+export * from './layout'
+
+// Store
+export * from './store'
+
+// Composables
+export * from './composables'
+
+// PWA
+export * from './pwa'
+
+// 样式
+import './styles/index.scss'

package/layout/AppShellLayout.vue

@@ -0,0 +1,41 @@
+<template>
+  <section class="app-shell">
+    <!-- 顶栏 -->
+    <app-header />
+
+    <!-- 主体区域 -->
+    <section class="app-shell__body">
+      <!-- 侧边栏（抽屉式） -->
+      <app-drawer />
+
+      <!-- 主内容区 -->
+      <app-main />
+    </section>
+
+    <!-- PWA 安装引导 -->
+    <pwa-install-prompt />
+  </section>
+</template>
+
+<script setup lang="ts">
+import AppHeader from './components/AppHeader.vue'
+import AppDrawer from './components/AppDrawer.vue'
+import AppMain from './components/AppMain.vue'
+import PWAInstallPrompt from './components/PWAInstallPrompt.vue'
+</script>
+
+<style lang="scss">
+.app-shell {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100vh;
+  overflow: hidden;
+
+  .app-shell__body {
+    flex: 1;
+    display: flex;
+    overflow: hidden;
+  }
+}
+</style>

package/layout/components/AppDrawer.vue

@@ -0,0 +1,87 @@
+<template>
+  <!-- PC 端：固定侧边栏 -->
+  <aside
+    class="app-drawer app-drawer--pc"
+    :class="{ 'is-collapsed': collapsed }">
+    <template v-for="slot in sidebarSlots" :key="slot">
+      <component :is="slot.component" v-bind="slot.props" />
+    </template>
+  </aside>
+
+  <!-- 移动端：全屏抽屉（条件渲染） -->
+  <teleport to="body">
+    <aside
+      class="app-drawer app-drawer--mobile"
+      :class="{ visible: drawerVisible }">
+      <template v-for="slot in sidebarSlots" :key="slot">
+        <component :is="slot.component" v-bind="slot.props" />
+      </template>
+    </aside>
+  </teleport>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { storeToRefs } from 'pinia'
+import { useAppShellLayoutStore, useAppShellSlotsStore } from '../../store'
+
+const layoutStore = useAppShellLayoutStore()
+const slotsStore = useAppShellSlotsStore()
+
+const { collapsed, drawerVisible } = storeToRefs(layoutStore)
+const { sidebar } = storeToRefs(slotsStore)
+</script>
+
+<style lang="scss">
+/* PC 端：固定左侧 */
+@media (min-width: 768px) {
+  .app-drawer--pc {
+    display: block;
+    position: fixed;
+    left: 0;
+    top: var(--mb-app-shell-header-height, 60px);
+    bottom: 0;
+    width: var(--mb-app-shell-drawer-width, 240px);
+    background-color: var(--mb-app-shell-drawer-bg, #ffffff);
+    border-right: var(--mb-app-shell-drawer-border-right, 1px solid #e4e7ed);
+    transition: width 0.3s ease;
+    overflow-y: auto;
+    overflow-x: hidden;
+    z-index: 1000;
+
+    &.is-collapsed {
+      width: var(--mb-app-shell-drawer-collapsed-width, 64px);
+    }
+  }
+
+  .app-drawer--mobile {
+    display: none;
+  }
+}
+
+/* 移动端：全屏抽屉（无遮罩） */
+@media (max-width: 767px) {
+  .app-drawer--pc {
+    display: none;
+  }
+
+  .app-drawer--mobile {
+    display: block;
+    position: fixed;
+    left: 0;
+    top: 0;
+    bottom: 0;
+    width: 100%;
+    background-color: var(--mb-app-shell-drawer-bg, #ffffff);
+    transform: translateX(-100%);
+    transition: transform 0.3s ease;
+    overflow-y: auto;
+    overflow-x: hidden;
+    z-index: 9999;
+
+    &.visible {
+      transform: translateX(0);
+    }
+  }
+}
+</style>