Flutter插件volt的介绍与使用方法详解

Flutter插件volt的介绍与使用方法详解

volt 是一个用于轻松管理异步数据获取、缓存和实时数据传输的插件。它通过极简的代码实现了高效的数据管理和状态更新。

特性

• ⚡️ 极速开发：通过减少样板代码实现快速开发。
• 🚀 快速内存缓存：支持即时数据访问。
• 💾 稳健的磁盘缓存：提供无缝离线支持。
• 🔄 智能查询去重：优化网络请求。
• 🔮 可配置的自动重新获取：保持数据新鲜。
• 📡 实时反应式更新：跨所有监听器实时同步。
• 🧩 易于集成到现有项目：无需大量改动即可使用。
• 🧠 计算隔离支持：处理繁重的反序列化任务。
• 📦 简洁高效的包：用于状态管理。
• 🔒 内置错误处理、自动恢复和重试机制。

安装

在 pubspec.yaml 文件中添加以下依赖项：

flutter pub add volt

使用方法

查询数据

通过 VoltQuery 来定义和执行查询操作。以下是一个示例，展示如何从远程 API 获取照片数据并显示其标题。

// 定义查询函数
VoltQuery<Photo> photoQuery(String id) => VoltQuery(
      queryKey: ['photo', id], // 唯一标识符
      queryFn: () => fetch('https://jsonplaceholder.typicode.com/photos/$id'), // 数据源
      select: Photo.fromJson, // 数据解析
    );

Widget build(BuildContext context) {
  // 执行查询
  final photo = useQuery(photoQuery('1'));

  return photo == null
      ? CircularProgressIndicator() // 加载中
      : Text('Photo: ${photo.title}'); // 显示照片标题
}

突变操作（如删除数据）

通过 VoltMutation 来执行突变操作，例如删除照片。

// 定义突变函数
VoltMutation<String> useDeletePhotoMutation() {
  final queryClient = useQueryClient(); // 获取全局 QueryClient

  return useMutation(
    mutationFn: (photoId) => fetch(
      'https://jsonplaceholder.typicode.com/photos/$photoId',
      method: 'DELETE', // HTTP 方法
    ),
    onSuccess: (photoId) => queryClient.prefetchQuery(photoQuery(photoId)), // 成功回调
  );
}

Widget build(BuildContext context) {
  // 使用突变函数
  final deletePhotoMutation = useDeletePhotoMutation();

  return deletePhotoMutation.state.isLoading
      ? const CircularProgressIndicator() // 加载中
      : ElevatedButton(
          onPressed: () => deletePhotoMutation.mutate('1'), // 触发突变
          child: const Text('Delete Photo'), // 按钮文本
        );
}

配置全局设置

可以通过 QueryClient 配置全局选项，例如缓存策略、错误处理等。

Widget build(BuildContext context) {
  // 初始化 QueryClient
  final queryClient = useMemoized(() => QueryClient(
    // 配置选项
  ));

  return QueryClientProvider(
    client: queryClient, // 提供全局 QueryClient
    child: MyApp(), // 应用根组件
  );
}

查询依赖关系

VoltQuery 支持动态依赖关系，例如根据账户 ID 查询相册。

// 定义账户查询
final accountQuery = VoltQuery(
  queryKey: ['account'],
  queryFn: () async => fetch('https://jsonplaceholder.typicode.com/account/1'),
  select: Account.fromJson,
);

// 定义相册查询
VoltQuery<Photos> photosQuery(Account? account) =>
    VoltQuery(
      queryKey: ['photos', account?.id],
      queryFn: account == null
          ? null // 如果账户为空，则禁用查询
          : () async => fetch('https://jsonplaceholder.typicode.com/account/${account.id}/photos/'),
      select: Photos.fromJson,
    );

Widget build(BuildContext context) {
  // 执行查询
  final account = useQuery(accountQuery);
  final photos = useQuery(photosQuery(account));

  ...
}

API 稳定性

volt 的公共 API 当前不稳定，可能会在 1.0.0 发布之前发生重大变更。

致谢

volt 的公共 API 设计灵感来源于 React Query，这是一个流行的 React 应用程序数据获取和状态管理库。

示例代码运行效果

以下是完整的示例代码，展示如何使用 volt 插件获取和显示照片信息，并提供删除功能。

import 'package:flutter/material.dart';
import 'package:volt/volt.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return QueryClientProvider(
      client: QueryClient(), // 初始化 QueryClient
      child: MaterialApp(
        home: HomeScreen(),
      ),
    );
  }
}

class HomeScreen extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    // 定义查询函数
    final photoQuery = VoltQuery<Photo>(
      queryKey: ['photo', '1'],
      queryFn: () => fetch('https://jsonplaceholder.typicode.com/photos/1'),
      select: Photo.fromJson,
    );

    // 定义突变函数
    final deletePhotoMutation = useDeletePhotoMutation();

    return Scaffold(
      appBar: AppBar(title: Text('Volt Example')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            FutureBuilder(
              future: useQuery(photoQuery).data,
              builder: (context, snapshot) {
                if (snapshot.connectionState == ConnectionState.waiting) {
                  return CircularProgressIndicator();
                } else if (snapshot.hasError) {
                  return Text('Error: ${snapshot.error}');
                } else {
                  return Text('Photo: ${snapshot.data!.title}');
                }
              },
            ),
            SizedBox(height: 20),
            ElevatedButton(
              onPressed: () => deletePhotoMutation.mutate('1'),
              child: Text('Delete Photo'),
            ),
          ],
        ),
      ),
    );
  }
}

class Photo {
  final int id;
  final String title;

  Photo({required this.id, required this.title});

  factory Photo.fromJson(Map<String, dynamic> json) {
    return Photo(id: json['id'], title: json['title']);
  }
}

class Account {
  final int id;

  Account({required this.id});

  factory Account.fromJson(Map<String, dynamic> json) {
    return Account(id: json['id']);
  }
}

class Photos {
  final List<Photo> photos;

  Photos({required this.photos});

  factory Photos.fromJson(List<dynamic> json) {
    return Photos(photos: json.map((e) => Photo.fromJson(e)).toList());
  }
}

Future<Map<String, dynamic>> fetch(String url) async {
  final response = await HttpClient().getUrl(Uri.parse(url)).close();
  return await response.json();
}