feat: 添加应用版本更新功能；实现版本检查、更新提示及国际化支持

2025-12-30 18:07:14 +07:00
parent 7ce60b860c
commit e7e2b1bd85
6 changed files with 484 additions and 70 deletions
--- a/app.update.md
+++ b/app.update.md
@@ -0,0 +1,242 @@
+# 应用版本更新使用示例
+
+## 功能说明
+
+`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
+<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>
+
+<script setup lang="ts">
+const {
+  isChecking,
+  currentVersion,
+  checkAndPromptUpdate,
+} = useAppUpdate()
+
+async function handleCheckUpdate() {
+  await checkAndPromptUpdate()
+}
+</script>
+```
+
+### 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
+<template>
+  <ion-item>
+    <ion-label>
+      <h2>应用版本</h2>
+      <p>{{ currentVersion || '获取中...' }}</p>
+    </ion-label>
+    <ion-badge v-if="hasUpdate" color="danger">有更新</ion-badge>
+  </ion-item>
+</template>
+
+<script setup lang="ts">
+import { onMounted } from 'vue'
+
+const { currentVersion, hasUpdate, getCurrentVersion, checkForUpdate } = useAppUpdate()
+
+onMounted(async () => {
+  await getCurrentVersion()
+  await checkForUpdate()
+})
+</script>
+```
+
+## 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`