246 lines
6.2 KiB
Markdown
246 lines
6.2 KiB
Markdown
# 应用版本更新使用示例
|
||
|
||
## 功能说明
|
||
|
||
`useAppUpdate` 提供了完整的应用版本检查和更新功能，支持：
|
||
|
||
- ✅ 自动获取当前应用版本（原生/Web）
|
||
- ✅ 从后端 API 检查最新版本
|
||
- ✅ 版本号比较（语义化版本）
|
||
- ✅ 强制更新和可选更新
|
||
- ✅ 打开应用商店更新页面
|
||
- ✅ 国际化支持（中英文）
|
||
- ✅ Service Worker 更新（PWA）
|
||
|
||
## 基础使用
|
||
|
||
### 1. 在应用启动时检查更新
|
||
|
||
在 `App.vue` 或主布局组件中：
|
||
|
||
```vue
|
||
<script setup lang="ts">
|
||
import { onMounted } from "vue";
|
||
|
||
const { checkAndPromptUpdate } = useAppUpdate();
|
||
|
||
onMounted(async () => {
|
||
// 应用启动 3 秒后检查更新
|
||
setTimeout(() => {
|
||
checkAndPromptUpdate();
|
||
}, 3000);
|
||
});
|
||
</script>
|
||
```
|
||
|
||
### 2. 手动触发检查更新
|
||
|
||
在设置页面添加"检查更新"按钮：
|
||
|
||
```vue
|
||
<script setup lang="ts">
|
||
const {
|
||
isChecking,
|
||
currentVersion,
|
||
checkAndPromptUpdate,
|
||
} = useAppUpdate();
|
||
|
||
async function handleCheckUpdate() {
|
||
await checkAndPromptUpdate();
|
||
}
|
||
</script>
|
||
|
||
<template>
|
||
<ion-page>
|
||
<ion-header>
|
||
<ion-toolbar>
|
||
<ion-title>系统设置</ion-title>
|
||
</ion-toolbar>
|
||
</ion-header>
|
||
|
||
<ion-content>
|
||
<ion-list>
|
||
<ion-item button @click="handleCheckUpdate">
|
||
<ion-label>
|
||
<h2>检查更新</h2>
|
||
<p>当前版本: {{ currentVersion }}</p>
|
||
</ion-label>
|
||
<ion-spinner v-if="isChecking" slot="end" />
|
||
</ion-item>
|
||
</ion-list>
|
||
</ion-content>
|
||
</ion-page>
|
||
</template>
|
||
```
|
||
|
||
### 3. 自定义更新提示
|
||
|
||
如果不想使用默认对话框，可以自己处理：
|
||
|
||
```vue
|
||
<script setup lang="ts">
|
||
const {
|
||
hasUpdate,
|
||
latestVersion,
|
||
forceUpdate,
|
||
updateMessage,
|
||
checkForUpdate,
|
||
openStoreUpdate,
|
||
} = useAppUpdate();
|
||
|
||
async function checkUpdate() {
|
||
const result = await checkForUpdate();
|
||
|
||
if (result.hasUpdate) {
|
||
// 自定义提示逻辑
|
||
if (result.forceUpdate) {
|
||
// 强制更新 - 阻止用户继续使用
|
||
showForceUpdateModal();
|
||
}
|
||
else {
|
||
// 可选更新 - 显示提示但允许跳过
|
||
showOptionalUpdateToast();
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 4. 显示版本信息
|
||
|
||
```vue
|
||
<script setup lang="ts">
|
||
import { onMounted } from "vue";
|
||
|
||
const { currentVersion, hasUpdate, getCurrentVersion, checkForUpdate } = useAppUpdate();
|
||
|
||
onMounted(async () => {
|
||
await getCurrentVersion();
|
||
await checkForUpdate();
|
||
});
|
||
</script>
|
||
|
||
<template>
|
||
<ion-item>
|
||
<ion-label>
|
||
<h2>应用版本</h2>
|
||
<p>{{ currentVersion || '获取中...' }}</p>
|
||
</ion-label>
|
||
<ion-badge v-if="hasUpdate" color="danger">
|
||
有更新
|
||
</ion-badge>
|
||
</ion-item>
|
||
</template>
|
||
```
|
||
|
||
## API 参考
|
||
|
||
### 返回值
|
||
|
||
```typescript
|
||
{
|
||
// 状态
|
||
isChecking: Ref<boolean> // 是否正在检查更新
|
||
hasUpdate: Ref<boolean> // 是否有新版本
|
||
currentVersion: Ref<string> // 当前版本号
|
||
latestVersion: Ref<string> // 最新版本号
|
||
forceUpdate: Ref<boolean> // 是否强制更新
|
||
updateMessage: Ref<string> // 更新提示信息
|
||
updateUrl: Ref<string> // 应用商店链接
|
||
|
||
// 方法
|
||
getCurrentVersion(): Promise<string> // 获取当前版本
|
||
checkForUpdate(): Promise<UpdateResult> // 检查更新
|
||
checkAndPromptUpdate(): Promise<void> // 检查并显示提示
|
||
showUpdateDialog(): Promise<void> // 显示更新对话框
|
||
openStoreUpdate(): Promise<void> // 打开应用商店
|
||
applyUpdate(): Promise<void> // 应用更新
|
||
forceReload(): Promise<void> // 强制刷新
|
||
}
|
||
```
|
||
|
||
### checkForUpdate 返回类型
|
||
|
||
```typescript
|
||
{
|
||
hasUpdate: boolean // 是否有更新
|
||
currentVersion: string // 当前版本
|
||
latestVersion?: string // 最新版本
|
||
forceUpdate?: boolean // 是否强制更新
|
||
updateMessage?: string // 更新说明
|
||
updateUrl?: string // 更新链接
|
||
}
|
||
```
|
||
|
||
## 后端 API 接口
|
||
|
||
需要后端实现以下接口：
|
||
|
||
```typescript
|
||
// GET /api/app/version
|
||
// Query Parameters:
|
||
{
|
||
platform: 'ios' | 'android' | 'web' // 平台类型
|
||
currentVersion: string // 当前版本号
|
||
}
|
||
|
||
// Response:
|
||
{
|
||
version: string // 最新版本号
|
||
buildNumber?: number // 构建号
|
||
forceUpdate: boolean // 是否强制更新
|
||
updateMessage?: string // 更新说明（多语言）
|
||
updateUrl?: string // 下载链接
|
||
minSupportVersion?: string // 最低支持版本
|
||
releaseDate?: string // 发布时间
|
||
releaseNotes?: string[] // 更新日志
|
||
}
|
||
```
|
||
|
||
## 环境变量配置
|
||
|
||
在 `.env` 文件中添加：
|
||
|
||
```bash
|
||
# 应用版本（可选，如果不设置会从 Capacitor 读取）
|
||
VITE_APP_VERSION=1.0.0
|
||
```
|
||
|
||
## 版本号规范
|
||
|
||
遵循语义化版本规范（Semantic Versioning）：
|
||
|
||
- **主版本号**：不兼容的 API 修改
|
||
- **次版本号**：向下兼容的功能性新增
|
||
- **修订号**：向下兼容的问题修正
|
||
|
||
示例：`1.2.3`
|
||
|
||
## 注意事项
|
||
|
||
1. **原生应用更新**：iOS 和 Android 原生应用必须通过应用商店更新，不能绕过
|
||
2. **强制更新策略**：谨慎使用强制更新，避免影响用户体验
|
||
3. **版本检查频率**：建议应用启动时检查，避免频繁请求
|
||
4. **降级处理**：如果后端接口失败，应用仍能正常使用
|
||
5. **测试环境**：开发阶段接口返回模拟数据，生产环境需替换为真实 API
|
||
|
||
## 国际化文本
|
||
|
||
已添加的翻译键：
|
||
|
||
```json
|
||
{
|
||
"app.update.title": "发现新版本 / New Version Available",
|
||
"app.update.message": "有新版本可用... / A new version is available...",
|
||
"app.update.now": "立即更新 / Update Now",
|
||
"app.update.later": "稍后再说 / Later",
|
||
"app.update.forceUpdate": "发现新版本，需要更新后才能继续使用"
|
||
}
|
||
```
|
||
|
||
## 生产环境配置
|
||
|
||
1. **替换模拟数据**：在 [useAppUpdate.ts](../composables/useAppUpdate.ts#L80-L100) 中取消注释真实 API 调用
|
||
2. **配置应用商店链接**：后端返回正确的 App Store / Google Play 链接
|
||
3. **设置最低支持版本**：根据实际情况配置 `minSupportVersion`
|