From ebe45c7fe93c26fcd2070b65f98f9f0893bb7592 Mon Sep 17 00:00:00 2001 From: "DESKTOP-I3JPKHK\\wy" <1111> Date: Thu, 11 Dec 2025 18:13:03 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E8=BE=85=E5=8A=A9=E5=B7=A5?= =?UTF-8?q?=E5=85=B7=E4=BF=AE=E6=94=B9=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 145 ++++++++++++++++++++---------------------------------- 1 file changed, 54 insertions(+), 91 deletions(-) diff --git a/README.md b/README.md index 332b1e2..68ef6ca 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ ## ✨ 特性 - **🎯 智能平台适配**：Android 直下直装，iOS 跳转 App Store +- **🧠 智能辅助工具**：内置 `UpgradeAuxiliaryUtils`，支持**设备类型自动识别**与**"稍后更新"状态记忆**（同一版本被跳过不再打扰）。 - **🔄 灵活的更新策略**： - **一键检查**：自动拉取、对比版本、弹窗提示 - **静默检查**：后台获取更新信息，适合冷启动或用户主动点击前的预检查 @@ -29,80 +30,76 @@ dependencies: ## 🚀 快速开始 -### 方式一：一键检查更新（推荐） +### 方式一：使用辅助工具检查（推荐） -这是最简单的方式，一行代码即可完成检查更新并显示升级对话框： +使用 `UpgradeAuxiliaryUtils` 可以自动处理设备类型判断，并记住用户的"稍后更新"选择（若用户对当前版本点击了稍后更新，下次检查将自动跳过，避免重复打扰）。 ```dart -import 'package:yx_app_upgrade_flutter/app_upgrade_plugin.dart'; +import 'package:yx_app_upgrade_flutter/yx_app_upgrade_flutter.dart'; void checkUpdate(BuildContext context) { - // 可选：一次性配置常用选项 - AppUpgradeSimple.instance.configure( - const UpgradeConfig( - showNoUpdateToast: true, - autoInstall: false, - ), - ); - - // 一行调用，自动拉取并展示升级对话框 - AppUpgradeSimple.instance.checkUpdate( - context: context, - future: () async { - // 调用您的 API 获取版本信息 - final response = await http.get('https://your-api.com/check-update'); - final data = json.decode(response.body); + UpgradeAuxiliaryUtils.instance.initiateVersionCheck( + context, + // upType: 1 为 Android, 2 为 iOS + future: (int upType) async { + // 模拟请求 API + // final response = await api.checkVersion(type: upType); - // 返回 AppUpgradeVersion 对象 return AppUpgradeVersion( - versionName: data['versionName'], - versionBuildNumber: data['versionBuildNumber'], - isForce: data['isForceUpdate'] ?? false, - updateContent: data['updateContent'], - downloadUrl: data['downloadUrl'], - appStoreUrl: data['appStoreUrl'], - apkSize: data['apkSize'], - apkMd5: data['apkMd5'], - // 应用市场配置 - appMarkets: (data['appMarkets'] as List?) - ?.map((e) => AppMarket.fromString(e)) - .toList(), - // 支持的更新方式 - supportedMethods: [ - AppUpgradeMethod.market, - AppUpgradeMethod.browser, - AppUpgradeMethod.inApp, - ], + versionName: "1.2.0", + versionBuildNumber: 102, + downloadUrl: "https://example.com/app.apk", + updateContent: "1. 新增功能\n2. 修复Bug", + // ... 其他配置 ); }, + // 可选配置 + showNoUpdateToast: true, // 无更新时是否提示 + config: UpgradeConfig.production, // 指定环境配置 ); } ``` -### 方式二：静默检查 + 由用户决定 +### 方式二：基础 API (AppUpgradeSimple) -此方式适用于： -1. **App 启动时**：在后台静默检查是否有更新，如果有则在合适的时机（如用户点击"版本更新"按钮时）展示，避免打断用户操作。 -2. **红点提示**：检查到有更新时仅显示红点，用户点击后才弹出对话框。 +如果您需要更底层的控制，或者不需要"稍后更新"的记忆功能，可以直接使用核心类 `AppUpgradeSimple`。 + +#### 1. 一键检查更新 + +```dart +import 'package:yx_app_upgrade_flutter/app_upgrade_simple.dart'; + +// ... +AppUpgradeSimple.instance.checkUpdate( + context: context, + future: () async { + // 调用 API 获取版本信息 + return AppUpgradeVersion( + // ... + ); + }, +); +``` + +#### 2. 静默检查 + 由用户决定 + +此方式适用于 App 启动时在后台静默检查，仅在有更新时（如显示红点）提示用户。 ```dart // 1. 静默检查更新（不显示任何 UI） final upgradeInfo = await AppUpgradeSimple.instance.silentCheckUpdate( future: () async { - // 调用您的 API return AppUpgradeVersion(...); }, ); // 2. 根据结果处理 if (upgradeInfo != null && upgradeInfo.hasUpdate) { - // 有新版本，可以显示红点或在用户点击时调用弹窗 print('发现新版本: ${upgradeInfo.versionName}'); - - // 在需要展示弹窗的时机（如用户点击按钮）： + // 显示红点，或者在用户点击"检查更新"按钮时调用: AppUpgradeSimple.instance.showPreparedUpgrade( context: context, - info: upgradeInfo, // 传入刚才获取的 info + info: upgradeInfo, ); } ``` @@ -120,7 +117,7 @@ AppUpgradeSimple.instance.configure(const UpgradeConfig( autoInstall: false, installTimeout: 60, enableDebugLog: true, - requireInstallPermission: false, // 默认不需要权限，直接安装 + requireInstallPermission: false, )); ``` @@ -128,14 +125,13 @@ AppUpgradeSimple.instance.configure(const UpgradeConfig( ### 富文本更新日志 -更新内容 (`updateContent`) 支持简单的 Markdown 风格富文本，让更新日志更清晰： +更新内容 (`updateContent`) 支持简单的 Markdown 风格富文本： - **粗体**：`**重要内容**` - **斜体**：`__斜体内容__` - **代码块**：`` `version 2.0` `` - **高亮**：`[特别注意]` -示例： ```text 1. 新增 **深色模式** 支持 2. 修复 `Login` 页面崩溃问题 @@ -145,11 +141,9 @@ AppUpgradeSimple.instance.configure(const UpgradeConfig( ### 对话框特性 - **发现新版本**（强制/非强制） - - 强制更新：不可关闭，必须更新 - - 非强制更新：可稍后更新，支持后台下载 -- **版本信息卡片**：显示当前版本、新版本、APK 大小 -- **下载进度展示**：实时显示下载进度百分比和状态 -- **安装状态检测**：自动检测安装结果，支持重试 +- **版本信息卡片** +- **下载进度展示** +- **安装状态检测** ## ⚙️ Android 配置 @@ -200,25 +194,18 @@ AppUpgradeSimple.instance.configure(const UpgradeConfig( ```xml - - - - - - - ``` ## 📡 服务端返回协议 -服务端需要返回包含以下字段的 JSON： +服务端需要返回包含以下字段的 JSON，并在前端转换为 `AppUpgradeVersion` 对象： ```json { @@ -235,24 +222,15 @@ AppUpgradeSimple.instance.configure(const UpgradeConfig( } ``` -### 关键字段说明 - -- **versionBuildNumber**（必填）：版本号（整数），用于比较。如果大于当前版本号，则提示更新。 -- **versionName**（必填）：版本名称，如 "1.0.1"。如果 BuildNumber 相同但 VersionName 更大（字典序），也会提示更新。 -- **appMarkets**（可选）：Android 应用市场白名单。配置后，优先尝试跳转已安装且在白名单中的市场。 -- **supportedMethods**（可选）：指定支持的更新方式（market/browser/inApp）。 - ## 🔧 进阶能力 ### 1) 网络配置 -支持开发/生产环境切换，以及自定义 HTTP 配置（如 Headers、超时）： - ```dart -// 自动选择（Debug 绕过证书、Release 严格校验） +// 自动选择 AppUpgradePlugin().configureHttp(HttpConfig.auto); -// 手动配置： +// 手动配置 AppUpgradePlugin().configureHttp(const HttpConfig( ignoreCertificate: false, enableLog: true, @@ -261,27 +239,12 @@ AppUpgradePlugin().configureHttp(const HttpConfig( )); ``` -### 2) 权限助手（Android） +### 2) 预下载 APK ```dart -import 'package:yx_app_upgrade_flutter/core/permission_helper.dart'; - -// 检查并请求存储权限 -final hasStorage = await PermissionHelper.checkAndRequestStoragePermission(context: context); - -// 检查并请求安装权限 -final hasInstall = await PermissionHelper.checkAndRequestInstallPermission(context: context); -``` - -### 3) 预下载 APK - -```dart -// 后台预下载 APK（不显示 UI） final apkPath = await AppUpgradeSimple.instance.preDownloadApk( - url: 'https://your-cdn.com/app-release.apk', - onProgress: (progress) { - print('下载进度: ${progress.percentage}%'); - }, + url: 'https://...', + onProgress: (progress) => print('${progress.percentage}%'), ); ```