V3 Admin Vite 内置组合式函数(Composables)完整使用指南

原创2026-10-14 11:25:471,720 阅读
文章标签:前端Vibe Coding

V3 Admin Vite 内置组合式函数(Composables)完整使用指南

V3 Admin Vite 项目在 src/common/composables 目录下内置了一组开箱即用的通用组合式函数(Composables),涵盖设备检测、异步下拉、全屏加载、分页、路由监听、主题切换、动态标题、水印、无障碍模式与布局模式等高频后台场景。本文以这组函数的官方使用教程为核心,结合仓库源码逐一定位实现原理,帮助你彻底掌握它们的调用方式、参数约定与内部机制,从而在业务页面中直接复用、不再重复造轮子。

准备工作:路径别名与目录约定

所有内置组合式函数都集中在 src/common/composables 目录下,通过路径别名 @@/composables/ 导入。该别名在 vite.config.ts 中定义:

resolve: {
  alias: {
    // @ 符号指向 src 目录
    "@": resolve(__dirname, "src"),
    // @@ 符号指向 src/common 通用目录
    "@@": resolve(__dirname, "src/common")
  }
}

因此 @@/composables/useDevice 实际解析为 src/common/composables/useDevice。这些函数统一以 use 开头命名,遵循 Vue 组合式函数(Composable)惯例。

设备检测 useDevice

基本用法

useDevice 用于判断当前设备类型(移动端 / 桌面端),返回两个响应式计算属性:

import { useDevice } from "@@/composables/useDevice"

const { isMobile, isDesktop } = useDevice()

// 在模板或逻辑中使用
if (isMobile.value) {
  // 移动端逻辑
}

实现原理

查看 useDevice.ts 源码,核心逻辑非常简洁——基于 appStore.device 的两个 computed:

import { DeviceEnum } from "@@/constants/app-key"
import { useAppStore } from "@/pinia/stores/app"

const appStore = useAppStore()

const isMobile = computed(() => appStore.device === DeviceEnum.Mobile)
const isDesktop = computed(() => appStore.device === DeviceEnum.Desktop)

/** 设备类型 Composable */
export function useDevice() {
  return { isMobile, isDesktop }
}

其中 DeviceEnum 定义在 app-key.ts,appStore.device 的初始值为 DeviceEnum.Desktop。项目通过 useResize.ts 监听窗口 resize 事件(参考 Bootstrap 响应式设计,将最大移动端宽度设为 992px),当 document.body.getBoundingClientRect().width - 1 < 992 时调用 appStore.toggleDevice(DeviceEnum.Mobile),否则切换为桌面端。也就是说,useDevice 的返回值会随浏览器窗口变化自动更新,可用于响应式布局、菜单折叠、页面适配等场景。

异步下拉选择器 useFetchSelect

基本用法

useFetchSelect 封装了下拉选择器的异步数据加载逻辑,组件挂载时自动调用接口获取选项,返回 loading(加载状态)、options(选项数据)和 value(当前选中值):

import { useFetchSelect } from "@@/composables/useFetchSelect"
import { getSelectDataApi } from "./apis/xxx"

const { loading, options, value } = useFetchSelect({
  api: getSelectDataApi // 直接传函数引用,返回 ApiResponseData<SelectOption[]>
})

在模板中配合 Element Plus 使用:

<el-card v-loading="loading">
  <el-select v-model="value" filterable>
    <el-option v-for="item in options" v-bind="item" :key="item.value" placeholder="请选择" />
  </el-select>
</el-card>

数据格式约定

接口返回的数据格式必须符合以下 SelectOption 结构:

interface SelectOption {
  value: string | number
  label: string
  disabled?: boolean
}

源码中实际类型定义(useFetchSelect.ts):

type OptionValue = string | number

/** Select 需要的数据格式 */
interface SelectOption {
  value: OptionValue
  label: string
  disabled?: boolean
}

/** 接口响应格式 */
type ApiData = ApiResponseData<SelectOption[]>

