添加辅助工具修改文档
This commit is contained in:
DESKTOP-I3JPKHK\wy
parent
af52743e94
commit
ebe45c7fe9
145
README.md
145
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,
|
||||
),
|
||||
);
|
||||
UpgradeAuxiliaryUtils.instance.initiateVersionCheck(
|
||||
context,
|
||||
// upType: 1 为 Android, 2 为 iOS
|
||||
future: (int upType) async {
|
||||
// 模拟请求 API
|
||||
// final response = await api.checkVersion(type: upType);
|
||||
|
||||
// 一行调用，自动拉取并展示升级对话框
|
||||
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);
|
||||
|
||||
// 返回 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
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<paths xmlns:android="http://schemas.android.com/apk/res/android">
|
||||
<!-- External storage -->
|
||||
<external-path name="external_files" path="." />
|
||||
<!-- Internal app storage -->
|
||||
<files-path name="files" path="." />
|
||||
<!-- Cache directory -->
|
||||
<cache-path name="cache" path="." />
|
||||
<!-- External cache -->
|
||||
<external-cache-path name="external_cache" path="." />
|
||||
<!-- Downloads directory -->
|
||||
<external-path name="downloads" path="Download/" />
|
||||
<!-- External app-specific files directory (Android/data/包名/files/) -->
|
||||
<!-- 用于权限被拒绝时，使用应用私有目录存储下载的 APK -->
|
||||
<external-files-path name="external_app_files" path="." />
|
||||
</paths>
|
||||
```
|
||||
|
||||
## 📡 服务端返回协议
|
||||
|
||||
服务端需要返回包含以下字段的 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}%'),
|
||||
);
|
||||
```
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue