Flutter 鸿蒙应用离线模式实战：无网络也能流畅使用

本文为 Flutter for OpenHarmony 跨平台应用开发任务 34 实战教程，完整实现应用离线模式功能，解决无网络环境下的使用体验问题。基于前序网络优化与缓存体系，扩展实现本地数据持久化缓存、离线操作队列、网络状态智能切换、断网恢复自动同步等核心能力，同时设计统一的离线状态 UI 提示与交互逻辑。所有代码在 macOS + DevEco Studio 环境开发，兼容开源鸿蒙真机与模拟

Lanren的编程日记

29人浏览 · 2026-04-21 20:28:34

Lanren的编程日记 · 2026-04-21 20:28:34 发布

Flutter 鸿蒙应用离线模式实战：无网络也能流畅使用

欢迎加入开源鸿蒙跨平台社区： https://openharmonycrossplatform.csdn.net

📄 文章摘要

📋 文章目录

📝 前言

🎯 功能目标与技术要点

📝 步骤1：依赖确认与项目结构规划

📝 步骤2：实现本地离线缓存服务

📝 步骤3：实现离线操作队列与同步机制

📝 步骤4：实现离线模式统一管理器

📝 步骤5：设计离线模式 UI 组件与页面

📝 步骤6：集成离线模式到主应用与路由

📸 运行效果展示

⚠️ 鸿蒙平台兼容性注意事项

✅ 开源鸿蒙设备验证结果

💡 功能亮点与扩展方向

🎯 全文总结

📝 前言

在移动场景中，网络不稳定、地铁隧道、信号盲区等情况频繁出现，应用若仅支持在线使用，会直接导致用户无法操作、数据加载失败，体验极差。

为解决这一问题，本次开发任务 34：实现离线模式，提升用户体验。核心目标是让应用在无网络时仍可正常浏览缓存数据、提交操作，网络恢复后自动同步，实现“在线离线无缝切换”。

整体方案基于 Flutter 主流本地存储与网络检测能力，深度兼容 OpenHarmony 平台，不侵入原有业务逻辑，以最小成本实现完整离线能力。

🎯 功能目标与技术要点

一、核心目标

支持无网络环境正常浏览已缓存数据
支持离线状态下提交增删改操作，存入离线队列
实时监测网络状态，自动切换在线/离线模式
网络恢复后自动同步离线操作，支持失败重试
统一的离线提示 UI，不干扰正常操作流程
全量兼容开源鸿蒙设备，无原生适配问题

二、核心技术要点

本地缓存：shared_preferences + 内存缓存双策略
网络检测：connectivity_plus 实时监听网络变化
离线队列：持久化存储待同步操作，支持创建/更新/删除类型
自动同步：网络恢复时触发批量同步，带指数退避重试
状态管理：全局单例管理器，提供统一调用入口
UI 组件：离线横幅、状态卡片、离线感知按钮
鸿蒙兼容：遵循 OpenHarmony 权限与生命周期规范

📝 步骤1：依赖确认与项目结构规划

1.1 新增依赖

在 pubspec.yaml 中确保以下依赖已配置：

dependencies:
  flutter:
    sdk: flutter
  dio: ^5.4.0
  connectivity_plus: ^6.1.5
  shared_preferences: ^2.2.2

执行：

flutter pub get

1.2 项目结构

本次新增文件统一规划如下：

lib/
├── services/
│ ├── offline_cache_service.dart # 离线缓存核心服务
│ ├── offline_operation_queue.dart # 离线操作队列
│ └── offline_mode_manager.dart # 离线模式总管理器
├── widgets/
│ └── offline_widgets.dart # 离线相关UI组件
└── screens/
└── offline_mode_showcase_page.dart # 离线模式演示页面

📝 步骤2：实现本地离线缓存服务

offline_cache_service.dart 负责双重缓存（内存+本地）、缓存过期、缓存统计、清理逻辑。

核心能力：