/** 入参格式,暂时只需要传递 api 函数即可 */
interface FetchSelectProps {
  api: () => Promise<ApiData>
}

注意:传入的必须是函数引用(如 api: getSelectDataApi),而非函数调用结果,这一点与 useFullscreenLoading 的传参方式一致。

源码机制与实战示例

从源码看,useFetchSelect 在 onMounted 钩子中自动执行 loadData:先将 loading 置为 true、清空 options,再调用 api(),成功后将 res.data 写入 options,finally 中关闭加载状态:

onMounted(() => {
  loadData()
})

仓库在 use-fetch-select.vue 提供了完整示例页面,其中演示了两个用法:普通的 el-select 以及数据量较大时可选的 el-select-v2(el-select-v2 直接以 :options="options" 传入即可)。对应模拟接口见 apis/use-fetch-select.ts,它返回的 SELECT_RESPONSE_DATA.data 数组中包含了 label、value 以及 disabled: true 的禁用选项,恰好覆盖了 SelectOption 的全部字段。

全屏加载 useFullscreenLoading

三种调用方式

useFullscreenLoading 包装一个函数,在其执行期间自动显示全屏 Loading,函数执行完毕后自动关闭:

import { useFullscreenLoading } from "@@/composables/useFullscreenLoading"

// 方式一:行内调用(推荐简单场景)
const res = await useFullscreenLoading(getSuccessApi)([1, 2, 3])

// 方式二:自定义 Loading 配置
try {
  await useFullscreenLoading(getErrorApi, { text: "删除中...", background: "#F56C6C20" })()
} catch (error) {
  ElMessage.error((error as Error).message)
}

// 方式三:先赋值再调用(适合多次复用)
const submitWithLoading = useFullscreenLoading(submitApi)
await submitWithLoading(formData)

方式三是"柯里化"式的复用技巧:useFullscreenLoading(submitApi) 返回一个新的函数,可以绑定到按钮事件或多次调用,每次调用都会自动开启全屏 Loading,无需重复传入函数。

实现原理

源码(useFullscreenLoading.ts)基于 Element Plus 的 ElLoading.service 实现,采用 try/finally 确保 Loading 必然关闭:

const DEFAULT_OPTIONS = {
  lock: true,
  text: "加载中..."
}

export const useFullscreenLoading: UseFullscreenLoading = (fn, options = {}) => {
  let loadingInstance: LoadingInstance
  return async (...args) => {
    try {
      loadingInstance = ElLoading.service({ ...DEFAULT_OPTIONS, ...options })
      return await fn(...args)
    } finally {
      loadingInstance.close()
    }
  }
}

关键点:

  • 默认配置为 lock: true(锁定屏幕滚动)和 text: "加载中...",传入的 options 会与默认值合并(浅合并),因此自定义配置只需覆盖需要改动的字段即可;
  • 第二个参数类型为 Element Plus 的 LoadingOptions,除了 text、background,还支持 svg、svgViewBox 等高级配置。演示页 use-fullscreen-loading.vue 中即传入了一段自定义 SVG 加载动画:
    const options = {
      text: "即将发生错误...",
      background: "#F56C6C20",
      svg,
      svgViewBox: "-10, -10, 50, 50"
    }
    
  • 使用 finally 而非 catch,意味着函数内部的错误不会被吞掉,会照常向上抛出,因此调用方可以放心使用 try/catch 捕获并提示错误,如演示页中的 queryError 所示。

分页 usePagination

基本用法

usePagination 封装分页状态与操作,直接适配 Element Plus 的 el-pagination 组件:

import { usePagination } from "@@/composables/usePagination"

function getTableData() {
  // 请求表格数据,并更新 paginationData.total
}

const { paginationData, resetCurrentPage, watchPagination } = usePagination({
  callback: getTableData,
  pageSize: 20,
  pageSizes: [10, 20, 50, 100]
})

// 初始化加载,并在 currentPage / pageSize 变化时重新请求
watchPagination()

function handleSearch() {
  resetCurrentPage()
}

模板中的 el-pagination 绑定:

