@mindbase/vue3-app-shell 1.0.0

package/store/pwa.ts

@@ -0,0 +1,141 @@
+import { defineStore } from 'pinia'
+import { ref, computed } from 'vue'
+import { getStorage, setStorage } from '@mindbase/vue3-kit/utils/storage'
+import type { PWAInstallState, PWAInstallConfig } from '../types'
+
+const STORAGE_KEY = 'pwa_install_dont_show_again'
+const DEFAULT_CONFIG: PWAInstallConfig = {
+  title: '安装应用',
+  description: '添加到主屏幕，获得更好的体验',
+  installButtonText: '安装',
+  cancelButtonText: '暂不安装',
+  dontShowAgainText: '不再提示',
+  autoShow: true
+}
+
+/**
+ * App Shell PWA 状态管理
+ */
+export const useAppShellPWAStore = defineStore('appShellPWA', () => {
+  // 配置
+  const config = ref<PWAInstallConfig>(DEFAULT_CONFIG)
+
+  // 状态
+  const canInstall = ref(false)
+  const isInstalled = ref(false)
+  const promptVisible = ref(false)
+  const deferredPrompt = ref<Event | null>(null)
+
+  // "不再提示"状态（从 storage 读取）
+  const dontShowAgain = ref(getStorage<boolean>(STORAGE_KEY) ?? false)
+
+  /**
+   * 设置 PWA 配置
+   */
+  function setConfig(newConfig: Partial<PWAInstallConfig>) {
+    config.value = { ...DEFAULT_CONFIG, ...newConfig }
+  }
+
+  /**
+   * 设置可安装状态
+   */
+  function setCanInstall(value: boolean) {
+    canInstall.value = value
+  }
+
+  /**
+   * 设置已安装状态
+   */
+  function setIsInstalled(value: boolean) {
+    isInstalled.value = value
+  }
+
+  /**
+   * 保存延迟的安装事件
+   */
+  function setDeferredPrompt(event: Event | null) {
+    deferredPrompt.value = event
+  }
+
+  /**
+   * 显示安装提示
+   */
+  function showPrompt() {
+    if (canInstall.value && !isInstalled.value && !dontShowAgain.value) {
+      promptVisible.value = true
+    }
+  }
+
+  /**
+   * 隐藏安装提示
+   */
+  function hidePrompt() {
+    promptVisible.value = false
+  }
+
+  /**
+   * 设置"不再提示"
+   */
+  function setDontShowAgain(value: boolean) {
+    dontShowAgain.value = value
+    setStorage(STORAGE_KEY, value)
+    if (value) {
+      hidePrompt()
+    }
+  }
+
+  /**
+   * 触发安装
+   */
+  async function promptInstall() {
+    const promptEvent = deferredPrompt.value as any
+    if (!promptEvent) {
+      console.warn('No deferred prompt event available')
+      return
+    }
+
+    // 显示原生安装提示
+    promptEvent.prompt()
+
+    // 等待用户响应
+    const { outcome } = await promptEvent.userChoice
+
+    if (outcome === 'accepted') {
+      setIsInstalled(true)
+    }
+
+    // 清除延迟的事件
+    setDeferredPrompt(null)
+    hidePrompt()
+  }
+
+  // 计算属性：是否应该显示提示
+  const shouldShowPrompt = computed(() => {
+    return (
+      config.value.autoShow &&
+      canInstall.value &&
+      !isInstalled.value &&
+      !dontShowAgain.value
+    )
+  })
+
+  return {
+    config,
+    canInstall,
+    isInstalled,
+    dontShowAgain,
+    promptVisible,
+    deferredPrompt,
+    shouldShowPrompt,
+    setConfig,
+    setCanInstall,
+    setIsInstalled,
+    setDeferredPrompt,
+    showPrompt,
+    hidePrompt,
+    setDontShowAgain,
+    promptInstall
+  }
+})
+
+export type AppShellPWAStore = ReturnType<typeof useAppShellPWAStore>

package/store/slots.ts