设置 TTL 过期机制，避免脏数据
支持按 key 缓存/读取/删除
支持批量清理过期缓存与全部缓存
提供缓存大小、命中率统计

核心代码结构：

class OfflineCacheService {
  final Map<String, CacheItem> _memoryCache = {};
  late SharedPreferences _prefs;

  Future<void> initialize() async {
    _prefs = await SharedPreferences.getInstance();
    await _loadFromDisk();
  }

  Future<void> saveCache<T>(String key, T data, Duration ttl) async {
    // 写入内存与本地存储
  }

  T? getCache<T>(String key) {
    // 读取并判断是否过期
  }

  Future<void> clearExpired() async {}
  Future<void> clearAll() async {}
}

class CacheItem {
  final dynamic data;
  final DateTime expireAt;
  // ...
}

📝 步骤3：实现离线操作队列与同步机制

offline_operation_queue.dart 用于记录用户在离线时提交的操作，如发布、修改、删除等，网络恢复后自动同步。

核心能力：

支持操作类型：create / update / delete
持久化存储，重启应用不丢失
同步状态：pending / syncing / success / failed
自动重试机制（最多3次）
同步完成回调与失败通知

核心代码结构：

enum PendingOperationType { create, update, delete }
enum OperationStatus { pending, syncing, success, failed }

class PendingOperation {
  final String id;
  final PendingOperationType type;
  final String endpoint;
  final dynamic data;
  final OperationStatus status;
  // ...
}

class OfflineOperationQueue {
  final List<PendingOperation> _operations = [];

  Future<void> addOperation(/* ... */) async {}
  Future<void> syncOperations() async {}
  Future<void> retryFailed() async {}
  // ...
}

📝 步骤4：实现离线模式统一管理器

offline_mode_manager.dart 是全局唯一入口，整合网络检测、缓存、队列、状态流。

上层业务只需调用它，无需关心底层实现。

核心方法：

fetchData()：优先缓存，无缓存走网络
executeWithOfflineSupport()：支持离线的业务操作
stream：实时监听网络与离线状态
syncWhenNetworkRecover()：网络恢复自动同步

核心代码结构：

class OfflineModeManager {
  static final OfflineModeManager instance = OfflineModeManager._internal();
  late final OfflineCacheService _cache;
  late final OfflineOperationQueue _queue;
  late final NetworkConnectivityService _network;

  Future<void> initialize() async {
    // 初始化所有子服务
  }

  Future<T?> fetchData<T>(
    String key,
    Future<T> Function() fetchFromNetwork,
    Duration cacheTTL,
  ) async {
    // 离线逻辑 + 在线逻辑统一封装
  }

  Future<T?> executeWithOfflineSupport<T>({
    required Future<T> Function() onlineOperation,
    required T Function() offlineFallback,
    required String endpoint,
    required PendingOperationType type,
    dynamic data,
  }) async {
    // 在线执行 / 离线入队
  }

  Stream<OfflineStatus> get statusStream => // ...
}

📝 步骤5：设计离线模式 UI 组件与页面

在 offline_widgets.dart 中实现通用离线 UI，可全局复用：

OfflineBanner：顶部离线提示条
OfflineIndicator：小图标显示网络状态
OfflineStatusCard：展示同步进度、待同步数量
OfflineAwareButton：离线时自动变灰并提示

同时实现 offline_mode_showcase_page.dart 演示页面，包含：

实时网络状态展示
缓存数据管理
待同步操作列表
手动同步/重试按钮

📝 步骤6：集成离线模式到主应用与路由

在 main.dart 中初始化离线管理器：

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await OfflineModeManager.instance.initialize();
  runApp(const MyApp());
}

在路由中添加演示页面：

MaterialPageRoute(
  builder: (context) => const OfflineModeShowcasePage(),
),

在需要离线支持的页面使用：

final data = await OfflineModeManager.instance.fetchData(
  'home_data',
  () => api.getHomeData(),
  cacheTTL: const Duration(hours: 12),
);