riwa-ionic/APP_UPDATE.md

应用版本更新使用示例

功能说明

useAppUpdate 提供了完整的应用版本检查和更新功能，支持：

• ✅ 自动获取当前应用版本（原生/Web）
• ✅ 从后端 API 检查最新版本
• ✅ 版本号比较（语义化版本）
• ✅ 强制更新和可选更新
• ✅ 打开应用商店更新页面
• ✅ 国际化支持（中英文）
• ✅ Service Worker 更新（PWA）

基础使用

1. 在应用启动时检查更新

在 App.vue 或主布局组件中：

<script setup lang="ts">
import { onMounted } from "vue";

const { checkAndPromptUpdate } = useAppUpdate();

onMounted(async () => {
  // 应用启动 3 秒后检查更新
  setTimeout(() => {
    checkAndPromptUpdate();
  }, 3000);
});
</script>

2. 手动触发检查更新

在设置页面添加"检查更新"按钮：

<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. 自定义更新提示

如果不想使用默认对话框，可以自己处理：

<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. 显示版本信息

<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 参考

返回值

{
  // 状态
  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 返回类型

{
  hasUpdate: boolean              // 是否有更新
  currentVersion: string          // 当前版本
  latestVersion?: string          // 最新版本
  forceUpdate?: boolean           // 是否强制更新
  updateMessage?: string          // 更新说明
  updateUrl?: string              // 更新链接
}

后端 API 接口

需要后端实现以下接口：

// 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 文件中添加：

# 应用版本（可选，如果不设置会从 Capacitor 读取）
VITE_APP_VERSION=1.0.0

版本号规范

遵循语义化版本规范（Semantic Versioning）：

• 主版本号：不兼容的 API 修改
• 次版本号：向下兼容的功能性新增
• 修订号：向下兼容的问题修正

示例：1.2.3

注意事项

1. 原生应用更新：iOS 和 Android 原生应用必须通过应用商店更新，不能绕过
2. 强制更新策略：谨慎使用强制更新，避免影响用户体验
3. 版本检查频率：建议应用启动时检查，避免频繁请求
4. 降级处理：如果后端接口失败，应用仍能正常使用
5. 测试环境：开发阶段接口返回模拟数据，生产环境需替换为真实 API

国际化文本

已添加的翻译键：

{
  "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 中取消注释真实 API 调用
2. 配置应用商店链接：后端返回正确的 App Store / Google Play 链接
3. 设置最低支持版本：根据实际情况配置 minSupportVersion