V3 Admin Vite 内置组合式函数(Composables)完整使用指南
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",是必填的)。
实现原理
源码的关键机制:
-
持久化与初始化:
activeThemeName初始值读取自 localStorage(getActiveThemeName(),见 local-storage.ts),无缓存时回退到默认主题;initTheme()用watchEffect收集副作用——主题名变化时在<html>根元素上移除其他主题 class、添加当前主题 class,并写入 localStorage,实现刷新后主题记忆。 -
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()圆形扩散动画。 -
主题样式注册:多主题的 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
从源码可以梳理出水印的完整工作链路:
- 绘制:使用 Canvas 2D 按配置(颜色、透明度、字体、倾斜角)将文本绘制到
width × height的画布上,toDataURL()生成 base64 图片,作为水印层background: url(...) left top repeat平铺。水印元素pointerEvents: none且z-index: 99999,不影响页面交互; - 定位:挂载到
body时水印为position: fixed,挂载到普通容器时水印为absolute且容器被设置为relative,水印尺寸跟随容器尺寸; - 防御机制:开启
defense后,通过MutationObserver同时监听水印元素(属性变化,如被 CSS 隐藏)与容器元素(子节点移除),一旦发现水印被删除(removedNodes命中水印元素)就重新appendChild回去,发现属性被篡改就触发updateWatermark()刷新;updateWatermark内部通过debounce(100ms)防抖,避免频繁重建; - 自适应:通过
ResizeObserver监听容器尺寸变化(500ms 防抖),容器缩放时自动更新水印层的宽高; - 自动清理:
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 一一对应。
使用原则与最佳实践
仓库在文档末尾明确了四条使用原则,这也是在日常开发中应该遵守的约定:
- 优先使用内置组合式函数,不要重复造轮子——上述 10 个函数已经覆盖了后台管理系统的高频能力,遇到同类需求先到
src/common/composables目录查找; - 组合式函数内部已处理生命周期(如
onBeforeUnmount自动清理监听、移除水印等),业务代码无需手动管理清理逻辑; - 需要新增通用组合式函数时,在
src/common/composables目录下创建,命名以use开头,并建议复用@@/composables/路径别名导入; - 页面私有的组合式函数应放在对应页面目录的
composables子目录下,而非src/common/composables——页面级函数与全局通用函数分层隔离,避免公共目录膨胀。
结语
这组内置组合式函数的设计思路非常清晰:设备、主题、布局、无障碍模式等全局能力由「Composable + Pinia Store + localStorage」三件套驱动,分页、异步下拉、全屏加载、水印等页面能力则封装为「声明即用」的独立函数,配合路由守卫、App.vue 启动初始化与 composable-demo 演示页面,构成了完整的可复用能力体系。在实际开发中,先评估这些函数能否覆盖需求,再决定是否手写——这既是效率提升,也是项目代码一致性的保障。