yx_app_upgrade_flutter/USAGE_GUIDE.md

App Upgrade Plugin - 完整使用指南

🚀 快速开始

基础用法（一行代码）

import 'package:app_upgrade_plugin/app_upgrade_plugin.dart';

// 最简单的使用方式
await AppUpgradeSimple.instance.checkUpdate(
  context: context,
  url: 'https://api.example.com/check-update',
);

⚙️ 配置选项

预设配置

// 开发模式（详细日志+提示信息）
AppUpgradeSimple.instance.configure(UpgradeConfig.development);

// 生产模式（静默检查+性能优化）
AppUpgradeSimple.instance.configure(UpgradeConfig.production);

自定义配置

AppUpgradeSimple.instance.configure(UpgradeConfig(
  showNoUpdateToast: true,        // 显示无更新提示
  autoInstall: false,             // 自动安装
  installTimeout: 45,             // 安装检测超时（秒）
  enableDebugLog: true,           // 启用调试日志
  customToast: (message) {        // 自定义Toast
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(message)),
    );
  },
));

🎯 使用场景

1. 应用启动时检查更新

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Builder(
        builder: (context) {
          // 应用启动后检查更新
          WidgetsBinding.instance.addPostFrameCallback((_) {
            AppUpgradeSimple.instance.checkUpdate(
              context: context,
              url: 'https://api.example.com/check-update',
            );
          });
          return MyHomePage();
        },
      ),
    );
  }
}

2. 定期检查更新

class MyHomePage extends StatefulWidget {
  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  Timer? _updateTimer;

  @override
  void initState() {
    super.initState();
    // 每24小时检查一次更新
    _updateTimer = Timer.periodic(const Duration(hours: 24), (_) {
      AppUpgradeSimple.instance.checkUpdateSilent(
        url: 'https://api.example.com/check-update',
      );
    });
  }

  @override
  void dispose() {
    _updateTimer?.cancel();
    super.dispose();
  }
}

3. 手动检查更新

ElevatedButton(
  onPressed: () async {
    await AppUpgradeSimple.instance.checkUpdate(
      context: context,
      url: 'https://api.example.com/check-update',
      params: {
        'userId': currentUserId,
        'channel': releaseChannel,
      },
      onComplete: () {
        print('更新检查完成');
      },
    );
  },
  child: const Text('检查更新'),
)

🔧 高级功能

预下载APK

// 后台预下载，不显示UI
final filePath = await AppUpgradeSimple.instance.preDownloadApk(
  url: 'https://example.com/app.apk',
  onProgress: (progress) {
    print('下载进度: ${progress.percentage}%');
  },
);

查找已下载的APK

final existingApk = await AppUpgradeSimple.instance.findDownloadedApk('1.2.0');
if (existingApk != null) {
  print('找到已下载的APK: $existingApk');
}

网络状态检查

final hasNetwork = await AppUpgradeSimple.instance.checkNetworkStatus();
if (!hasNetwork) {
  showDialog(
    context: context,
    builder: (context) => AlertDialog(
      title: const Text('网络错误'),
      content: const Text('请检查网络连接'),
      actions: [
        TextButton(
          onPressed: () => Navigator.of(context).pop(),
          child: const Text('确定'),
        ),
      ],
    ),
  );
}

清理下载缓存

// 清理所有下载的APK文件
await AppUpgradeSimple.instance.clearDownloadCache();

🎨 UI定制

自定义Toast

AppUpgradeSimple.instance.configure(UpgradeConfig(
  customToast: (message) {
    // 使用SnackBar代替Toast
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text(message),
        backgroundColor: Colors.deepPurple,
        behavior: SnackBarBehavior.floating,
      ),
    );
  },
));

富文本更新内容

服务器返回的更新内容支持简单且可嵌套的富文本标记，当前支持四种语法：

• **粗体**：强调关键信息（仍沿用系统字体与字号）
• __斜体__：适合附注或说明文本
• `代码`：以等宽字体+主题色背景展示命令或关键字
• [高亮]：使用主题主色渲染高亮标签

以上标记可以任意嵌套，解析器会自动合并样式。例如：
**学生详情：**__在[学生管理]中添加详情页__ 会得到粗体标题 + 斜体正文 + 主题色高亮的「学生管理」。

示例：

**新功能**
- 添加了[暗黑模式]支持
- 优化了`网络请求`性能
- __修复了已知问题__

**重要更新**
请及时更新到最新版本以获得更好的体验！

📱 平台支持

Android

• ✅ APK下载和安装
• ✅ 权限自动处理
• ✅ 多应用商店支持
• ✅ 安装状态智能检测
• ✅ 断点续传
• ✅ 文件校验

iOS

• ✅ App Store跳转
• ✅ 企业证书分发
• ✅ TestFlight支持

🔍 调试和测试

启用调试日志

AppUpgradeSimple.instance.configure(UpgradeConfig.development);

查看日志输出

🔍 检查更新结果: UpgradeInfo(...)
⚡ 应用回到前台，立即检查安装状态
✅ 检测结果: 安装成功
❌ 检测结果: 安装未完成

测试不同场景

插件内置了测试按钮，可以模拟各种安装场景：

• 模拟安装取消
• 模拟权限拒绝
• 模拟安装超时

🛡️ 错误处理

插件提供了完善的错误处理机制：

网络错误

• 连接超时
• DNS解析失败
• 服务器错误
• 证书验证失败

安装错误

• 权限被拒绝
• APK文件损坏
• 存储空间不足
• 系统版本不兼容

自动重试

• 智能检测安装状态
• 多种重试方式
• 用户友好的错误提示

📊 最佳实践

1. 应用启动检查

// 推荐：应用启动时静默检查
WidgetsBinding.instance.addPostFrameCallback((_) {
  AppUpgradeSimple.instance.checkUpdateSilent(
    url: 'https://api.example.com/check-update',
  ).then((info) {
    if (info != null && info.hasUpdate) {
      // 发现更新，显示提示
      showUpdateNotification(context, info);
    }
  });
});

2. 定期检查

// 推荐：每日检查一次
Timer.periodic(const Duration(days: 1), (_) {
  AppUpgradeSimple.instance.checkUpdateSilent(
    url: 'https://api.example.com/check-update',
  );
});

3. 用户手动检查

// 推荐：提供手动检查按钮
ElevatedButton(
  onPressed: () {
    AppUpgradeSimple.instance.checkUpdate(
      context: context,
      url: 'https://api.example.com/check-update',
    );
  },
  child: const Text('检查更新'),
)

🎯 完整示例

查看 example/lib/main_enhanced.dart 获取完整的使用示例，包含所有功能的演示。

📝 API文档

主要方法

checkUpdate()

检查并处理应用更新的主要方法。

checkUpdateSilent()

静默检查更新，不显示UI。

preDownloadApk()

后台预下载APK文件。

clearDownloadCache()

清理下载缓存。

checkNetworkStatus()

检查网络连接状态。

配置类

UpgradeConfig

升级配置类，控制插件的行为。

预设配置

• UpgradeConfig.development - 开发模式（详细日志+提示信息）
• UpgradeConfig.production - 生产模式（静默检查+性能优化）

---

这个插件现在提供了完整的应用升级解决方案，支持各种使用场景和自定义需求！