事件

Capacitor Updater 插件提供了多个事件,您可以监听这些事件来监控更新过程并响应不同的状态。

事件监听器设置

要监听事件,请在 CapacitorUpdater 对象上使用 addListener 方法:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// 添加监听器
const listener = await CapacitorUpdater.addListener('eventName', (event) => {
  // 处理事件
});

// 不再需要时移除监听器
listener.remove();

// 移除所有监听器
await CapacitorUpdater.removeAllListeners();

可用事件

download

在 bundle 下载过程中触发。提供下载进度信息。

CapacitorUpdater.addListener('download', (event) => {
  console.log(`下载进度: ${event.percent}%`);
  console.log('Bundle 信息:', event.bundle);
});

事件数据:

• percent: number - 下载进度百分比 (0-100)
• bundle: BundleInfo - 正在下载的 bundle 信息

注意

此事件在下载期间触发多次以报告进度。

noNeedUpdate

当检查更新确定不需要更新时触发。

CapacitorUpdater.addListener('noNeedUpdate', (event) => {
  console.log('应用是最新的');
  console.log('当前 bundle:', event.bundle);
});

事件数据:

• bundle: BundleInfo - 当前 bundle 的信息

updateAvailable

当有新更新可供下载时触发。

CapacitorUpdater.addListener('updateAvailable', (event) => {
  console.log('更新可用');
  console.log('新 bundle:', event.bundle);
  // 如果需要,您可以在这里触发下载
});

事件数据:

• bundle: BundleInfo - 可用更新 bundle 的信息

downloadComplete

当 bundle 下载成功完成时触发。

CapacitorUpdater.addListener('downloadComplete', (event) => {
  console.log('下载完成');
  console.log('已下载的 bundle:', event.bundle);
  // 您可能希望将此 bundle 设置为下一个
});

事件数据:

• bundle: BundleInfo - 已下载 bundle 的信息

majorAvailable

当主要更新可用但被自动更新设置阻止时触发。

CapacitorUpdater.addListener('majorAvailable', (event) => {
  console.log('主要更新可用:', event.version);
  // 通知用户有关主要更新
});

事件数据:

• version: string - 主要更新的版本号

提示

主要更新通常需要用户确认或应用商店更新。使用此事件适当地通知用户。

updateFailed

当更新在下次应用启动时安装失败时触发。

CapacitorUpdater.addListener('updateFailed', (event) => {
  console.error('更新安装失败');
  console.log('失败的 bundle:', event.bundle);
  // 处理回滚或重试逻辑
});

事件数据:

• bundle: BundleInfo - 安装失败的 bundle 信息

downloadFailed

当 bundle 下载失败时触发。

CapacitorUpdater.addListener('downloadFailed', (event) => {
  console.error('版本下载失败:', event.version);
  // 处理下载重试逻辑
});

事件数据:

• version: string - 下载失败的版本

appReloaded

当应用已重新加载时触发。

CapacitorUpdater.addListener('appReloaded', () => {
  console.log('应用已重新加载');
  // 执行任何必要的重新初始化
});

事件数据: 无

appReady

当应用在更新后准备就绪可以使用时触发。

CapacitorUpdater.addListener('appReady', (event) => {
  console.log('应用已准备就绪');
  console.log('当前 bundle:', event.bundle);
  console.log('状态:', event.status);
});

事件数据:

• bundle: BundleInfo - 当前 bundle 的信息
• status: string - 就绪状态

警告

记得在配置的超时时间内(默认 10 秒)调用 notifyAppReady() 以防止自动回滚。

BundleInfo 对象

许多事件包含一个具有以下属性的 BundleInfo 对象:

interface BundleInfo {
  id: string;           // 唯一 bundle 标识符
  version: string;      // Bundle 版本
  downloaded: string;   // 下载时间戳
  checksum?: string;    // Bundle 校验和(如果可用)
  status: BundleStatus; // Bundle 状态
}

其中 BundleStatus 可以是:

• 'success' - Bundle 下载成功
• 'error' - Bundle 下载/安装失败
• 'pending' - Bundle 待设置为下一个
• 'downloading' - Bundle 当前正在下载

示例: 完整的更新流程

以下是使用事件处理完整更新流程的示例:

警告

此 UpdateManager 类不包括自动更新流程所需的 CapacitorUpdater.notifyAppReady() 调用。 有关更多信息,请参阅正确放置 notifyAppReady 调用文档。

import { CapacitorUpdater } from '@capgo/capacitor-updater';

export class UpdateManager {
  private listeners: any[] = [];

  async setupListeners() {
    // 监听可用更新
    this.listeners.push(
      await CapacitorUpdater.addListener('updateAvailable', async (event) => {
        console.log('更新可用:', event.bundle.version);
        // 自动下载更新
        await CapacitorUpdater.download({
          url: event.bundle.url,
          version: event.bundle.version
        });
      })
    );

    // 监控下载进度
    this.listeners.push(
      await CapacitorUpdater.addListener('download', (event) => {
        console.log(`正在下载: ${event.percent}%`);
        // 更新 UI 进度条
        this.updateProgressBar(event.percent);
      })
    );

    // 处理下载完成
    this.listeners.push(
      await CapacitorUpdater.addListener('downloadComplete', async (event) => {
        console.log('下载完成:', event.bundle.version);
        // 设置为下一个 bundle
        await CapacitorUpdater.next({ id: event.bundle.id });
      })
    );

    // 处理失败
    this.listeners.push(
      await CapacitorUpdater.addListener('downloadFailed', (event) => {
        console.error('下载失败:', event.version);
        this.showError('更新下载失败。请稍后重试。');
      })
    );

    this.listeners.push(
      await CapacitorUpdater.addListener('updateFailed', (event) => {
        console.error('更新安装失败:', event.bundle.version);
        this.showError('更新安装失败。应用已回滚。');
      })
    );

    // 处理应用就绪
    this.listeners.push(
      await CapacitorUpdater.addListener('appReady', async (event) => {
        console.log('应用就绪,bundle:', event.bundle.version);
      })
    );
  }

  cleanup() {
    // 不再需要时移除所有监听器
    this.listeners.forEach(listener => listener.remove());
    this.listeners = [];
  }

  private updateProgressBar(percent: number) {
    // 更新您的 UI 进度条
  }

  private showError(message: string) {
    // 向用户显示错误
  }
}

最佳实践

1. 始终调用 notifyAppReady(): 使用自动更新时,在应用初始化后始终调用此方法以防止回滚。

2. 优雅地处理失败: 为下载和更新失败实现适当的错误处理。

3. 提供用户反馈: 使用下载进度事件向用户显示更新进度。

4. 清理监听器: 不再需要时移除事件监听器以防止内存泄漏。

5. 测试更新场景: 测试各种更新场景,包括失败、回滚和主要更新。