bun + vite7 的结合，孕育的 Robot Admin 【靓仔出道】（十五）

Robot Admin 可用Hooks 完整指南

⏰ 阅读时间: 10 分钟
📊 等级: 进阶

Robot Admin 提供了一套全面的自定义 Vue Composition API 钩子，旨在简化应用程序中的常见任务。这些钩子封装了可重用的逻辑，使您的组件更加简洁和易于维护。

📋 钩子概览

Robot Admin 项目中提供了以下自定义钩子：

钩子名称	描述	关键特性
useCopy	将文本复制到剪贴板	支持多种数据格式，浏览器兼容性
useDownload	从 API 下载文件	支持多种文件类型，通知功能
useExcel	Excel 文件操作	导入/导出，模板，多工作表支持
useFormSubmit	表单提交处理	验证，API 集成，防抖
useImage	图像处理工具	优化，转换，预览
useJsZip	文件压缩与解压	ZIP 文件创建，解压，进度跟踪
useOnClickOutside	检测外部点击	元素引用，自定义处理程序
usePrintWatermark	向页面添加水印	文本/图像水印，可配置选项
useStorage	本地/会话存储封装	类型安全，过期，加密

---

🔧 详细钩子文档

📋 useCopy

useCopy 钩子提供了一种简单的方法来将文本复制到剪贴板，支持多种数据格式和浏览器兼容性。

基本用法

import { useCopy } from '@/hooks/useCopy'// 基本用法
const { copyText } = useCopy()
copyText('这段文本将被复制到剪贴板')// 高级用法，带选项
const { copy } = useCopy()
copy(dataObject, {dataType: 'json',formatData: true,successTip: 'JSON 数据已复制！',onSuccess: (text) => console.log('已复制：', text)
})

API 参考

const {// 核心方法copy,                // 带完整选项的复制copyText,            // 快速文本复制copyJSON,            // 格式化并复制 JSONcopyURL,             // 格式化并复制 URLcopyCode,            // 复制代码片段copyRichText,        // 复制带格式的 HTMLreadClipboard,       // 从剪贴板读取（需要权限）// 状态state,               // 当前状态（加载中，最后复制的文本等）canCopy,             // 是否支持复制recentlyCopied,      // 最近 2 秒内是否复制了内容// 工具clearHistory,        // 清除复制历史checkSupport,        // 检查浏览器支持详情formatters           // 访问数据格式化器
} = useCopy(defaultOptions?)

该钩子支持多种数据类型，包括文本、URL、电子邮件、JSON、HTML、Markdown 和 CSV，并为每种类型提供专门的格式化。

---

📥 useDownload

useDownload 钩子简化了从 API 端点下载文件的过程，处理浏览器兼容性并提供用户反馈。

基本用法

import { useDownload, FileType, useDownloadExcel } from '@/hooks/useDownload'// 基本用法
const downloadApi = (params) => fetch('/api/download').then(res => res.blob())// 通用下载
await useDownload(downloadApi, {fileName: '报告',fileType: FileType.PDF,params: { id: 123 }
})// 常见文件类型的专用下载
await useDownloadExcel(downloadApi, '月度报告', { month: '一月' })

API 参考

// 主下载函数
useDownload(api: (params?) => Promise<Blob>,config: {fileName: string,fileType: FileType,params?: Record<string, unknown>,showNotification?: boolean,notificationConfig?: {loading?: string,success?: string,error?: string}}
): Promise<void>// 专用下载助手
useDownloadExcel(api, fileName, params?): Promise<void>
useDownloadCSV(api, fileName, params?): Promise<void>
useDownloadPDF(api, fileName, params?): Promise<void>
useDownloadJSON(api, fileName, params?): Promise<void>// 获取支持的文件类型
getSupportedFileTypes(): Array<{ label: string, value: FileType }>

该钩子处理不同文件类型，使用适当的 MIME 类型，并提供浏览器特定的下载实现，以实现最大兼容性。

---

📊 useExcel

useExcel 钩子使用 xlsx 库提供全面的 Excel 文件操作，包括导入、导出和模板生成。

基本用法

import { useExcel } from '@/hooks/useExcel'const { readFile, exportToExcel, exportMultipleSheets,generateTemplate
} = useExcel()// 读取 Excel 文件
const fileInput = document.querySelector('input[type="file"]')
fileInput.addEventListener('change', async (e) => {const file = e.target.files[0]const data = await readFile(file)console.log('Excel 数据：', data)
})// 导出数据到 Excel
const data = [{ name: '张三', age: 30 }, { name: '李四', age: 25 }]
await exportToExcel(data, { fileName: '用户.xlsx', sheetName: '用户' })// 导出多个工作表
const sheetsData = {用户: [{ name: '张三', age: 30 }],订单: [{ id: 1, product: '笔记本电脑', price: 999 }]
}
await exportMultipleSheets(sheetsData, '公司数据.xlsx')

API 参考

const {// 状态loading,             // 加载状态error,               // 错误信息（如果有）// 数据workbook,            // 当前工作簿sheets,              // 可用工作表名称data,                // 从工作表中解析的数据// 基本方法readFile,            // 读取 Excel 文件exportToExcel,       // 导出数据到 ExcelexportMultipleSheets, // 导出多个工作表// 模板方法generateTemplate,    // 生成模板文件getPresetTemplates,  // 获取预定义模板// 工具clearData,           // 清除解析的数据clearError           // 清除错误状态
} = useExcel()

该钩子处理数据处理、列宽优化，并提供一个简单的 API 用于复杂的 Excel 操作。

---

📝 useFormSubmit