@@ -0,0 +1,68 @@
+import { defineStore } from 'pinia'
+import { reactive, computed } from 'vue'
+import type { Component } from 'vue'
+import { AppShellSlotLocation, type AppShellSlotRegistration } from '../types'
+
+/**
+ * App Shell 插槽状态管理
+ */
+export const useAppShellSlotsStore = defineStore('appShellSlots', () => {
+  const slots = reactive<Record<string, AppShellSlotRegistration[]>>({})
+
+  /**
+   * 注册插槽
+   */
+  function registerSlot(registration: AppShellSlotRegistration) {
+    const { location, component } = registration
+
+    if (!slots[location]) {
+      slots[location] = []
+    }
+
+    // 检查是否已存在相同的组件
+    const isDuplicate = slots[location].some((slot) => slot.component === component)
+    if (isDuplicate) {
+      console.warn(`Component already registered for location: ${location}`)
+      return
+    }
+
+    slots[location].push(registration)
+  }
+
+  /**
+   * 清空插槽
+   */
+  function clearSlots(location?: string) {
+    if (location) {
+      slots[location] = []
+    } else {
+      Object.keys(slots).forEach((key) => {
+        slots[key] = []
+      })
+    }
+  }
+
+  // 为每个位置创建计算属性
+  const headerLeft = computed(() => slots[AppShellSlotLocation.HEADER_LEFT] || [])
+  const headerCenter = computed(() => slots[AppShellSlotLocation.HEADER_CENTER] || [])
+  const headerRight = computed(() => slots[AppShellSlotLocation.HEADER_RIGHT] || [])
+  const sidebar = computed(() => slots[AppShellSlotLocation.SIDEBAR] || [])
+  const contentTop = computed(() => slots[AppShellSlotLocation.CONTENT_TOP] || [])
+  const contentBottom = computed(() => slots[AppShellSlotLocation.CONTENT_BOTTOM] || [])
+
+  return {
+    slots,
+    // 计算属性
+    headerLeft,
+    headerCenter,
+    headerRight,
+    sidebar,
+    contentTop,
+    contentBottom,
+    // 方法
+    registerSlot,
+    clearSlots
+  }
+})
+
+export type AppShellSlotsStore = ReturnType<typeof useAppShellSlotsStore>

package/styles/drawer.scss

@@ -0,0 +1,62 @@
+// 抽屉样式
+@import './variables.scss';
+
+// PC 端抽屉（固定侧边栏）
+.app-drawer--pc {
+  transition: width var(--mb-app-shell-transition-duration, 0.3s) var(--mb-app-shell-transition-function, ease);
+
+  &.is-collapsed {
+    // 折叠状态下的样式
+    &:deep(*) {
+      // 隐藏文本内容
+      .text,
+      span:not(.icon) {
+        display: none;
+      }
+    }
+  }
+}
+
+// 移动端抽屉（全屏覆盖）
+.app-drawer--mobile {
+  // 添加阴影
+  box-shadow: 2px 0 8px rgba(0, 0, 0, 0.1);
+
+  &.visible {
+    box-shadow: 2px 0 16px rgba(0, 0, 0, 0.15);
+  }
+}
+
+// 抽屉内的滚动条样式
+.app-drawer {
+  &::-webkit-scrollbar {
+    width: 6px;
+    height: 6px;
+  }
+
+  &::-webkit-scrollbar-thumb {
+    background-color: rgba(0, 0, 0, 0.2);
+    border-radius: 3px;
+
+    &:hover {
+      background-color: rgba(0, 0, 0, 0.3);
+    }
+  }
+
+  &::-webkit-scrollbar-track {
+    background-color: transparent;
+  }
+}
+
+// 暗色主题下的滚动条
+html.dark {
+  .app-drawer {
+    &::-webkit-scrollbar-thumb {
+      background-color: rgba(255, 255, 255, 0.2);
+
+      &:hover {
+        background-color: rgba(255, 255, 255, 0.3);
+      }
+    }
+  }
+}

package/styles/index.scss

@@ -0,0 +1,5 @@
+// App Shell 样式入口
+@import './variables.scss';
+@import './responsive.scss';
+@import './drawer.scss';
+@import './mobile.scss';

package/styles/mobile.scss