<el-pagination
  v-model:current-page="paginationData.currentPage"
  v-model:page-size="paginationData.pageSize"
  :page-sizes="paginationData.pageSizes"
  :total="paginationData.total"
  :layout="paginationData.layout"
  background
/>

默认分页参数

参数 默认值
total 0
currentPage 1
pageSizes [10, 20, 50]
pageSize 10
layout "total, sizes, prev, pager, next, jumper"

以上默认值定义于源码 DEFAULT_PAGINATION_DATA(usePagination.ts),传入的选项会通过 reactive({ ...DEFAULT_PAGINATION_DATA, ...initPaginationData }) 与默认值浅合并,因此 pageSize 与 pageSizes 属于可选覆盖项。

机制解读

  • callback 会在 watchPagination 监听到页码或每页条数变化时执行;
  • watchPagination(options = { immediate: true }) 内部用 watch 同时监听 paginationData.currentPage 与 paginationData.pageSize,默认 immediate: true,即调用即触发一次首次加载(源码见 usePagination.ts);
  • resetCurrentPage 用于搜索场景:当前已在第 1 页时直接执行回调,否则重置到第 1 页并交由 watch 触发,避免重复请求(源码为 paginationData.currentPage === 1 ? callback?.() : (paginationData.currentPage = 1));
  • 同时返回的 handleCurrentChange 与 handleSizeChange 可以手动绑定到组件的 @current-change、@size-change 事件。

仓库在 element-plus/index.vue 中给出了完整的表格 + 分页实战:getTableData 请求时将 currentPage、pageSize 传给接口,成功后写入 paginationData.total 与表格数据;搜索按钮调用 handleSearch()(内部即 resetCurrentPage()),随后初始化调用 watchPagination() 完成首次加载。这是后台管理表格页最典型的组合姿势。

路由监听 useRouteListener

基本用法

useRouteListener 基于发布订阅模式监听路由变化,比直接用 watch 监听路由性能更好,组件卸载时自动移除监听:

import { useRouteListener } from "@@/composables/useRouteListener"

const { listenerRouteChange, removeRouteListener } = useRouteListener()

// 监听路由变化
listenerRouteChange((route) => {
  console.log("路由变化了:", route.path)
})

// 立即执行一次(获取当前路由信息)
listenerRouteChange((route) => {
  activeMenu.value = route.path
}, true) // 第二个参数 immediate = true

发布订阅实现

源码(useRouteListener.ts)基于 mitt 实现事件总线:

  • 模块内创建了单例 emitter = mitt() 与事件 key(Symbol("ROUTE_CHANGE"));
  • 外部通过导出的 setRouteChange(to) 发布路由变化事件,同时缓存 latestRoute:
    export function setRouteChange(to: RouteLocationNormalizedGeneric) {
      emitter.emit(key, to)   // 触发事件
      latestRoute = to        // 缓存最新的路由信息
    }
    
  • listenerRouteChange(callback, immediate = false) 订阅事件;当 immediate 为 true 且 latestRoute 已存在时,会立即用最新路由执行一次回调(用于组件初始化时同步当前路由状态);
  • onBeforeUnmount 中会自动遍历 callbackList 调用 removeRouteListener,因此组件卸载时监听会被自动清理,无需手动管理。

调用链佐证

路由守卫 guard.ts 在全局后置钩子中发布路由变化事件,并同步更新页面标题:

router.afterEach((to) => {
  setRouteChange(to)
  setTitle(to.meta.title)
  NProgress.done()
})

项目中多个布局组件都订阅了该事件,例如 TagsView/index.vue 通过 listenerRouteChange((route) => { addTags(route) }, true) 在初始化时立即渲染当前标签页,Breadcrumb/index.vue 也以同样方式同步面包屑。对比"每个组件各自 watch(route)"的方案,发布订阅让路由变化只派发一次、按需分发,避免了重复渲染开销。

主题切换 useTheme

基本用法

useTheme 管理主题切换,并支持 View Transition 动画效果:

import { useTheme } from "@@/composables/useTheme"

const { themeList, activeThemeName, initTheme, setTheme } = useTheme()