useFormSubmit 钩子简化了表单提交，内置验证、API 集成、错误处理和防抖保护。

基本用法

import { useFormSubmit } from '@/hooks/useFormSubmit'// 在您的组件设置中
const { loading, createSubmit } = useFormSubmit()// 创建一个带 API 集成的提交处理程序
const loginApi = (formData) => api.post('/login', formData)
const submitLogin = createSubmit(loginApi, {successMsg: '登录成功！',errorMsg: '登录失败，请检查您的凭据。',onSuccess: ({ token }) => {// 处理成功登录userStore.setToken(token)router.push('/dashboard')},debounce: 500 // 防止多次点击
})// 在模板中使用
// <n-button :loading="loading" @click="submitLogin(formRef)">登录</n-button>

API 参考

const { loading,          // 响应式加载状态createSubmit      // 创建提交处理程序的函数
} = useFormSubmit<T>()// 创建提交处理程序
const submitFn = createSubmit(apiFunction: (model: any) => Promise<ApiResponse>,options?: {successCode?: string,         // 成功响应代码（默认：'0'）successMsg?: string,          // 成功通知消息errorMsg?: string,            // 错误通知消息onSuccess?: (data) => void,   // 成功回调globalErrorHandler?: (error) => void, // 自定义错误处理程序debounce?: number | false     // 防抖时间（毫秒，默认：500）}
)

该钩子自动在提交前验证表单，显示适当的通知，并处理 API 响应。

---

🖱️ useOnClickOutside

useOnClickOutside 钩子检测指定元素外的点击，适用于在点击外部时关闭下拉菜单、模态框或其他交互组件。

基本用法

import { useOnClickOutside } from '@/hooks/useOnClickOutside'// 在您的组件设置中
const dropdownRef = ref(null)
const isOpen = ref(true)// 设置外部点击检测
useOnClickOutside(dropdownRef, () => {isOpen.value = false
})

---

🖼️ usePrintWatermark

usePrintWatermark 钩子向您的应用程序页面添加水印覆盖层，适用于标记机密信息或保护知识产权。

基本用法

import { usePrintWatermark } from '@/hooks/usePrintWatermark'// 基本用法，带文本
const { addWatermark, removeWatermark } = usePrintWatermark()addWatermark({content: '机密',fontSize: 16,opacity: 0.1,angle: -30
})// 后续，当不再需要水印时
removeWatermark()

---

💾 useStorage

useStorage 钩子提供增强的浏览器存储，具有类型安全、自动序列化/反序列化、可选过期和加密支持。

基本用法

import { useStorage } from '@/hooks/useStorage'// 带类型安全的本地存储
const userName = useStorage<string>('user.name', '访客')
const userSettings = useStorage<{ theme: string, fontSize: number }>('user setting', {theme: 'light',fontSize: 14
})// 更新存储的值
userName.value = '约翰·多伊' // 自动持久化// 带过期（24小时）
const authToken = useStorage('auth.token', '', {expires: 24 * 60 * 60 * 1000,session: false, // 使用 localStorage（默认）encrypt: true  // 加密敏感数据
})

---

💡 使用钩子的最佳实践

1. 按需导入

大多数钩子返回多个方法和属性，但您可以解构仅需要的部分，以保持代码简洁。

2. 组合钩子以实现复杂工作流

钩子设计为协同工作。例如，结合 useExcel 和 useDownload 以实现完整的 Excel 工作流。

3. 使用 TypeScript 类型

所有钩子都完全类型化，因此请利用 TypeScript 确保您正确使用它们。

4. 处理加载状态

大多数钩子提供响应式加载状态，您可以在 UI 中使用它们来显示加载指示器。

5. 错误处理

在使用返回 Promise 的钩子时，使用 try-catch 块以优雅地处理错误。

try {await copyJSON(complexData)
} catch (error) {console.error('复制 JSON 数据失败：', error)
}

---

🛠️ 创建自定义钩子

您可以按照内置钩子使用的相同模式创建自己的自定义钩子。推荐的结构如下：

• 为参数和返回值定义清晰的接口
• 使用 ref 或 reactive 使用响应式状态
• 通过方法和状态暴露一致的 API
• 处理边缘情况并提供有意义的错误消息
• 使用 JSDoc 注释文档化您的钩子

示例自定义钩子模板

// 示例自定义钩子模板
export function useCustomFeature(options = {}) {// 状态const load = ref(false)const err = ref(null)// 方法const doSomething = async () => {load.value = truetry {// 实现return result} catch (err) {err.value = errthrow err} finally {load.value = false}}return {load,err,doSomething}
}

---

🎯 总结

通过利用这些强大的钩子，您可以显著减少样板代码，并提高组件的可维护性。每个钩子都经过精心设计，遵循 Vue 3 Composition API 的最佳实践，为常见的开发任务提供了优雅的解决方案。

💡 提示: 开始时可以从最常用的钩子（如 useCopy、useFormSubmit）开始，然后逐步探索其他更专业的钩子功能。

   期待共建！

如果这套组件系统对你的开发工作有所启发或帮助，请不要吝啬你的 Star！每一个 ⭐ 都是对我最大的鼓励和支持。

👉 点击这里 Star 支持项目 （🧧行大运摸大票💰）

🔗 探索更多资源

📋 资源类型	🔗 链接	📝 说明
🎯 在线预览	robotadmin.cn	体验完整功能演示
📚 详细文档	tzagileteam.com	深入了解实现细节
💻 源码仓库	https:/github.com/ChenyCHENYU/Robot_Admin	获取完整源代码

非常期待听到你的想法！