@@ -0,0 +1,58 @@
+// 移动端样式
+@import './variables.scss';
+
+// 移动端优化
+@media (max-width: #{($breakpoint-small - 1px)}) {
+  // 触摸优化
+  * {
+    // 增大触摸目标
+    -webkit-tap-highlight-color: transparent;
+  }
+
+  // 按钮、链接等触摸元素的最小尺寸
+  button,
+  a,
+  [role="button"] {
+    min-height: 44px;
+    min-width: 44px;
+  }
+
+  // 优化文本选择
+  .app-main__content {
+    -webkit-user-select: text;
+    user-select: text;
+  }
+
+  // 移动端抽屉全屏
+  .app-drawer--mobile {
+    // 确保全屏显示
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+
+    // 添加状态栏安全区域
+    padding-top: env(safe-area-inset-top);
+    padding-left: env(safe-area-inset-left);
+    padding-right: env(safe-area-inset-right);
+  }
+
+  // 移动端顶栏添加安全区域
+  .app-header {
+    padding-top: calc(env(safe-area-inset-top) + 16px);
+    height: calc(var(--mb-app-shell-header-height, 60px) + env(safe-area-inset-top));
+  }
+
+  // 移动端主内容区添加安全区域
+  .app-main__content {
+    padding-bottom: calc(var(--mb-app-shell-main-padding, 16px) + env(safe-area-inset-bottom));
+  }
+}
+
+// 横屏模式优化
+@media (max-width: #{($breakpoint-small - 1px)}) and (orientation: landscape) {
+  .app-drawer--mobile {
+    // 横屏时抽屉高度减小
+    height: 100vh;
+  }
+}

package/styles/responsive.scss

@@ -0,0 +1,33 @@
+// 响应式样式
+@import './variables.scss';
+
+// 小屏（< 768px）
+@media (max-width: #{($breakpoint-small - 1px)}) {
+  :root {
+    --mb-app-shell-drawer-width: 100%;
+  }
+
+  .app-header {
+    padding: 0 12px;
+  }
+
+  .app-main__content {
+    padding: 12px;
+  }
+}
+
+// 中屏（768px - 1199px）
+@media (min-width: $breakpoint-small) and (max-width: #{($breakpoint-medium - 1px)}) {
+  .app-drawer--pc {
+    width: 200px;
+
+    &.is-collapsed {
+      width: var(--mb-app-shell-drawer-collapsed-width);
+    }
+  }
+}
+
+// 大屏（≥ 1200px）
+@media (min-width: $breakpoint-medium) {
+  // 大屏可以添加额外的样式
+}

package/styles/variables.scss

@@ -0,0 +1,44 @@
+// App Shell CSS 变量
+
+// 断点
+$breakpoint-small: 768px;
+$breakpoint-medium: 1200px;
+
+// 尺寸
+$drawer-width: 240px;
+$drawer-collapsed-width: 64px;
+$header-height: 60px;
+
+// 过渡
+$transition-duration: 0.3s;
+$transition-function: ease;
+
+// CSS 变量定义
+:root {
+  // 布局尺寸
+  --mb-app-shell-drawer-width: #{$drawer-width};
+  --mb-app-shell-drawer-collapsed-width: #{$drawer-collapsed-width};
+  --mb-app-shell-header-height: #{$header-height};
+
+  // 颜色
+  --mb-app-shell-header-bg: #ffffff;
+  --mb-app-shell-header-text-color: #606266;
+  --mb-app-shell-header-border-bottom: 1px solid #e4e7ed;
+  --mb-app-shell-drawer-bg: #ffffff;
+  --mb-app-shell-drawer-border-right: 1px solid #e4e7ed;
+  --mb-app-shell-main-bg: #f5f5f5;
+
+  // 间距
+  --mb-app-shell-main-padding: 16px;
+  --mb-app-shell-header-gap: 12px;
+}
+
+// 暗色主题
+html.dark {
+  --mb-app-shell-header-bg: #1f1f1f;
+  --mb-app-shell-header-text-color: #e5e5e5;
+  --mb-app-shell-header-border-bottom: 1px solid #333333;
+  --mb-app-shell-drawer-bg: #1f1f1f;
+  --mb-app-shell-drawer-border-right: 1px solid #333333;
+  --mb-app-shell-main-bg: #141414;
+}

package/types/app.ts

