Flutter离线功能实现：API数据本地存储及类型错误修复

一、先修复类型错误 #

这个错误的核心是Hive取出的列表未被正确转为List<Article>类型，或者FutureProvider返回值类型不匹配，按以下步骤排查：

1. 明确Hive读取的泛型类型
   确保从Hive Box读取时指定泛型，避免返回原始List：

// 错误写法：未指定泛型，返回的是动态List
final articles = Hive.box('articles').get('cached_articles');

// 正确写法：指定泛型，直接获取List<Article>
final List<Article>? cachedArticles = Hive.box<Article>('articles').get('cached_articles');

2. 修正FutureProvider的返回逻辑
   FutureProvider要求返回FutureOr<List<Article>>，如果直接返回同步List会导致类型不匹配，需包裹为Future：

// 错误写法：直接返回同步List
final cachedArticlesProvider = FutureProvider<List<Article>>((ref) {
  return Hive.box<Article>('articles').get('cached_articles') ?? [];
});

// 正确写法：返回Future（即使是同步操作也需封装）
final cachedArticlesProvider = FutureProvider<List<Article>>((ref) async {
  // 确保Box已初始化打开
  await Hive.openBox<Article>('articles');
  return Hive.box<Article>('articles').get('cached_articles') ?? [];
});

3. 检查Hive模型适配正确性
   确认Article和Source模型已正确实现Hive适配，包含TypeAdapter并完成注册：

// Article模型示例
@HiveType(typeId: 0)
class Article extends HiveObject {
  @HiveField(0)
  final String title;
  @HiveField(1)
  final Source source;

  Article({required this.title, required this.source});
}

// Source模型示例
@HiveType(typeId: 1)
class Source extends HiveObject {
  @HiveField(0)
  final String id;
  @HiveField(1)
  final String name;

  Source({required this.id, required this.name});
}

// 初始化时注册Adapter并打开Box
void initHive() async {
  await Hive.initFlutter();
  Hive.registerAdapter(ArticleAdapter());
  Hive.registerAdapter(SourceAdapter());
  await Hive.openBox<Article>('articles');
}

二、完整离线功能实现流程 #

结合Riverpod、Hive和网络状态检测，实现“优先网络+无网读缓存+有网更缓存”的逻辑：

1. 网络状态StreamProvider
   复用你已编写的网络检测逻辑，封装为可监听的Provider：

final networkStatusProvider = StreamProvider<bool>((ref) {
  return Connectivity().onConnectivityChanged.map(
    (result) => result != ConnectivityResult.none,
  );
});

2. 整合型新闻数据Provider
   创建主Provider，根据网络状态分支处理数据来源：

final newsArticlesProvider = FutureProvider<List<Article>>((ref) async {
  final isConnected = await ref.watch(networkStatusProvider.future);
  final articleBox = Hive.box<Article>('articles');

  if (isConnected) {
    // 有网络：请求NewsAPI并更新缓存
    final response = await http.get(Uri.parse('你的NewsAPI接口地址'));
    if (response.statusCode == 200) {
      final jsonData = jsonDecode(response.body);
      final articles = (jsonData['articles'] as List)
          .map((item) => Article.fromJson(item))
          .toList();
      // 将新数据写入缓存
      await articleBox.put('cached_articles', articles);
      return articles;
    } else {
      // 请求失败，降级读取缓存
      return articleBox.get('cached_articles') ?? [];
    }
  } else {
    // 无网络：直接读取缓存，无缓存返回空列表
    return articleBox.get('cached_articles') ?? [];
  }
});

3. UI层数据监听与渲染
   在UI中通过ref.watch监听数据，处理加载、空数据、错误状态：

class NewsScreen extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final articlesAsync = ref.watch(newsArticlesProvider);

    return articlesAsync.when(
      loading: () => const CircularProgressIndicator(),
      error: (err, stack) => Text('加载失败：$err'),
      data: (articles) {
        if (articles.isEmpty) {
          return const Text('暂无新闻数据');
        }
        return ListView.builder(
          itemCount: articles.length,
          itemBuilder: (context, index) {
            final article = articles[index];
            return ListTile(
              title: Text(article.title),
              subtitle: Text(article.source.name),
            );
          },
        );
      },
    );
  }
}

三、额外注意事项 #

• 确保Hive初始化完成后再启动应用：

  void main() async {
    WidgetsFlutterBinding.ensureInitialized();
    await initHive();
    runApp(const ProviderScope(child: MyApp()));
  }
  

• 可添加缓存过期逻辑：给缓存数据附加时间戳，读取时判断是否超过有效期（如24小时），有网时自动刷新。
• 优化错误提示：网络请求失败时，可通过Toast或SnackBar告知用户当前使用缓存数据。

内容的提问来源于stack exchange，提问作者Shubham Vimal