topfans/frontend/utils/preloadApi/README.md

preloadApi — API 预加载模块

快速开始

1. 在页面中使用缓存数据

<script setup>
import { usePreload } from '@/composables/usePreload'

const { data, loading, error, refresh } = usePreload('asset.detail', { id: route.params.id })
</script>

<template>
  <view v-if="data">{{ data.name }}</view>
  <view v-else-if="loading">加载中...</view>
  <view v-else-if="error">加载失败: {{ error.message }}</view>
</template>

2. 手动失效缓存

import { getPreloadApi } from '@/utils/preloadApi/index'

const api = getPreloadApi()

// 失效单个 key
api.invalidate('ranking.hot')

// 失效某个前缀的所有 key
api.invalidatePrefix('asset.')

// 清空全部内存缓存
api.invalidateAll()

3. 添加新的预拉配置

在 frontend/config/preload.config.js 中：

pages: {
  '/pages/new-page/new-page': [
    { key: 'new.data', fetcher: (params) => getNewDataApi(params.id) }
  ]
}

4. 替换页面跳转

// 旧写法
uni.navigateTo({ url: '/pages/detail/detail?id=123' })

// 新写法（自动触发预拉）
import { getPreloadApi } from '@/utils/preloadApi/index'
const api = getPreloadApi()
api.navigateTo({ url: '/pages/detail/detail?id=123' })

API 速查

方法	说明
preloadApi.run(key, params?)	触发预拉（fire-and-forget），不返回数据
preloadApi.get(key, params?)	读缓存，未命中则拉取
preloadApi.invalidate(key, params?)	失效单个 key（内存）
preloadApi.invalidatePrefix(prefix)	失效前缀匹配的所有 key（内存）
preloadApi.invalidateAll()	清空全部内存缓存
preloadApi.clearUser(userId)	登出：清空内存 + 删文件缓存目录
preloadApi.navigateTo(opts)	替代 uni.navigateTo
preloadApi.switchTab(opts)	替代 uni.switchTab
preloadApi.reLaunch(opts)	替代 uni.reLaunch

配置字段

字段	类型	默认值	说明
key	string	(必填)	逻辑 key，业务引用缓存的唯一标识
fetcher	(params) => Promise	(必填)	请求函数
ttl	number	300000	缓存有效期 (ms)
persistence	'memory'|'file'	'memory'	缓存存储方式
timeout	number	10000	单接口超时 (ms)
silent	boolean	true	失败是否静默