@@ -0,0 +1,41 @@
+import type { Router } from 'vue-router'
+import type { App } from 'vue'
+import type { PWAConfig } from './pwa'
+import type { LayoutConfig } from './layout'
+
+/**
+ * 应用创建选项
+ */
+export interface AppShellOptions {
+  /** 挂载元素选择器 */
+  el?: string
+  /** 路由配置 */
+  router?: {
+    /** 基础路由 */
+    baseRoutes?: any[]
+    /** 路由模式 */
+    historyMode?: 'hash' | 'html'
+    /** 基础路径 */
+    base?: string
+  }
+  /** PWA 配置 */
+  pwa?: PWAConfig
+  /** 布局配置 */
+  layout?: LayoutConfig
+  /** 是否设置 Pinia */
+  setupPinia?: boolean
+  /** 是否设置 Router */
+  setupRouter?: boolean
+}
+
+/**
+ * 应用创建结果
+ */
+export interface AppShellResult {
+  /** Vue 应用实例 */
+  app: App
+  /** 路由实例 */
+  router?: Router
+  /** Pinia 实例 */
+  pinia?: any
+}

package/types/index.ts

@@ -0,0 +1,4 @@
+export * from './slots'
+export * from './layout'
+export * from './pwa'
+export * from './app'

package/types/layout.ts

@@ -0,0 +1,28 @@
+/**
+ * 断点类型
+ */
+export type Breakpoint = 'small' | 'medium' | 'large'
+
+/**
+ * 布局配置
+ */
+export interface LayoutConfig {
+  /** 侧边栏宽度（PC端） */
+  siderWidth?: string
+  /** 侧边栏折叠宽度 */
+  siderCollapsedWidth?: string
+  /** 顶栏高度 */
+  headerHeight?: string
+  /** 是否默认折叠 */
+  defaultCollapsed?: boolean
+}
+
+/**
+ * 抽屉状态
+ */
+export interface DrawerState {
+  /** 是否可见（移动端） */
+  visible: boolean
+  /** 是否折叠（PC端） */
+  collapsed: boolean
+}

package/types/pwa.ts

@@ -0,0 +1,53 @@
+/**
+ * PWA 安装引导配置
+ */
+export interface PWAInstallConfig {
+  /** 安装提示标题 */
+  title?: string
+  /** 安装提示描述 */
+  description?: string
+  /** 安装按钮文案 */
+  installButtonText?: string
+  /** 取消按钮文案 */
+  cancelButtonText?: string
+  /** "不再提示"选项文案 */
+  dontShowAgainText?: string
+  /** 是否自动显示（默认 true） */
+  autoShow?: boolean
+}
+
+/**
+ * PWA 配置
+ */
+export interface PWAConfig {
+  /** 应用名称 */
+  name?: string
+  /** 应用简称 */
+  shortName?: string
+  /** 应用描述 */
+  description?: string
+  /** 主题色 */
+  themeColor?: string
+  /** 背景色 */
+  backgroundColor?: string
+  /** 应用图标（路径或对象） */
+  icon?: string | Record<string, string>
+  /** 安装引导配置 */
+  installPrompt?: PWAInstallConfig
+}
+
+/**
+ * PWA 安装事件状态
+ */
+export interface PWAInstallState {
+  /** 是否可安装 */
+  canInstall: boolean
+  /** 是否已安装 */
+  isInstalled: boolean
+  /** 是否不再提示 */
+  dontShowAgain: boolean
+  /** 安装提示是否可见 */
+  promptVisible: boolean
+  /** 延迟安装的安装事件 */
+  deferredPrompt: Event | null
+}

package/types/slots.ts

@@ -0,0 +1,31 @@
+import type { Component } from 'vue'
+
+/**
+ * App Shell 插槽位置
+ */
+export enum AppShellSlotLocation {
+  /** 顶栏左侧 */
+  HEADER_LEFT = 'HEADER_LEFT',
+  /** 顶栏中间 */
+  HEADER_CENTER = 'HEADER_CENTER',
+  /** 顶栏右侧 */
+  HEADER_RIGHT = 'HEADER_RIGHT',
+  /** 侧边栏（抽屉式） */
+  SIDEBAR = 'SIDEBAR',
+  /** 内容区域顶部 */
+  CONTENT_TOP = 'CONTENT_TOP',
+  /** 内容区域底部 */
+  CONTENT_BOTTOM = 'CONTENT_BOTTOM'
+}
+
+/**
+ * 插槽注册信息
+ */
+export interface AppShellSlotRegistration {
+  /** 插槽位置 */
+  location: AppShellSlotLocation
+  /** 组件 */
+  component: Component
+  /** 组件属性 */
+  props?: Record<string, any>
+}