// 初始化主题(应用启动时调用一次)
initTheme()

// 切换主题(需要传入鼠标事件以实现过渡动画)
function handleThemeChange(event: MouseEvent, themeName: ThemeName) {
  setTheme(event, themeName)
}

可用主题

name title
"normal" 默认
"dark" 黑暗
"dark-blue" 深蓝

主题列表 themeList 定义于 useTheme.ts,ThemeName 类型为 DefaultThemeName | "dark" | "dark-blue"(DefaultThemeName 即 "normal",是必填的)。

实现原理

源码的关键机制:

  1. 持久化与初始化:activeThemeName 初始值读取自 localStorage(getActiveThemeName(),见 local-storage.ts),无缓存时回退到默认主题;initTheme() 用 watchEffect 收集副作用——主题名变化时在 <html> 根元素上移除其他主题 class、添加当前主题 class,并写入 localStorage,实现刷新后主题记忆。

  2. View Transition 动画:setTheme(event, value) 需要传入鼠标事件。源码先根据点击位置计算圆形展开的半径 maxRadius(取点击点到四个边角距离的最大值,Math.hypot 计算),然后通过 setCssVar(css.ts)把 --v3-theme-x、--v3-theme-y、--v3-theme-r 三个 CSS 变量写入根元素,最后:

    document.startViewTransition ? document.startViewTransition(handler) : handler()
    

    即支持 View Transition API 的浏览器(如 Chrome 111+)走动画过渡,不支持的浏览器直接切换主题。动画样式定义在 view-transition.scss,是一个从 0 半径到最大半径的 clip-path: circle() 圆形扩散动画。

  3. 主题样式注册:多主题的 SCSS 通过 register.scss 注册(@import "./dark/index.scss" 与 "./dark-blue/index.scss"),每个主题的 index.scss 引入自己的 variables.scss(如 dark 主题 $theme-name: "dark"、$theme-bg-color: #141414,dark-blue 主题为 #001b44),再由 core/index.scss 用 .#{$theme-name} { ... } 包裹所有覆盖样式,实现按主题名作用域隔离。

界面上的主题切换入口是 ThemeSwitch/index.vue,通过 el-dropdown 渲染 themeList,点击项回调 (e: MouseEvent) => setTheme(e, theme.name),正是 setTheme 需要鼠标事件的典型使用场景。

动态标题 useTitle

基本用法

useTitle 动态设置浏览器标签页标题,格式为 项目名 | 页面名:

import { useTitle } from "@@/composables/useTitle"

const { setTitle } = useTitle()

// 设置标题为 "V3 Admin Vite | 用户管理"
setTitle("用户管理")

// 重置为项目默认标题
setTitle()

实现细节

源码(useTitle.ts):

/** 项目标题 */
const VITE_APP_TITLE = import.meta.env.VITE_APP_TITLE ?? "V3 Admin Vite"

const dynamicTitle = ref<string>("")

function setTitle(title?: string) {
  dynamicTitle.value = title ? `${VITE_APP_TITLE} | ${title}` : VITE_APP_TITLE
}

watch(dynamicTitle, (value, oldValue) => {
  if (document && value !== oldValue) {
    document.title = value
  }
})

要点:

  • 项目名读取自 import.meta.env.VITE_APP_TITLE(定义于根目录 .env 文件,值为 V3 Admin Vite),未配置时回退为 "V3 Admin Vite";
  • 标题变化通过 watch 统一写入 document.title,避免在业务代码中直接操作 DOM;
  • 在路由守卫 guard.ts 的 afterEach 中,已经调用了 setTitle(to.meta.title)——即每个页面的标题会自动跟随路由 meta 配置更新,业务页面通常无需手动调用;setTitle() 无参调用则用于重置回项目默认标题。

水印 useWatermark

基本用法

useWatermark 为页面或指定容器添加水印,支持防御(防止用户通过控制台删除或隐藏水印),组件卸载时自动清除:

import { useWatermark } from "@@/composables/useWatermark"

// 默认挂载到 body
const { setWatermark, clearWatermark } = useWatermark()

// 设置水印
setWatermark("机密文件")

// 自定义配置
setWatermark("内部使用", {
  defense: true,    // 开启防御(默认 true)
  color: "#c0c4cc", // 文本颜色
  opacity: 0.5,     // 透明度
  size: 16,         // 字体大小
  angle: -20,       // 倾斜角度
  width: 300,       // 单个水印宽度(越大密度越低)
  height: 200       // 单个水印高度(越大密度越低)
})

// 清除水印
clearWatermark()

默认配置表

源码 useWatermark.ts 中的 DEFAULT_CONFIG:

配置项 默认值 说明
defense true 防御模式,能防御水印被删除或隐藏(可能有性能损耗)
color "#c0c4cc" 文本颜色
opacity 0.5 文本透明度
size 16 文本字体大小
family "serif" 文本字体
angle -20 文本倾斜角度
width 300 一处水印所占宽度(数值越大水印密度越低)
height 200 一处水印所占高度(数值越大水印密度越低)

挂载到指定容器

不传参数时默认挂载到 body(全局水印)。若需要局部水印,可传入容器的模板引用:

<script setup lang="ts">
import { useWatermark } from "@@/composables/useWatermark"

const localRef = useTemplateRef("localRef")
const { setWatermark, clearWatermark } = useWatermark(localRef)

onMounted(() => {
  setWatermark("仅限内部")
})
</script>

<template>
  <div ref="localRef">
    <!-- 内容 -->
  </div>
</template>

注意源码中的一处约束(useWatermark.ts):若传入的容器尚未挂载(parentEl.value 为空),setWatermark 会 console.warn("请在 DOM 挂载完成后再调用 setWatermark 方法设置水印"),因此局部水印应在 onMounted 之后再设置。

实现原理:Canvas + MutationObserver + ResizeObserver

从源码可以梳理出水印的完整工作链路:

  1. 绘制:使用 Canvas 2D 按配置(颜色、透明度、字体、倾斜角)将文本绘制到 width × height 的画布上,toDataURL() 生成 base64 图片,作为水印层 background: url(...) left top repeat 平铺。水印元素 pointerEvents: none 且 z-index: 99999,不影响页面交互;
  2. 定位:挂载到 body 时水印为 position: fixed,挂载到普通容器时水印为 absolute 且容器被设置为 relative,水印尺寸跟随容器尺寸;
  3. 防御机制:开启 defense 后,通过 MutationObserver 同时监听水印元素(属性变化,如被 CSS 隐藏)与容器元素(子节点移除),一旦发现水印被删除(removedNodes 命中水印元素)就重新 appendChild 回去,发现属性被篡改就触发 updateWatermark() 刷新;updateWatermark 内部通过 debounce(100ms)防抖,避免频繁重建;
  4. 自适应:通过 ResizeObserver 监听容器尺寸变化(500ms 防抖),容器缩放时自动更新水印层的宽高;
  5. 自动清理:onBeforeUnmount 中调用 clearWatermark() 移除水印并断开所有观察器。

演示页面 use-watermark.vue 同时演示了全局水印与局部水印、有防御与无防御(defense: false)的切换,以及不同颜色的自定义水印,是验证该函数行为的最佳入口。

灰色模式与色弱模式 useGreyAndColorWeakness

基本用法

useGreyAndColorWeakness 初始化灰色模式和色弱模式,基于 settingsStore 的配置自动切换 HTML 根元素的 CSS 类名:

import { useGreyAndColorWeakness } from "@@/composables/useGreyAndColorWeakness"

const { initGreyAndColorWeakness } = useGreyAndColorWeakness()

// 应用启动时调用一次即可,后续会自动响应 Store 变化
initGreyAndColorWeakness()

实现原理

源码(useGreyAndColorWeakness.ts)定义了两个 CSS 类名 grey-mode 与 color-weakness,并用 watchEffect 让 settingsStore.showGreyMode 与 settingsStore.showColorWeakness 的变化自动反映到根元素的 classList 上:

function initGreyAndColorWeakness() {
  const settingsStore = useSettingsStore()
  watchEffect(() => {
    classList.toggle(GREY_MODE, settingsStore.showGreyMode)
    classList.toggle(COLOR_WEAKNESS, settingsStore.showColorWeakness)
  })
}

showGreyMode / showColorWeakness 是 layouts/config.ts 中 LayoutsConfig 的配置项(默认均为 false),该配置通过 settings.ts 这个 Pinia store 响应式暴露,并在变化时自动写入 localStorage 持久化。因此 initGreyAndColorWeakness 只需在应用启动时调用一次(见 App.vue),后续用户在任何地方修改 Store 中的开关,根元素类名都会自动增减,对应的灰阶 / 色弱 CSS 滤镜即生效。

布局模式 useLayoutMode

基本用法

useLayoutMode 管理系统布局模式(左侧菜单 / 顶部菜单 / 左侧 + 顶部混合菜单):

import { useLayoutMode } from "@@/composables/useLayoutMode"
import { LayoutModeEnum } from "@@/constants/app-key"

const { isLeft, isTop, isLeftTop, setLayoutMode } = useLayoutMode()

// 判断当前布局
if (isLeft.value) {
  // 左侧菜单布局
}

// 切换布局
setLayoutMode(LayoutModeEnum.Top)

实现原理

LayoutModeEnum 定义于 app-key.ts:

export enum LayoutModeEnum {
  Left = "left",
  Top = "top",
  LeftTop = "left-top"
}

源码(useLayoutMode.ts)基于 settingsStore.layoutMode(同样来源于 LayoutsConfig,默认值为 LayoutModeEnum.Left)生成三个 computed 判断标志,setLayoutMode(mode) 则直接改写 store 值:

const isLeft = computed(() => settingsStore.layoutMode === LayoutModeEnum.Left)
const isTop = computed(() => settingsStore.layoutMode === LayoutModeEnum.Top)
const isLeftTop = computed(() => settingsStore.layoutMode === LayoutModeEnum.LeftTop)

function setLayoutMode(mode: LayoutModeEnum) {
  settingsStore.layoutMode = mode
}

由于 settingsStore 会随配置变化持久化到 localStorage,布局模式同样具备刷新记忆能力。仓库中 SelectLayoutMode.vue 正是用 isLeft / isTop / isLeftTop 给三个布局选项做高亮,并用 @click="setLayoutMode(LayoutModeEnum.Left)" 等方式切换;布局模式的渲染由 layouts/modes 下的 LeftMode.vue、TopMode.vue、LeftTopMode.vue 三种布局组件承载,与 LayoutModeEnum 一一对应。

使用原则与最佳实践

仓库在文档末尾明确了四条使用原则,这也是在日常开发中应该遵守的约定:

  1. 优先使用内置组合式函数,不要重复造轮子——上述 10 个函数已经覆盖了后台管理系统的高频能力,遇到同类需求先到 src/common/composables 目录查找;
  2. 组合式函数内部已处理生命周期(如 onBeforeUnmount 自动清理监听、移除水印等),业务代码无需手动管理清理逻辑;
  3. 需要新增通用组合式函数时,在 src/common/composables 目录下创建,命名以 use 开头,并建议复用 @@/composables/ 路径别名导入;
  4. 页面私有的组合式函数应放在对应页面目录的 composables 子目录下,而非 src/common/composables——页面级函数与全局通用函数分层隔离,避免公共目录膨胀。

结语

这组内置组合式函数的设计思路非常清晰:设备、主题、布局、无障碍模式等全局能力由「Composable + Pinia Store + localStorage」三件套驱动,分页、异步下拉、全屏加载、水印等页面能力则封装为「声明即用」的独立函数,配合路由守卫、App.vue 启动初始化与 composable-demo 演示页面,构成了完整的可复用能力体系。在实际开发中,先评估这些函数能否覆盖需求,再决定是否手写——这既是效率提升,也是项目代码一致性的保障。

登录后查看全文
v3-admin-vite