通用方法

浏览器本地存储（缓存）

配置

web-storage-cache 是一个轻量级的 JavaScript 库，对浏览器原生 localStorage 和 sessionStorage 的扩展，提供了更强大的功能，如自动缓存、版本控制、生命周期管理等，从而提升应用性能和用户体验

• 代码：src\hooks\web\useCache.ts
• 默认为 localStorage，可以通过 type 参数进行切换。更改完默认存储方式后，需要清除浏览器缓存并重新登录，以免造成不可描述的问题。

/**
 * 配置浏览器本地存储的方式，可直接存储对象数组。
 */

import WebStorageCache from 'web-storage-cache'

type CacheType = 'localStorage' | 'sessionStorage'

// 缓存键
export const CACHE_KEY = {
  // 用户相关
  ROLE_ROUTERS: 'roleRouters',
  USER: 'user',
  // 系统设置
  IS_DARK: 'isDark',
  LANG: 'lang',
  THEME: 'theme',
  LAYOUT: 'layout',
  DICT_CACHE: 'dictCache',
  // 登录表单
  LoginForm: 'loginForm',
  TenantId: 'tenantId'
}

// 默认为 localStorage，可以通过 type 参数进行切换
export const useCache = (type: CacheType = 'localStorage') => {
  const wsCache: WebStorageCache = new WebStorageCache({
    storage: type
  })

  return {
    wsCache
  }
}

export const deleteUserCache = () => {
  const { wsCache } = useCache()
  wsCache.delete(CACHE_KEY.USER)
  wsCache.delete(CACHE_KEY.ROLE_ROUTERS)
  // 注意，不要清理 LoginForm 登录表单
}

使用示例

实现多语言状态管理

• 代码：src\store\modules\locale.ts
  • wsCache.set：设置
  • wsCache.get：获取

消息提示

配置

message 对象，由 实现，基于 ElMessage、ElMessageBox、ElNotification 封装，用于做消息提示、通知提示、对话框提醒、二次确认等。

• 代码：src/hooks/web/useMessage.ts
  • 消息提示：包含 info、error、success、warning 四种类型。
  • 弹出框提示：alert 及其不同类型的变体（如 alertError、alertSuccess 等）。
  • 通知提醒：notify 及其不同类型的通知（如 notifyError、notifySuccess 等）。
  • 确认对话框：confirm、delConfirm、exportConfirm 和 prompt 方法用于弹出确认或输入框。

使用示例

实现删除时，弹窗二次确认。示例：src\views\system\post\index.vue

<script lang="ts" setup>
const message = useMessage() // 消息弹窗

/** 删除按钮操作 */
const handleDelete = async (id: number) => {
  try {
    // 删除的二次确认
    await message.delConfirm()
    // 发起删除
    await PostApi.deletePost(id)
    message.success(t('common.delSuccess'))
    // 刷新列表
    await getList()
  } catch {}
}
</script>

文件下载

配置

download 对象，提供多种文件下载方法，包括 Excel、Word、Zip、HTML、Markdown、JSON 文件的 Blob 下载，以及图片跨域下载和 Base64 转文件功能。

• 代码：src\utils\download.ts
  • download0：通用下载函数，创建 Blob 和临时链接并触发下载。
  • excel/word/zip/html/markdown/json：指定 MIME 类型调用 download0。
  • image：通过 Canvas 下载图片，支持跨域和尺寸调整。
  • base64ToFile：将 Base64 数据转为 File 对象，用于文件下载或上传。

使用示例

实现导出Excel数据。示例：src\views\system\post\index.vue

<script lang="ts" setup>
import download from '@/utils/download'
    
/** 导出按钮操作 */
const handleExport = async () => {
  try {
    // 导出的二次确认
    await message.exportConfirm()
    // 发起导出
    exportLoading.value = true
    const data = await PostApi.exportPost(queryParams)
    download.excel(data, '岗位列表.xlsx')
  } catch {
  } finally {
    exportLoading.value = false
  }
}

</script>

配置读取

读取配置

配合《后端手册——配置管理》使用。使用场景：前端读取配置信息，执行特定操作。

前端调用 src\api\infra\config\index.ts 的 getConfigKey(configKey) 方法，获取指定 key 对应的配置的值。

// 根据参数键名查询参数值
export const getConfigKey = (configKey: string) => {
  return request.get({ url: '/infra/config/get-value-by-key?key=' + configKey })
}

使用示例

文件：src\views\infra\server\index.vue。该 Vue 组件用于展示一个后台管理系统的内嵌页面（iframe）：

• 使用 IFrame 加载后台地址，地址由接口动态获取；
• 页面加载时通过 ConfigApi.getConfigKey 获取配置的 URL；
• 在加载过程中显示 loading 效果，请求完成后隐藏；
• 使用 ContentWrap 包裹内容并设置样式。

<template>
  <ContentWrap :bodyStyle="{ padding: '0px' }" class="!mb-0">
    <IFrame v-if="!loading" v-loading="loading" :src="src" />
  </ContentWrap>
</template>
<script lang="ts" setup>
import * as ConfigApi from '@/api/infra/config'

defineOptions({ name: 'InfraAdminServer' })

const loading = ref(true) // 是否加载中
const src = ref(import.meta.env.VITE_BASE_URL + '/admin/applications')

/** 初始化 */
onMounted(async () => {
  try {
    const data = await ConfigApi.getConfigKey('url.spring-boot-admin')
    if (data && data.length > 0) {
      src.value = data
    }
  } finally {
    loading.value = false
  }
})
</script>