Flutter Firestore数据转换插件firestore_converter的使用

Flutter Firestore数据转换插件firestore_converter的使用

介绍

firestore_converter 是一个用于简化 Firestore 数据模型与 Dart 类之间转换的插件。通过使用 [@FirestoreConverter](/user/FirestoreConverter) 注解，可以自动生成 withConverter 实现，从而减少样板代码。它最好与其他注解库（如 freezed 或 json_serializable）一起使用，但并不是必需的。

减少样板代码

Before:

part 'example.freezed.dart';
part 'example.g.dart';

[@freezed](/user/freezed)
class Example<T> with _$Example<T> {
  factory Example(int a) = _Example;
  factory Example.fromJson(Map<String, Object?> json) => _$ExampleFromJson(json);
}

CollectionReference<Example> exampleCollection([String path = 'examples']) {
  return FirebaseFirestore.instance
      .collection(path)
      .withConverter<Example>(
        fromFirestore: (snapshot, _) => Example.fromJson(snapshot.data()!),
        toFirestore: (instance, _) => instance.toJson(),
      );
}

DocumentReference<Example> exampleDoc({String path = 'examples', required String docId}) {
  return FirebaseFirestore.instance
      .doc('$path/$docId')
      .withConverter<Example>(
        fromFirestore: (snapshot, _) => Example.fromJson(snapshot.data()!),
        toFirestore: (instance, _) => instance.toJson(),
      );
}

After:

part 'example.firestore_converter.dart';
part 'example.freezed.dart';
part 'example.g.dart';

[@freezed](/user/freezed)
[@FirestoreConverter](/user/FirestoreConverter)(defaultPath: 'examples')
class Example<T> with _$Example<T> {
  factory Example(int a) = _Example;
  factory Example.fromJson(Map<String, Object?> json) => _$ExampleFromJson(json);
}

安装

1. 安装 build_runner 以运行代码生成：

   flutter pub add dev:build_runner
   

2. 安装 firestore_converter_generator 作为开发依赖：

   flutter pub add dev:firestore_converter_generator
   

3. 安装 firestore_converter 作为普通依赖：

   flutter pub add firestore_converter
   

升级指南（适用于版本1.0.8之前的用户）

如果你之前使用的是 firestore_converter 版本1.0.8之前的版本，请按照以下步骤进行升级：

1. 移除旧的依赖：

   flutter pub remove firestore_converter_annotation
   flutter pub remove firestore_converter
   

2. 添加新的依赖：

   flutter pub add dev:build_runner
   flutter pub add dev:firestore_converter_generator
   flutter pub add firestore_converter
   

3. 在源代码中替换导入语句：

   • 将 import 'package:firestore_converter_annotation/firestore_converter_annotation.dart'; 替换为：

     import 'package:firestore_converter/firestore_converter.dart';
     

使用方法

在数据类上使用 [@FirestoreConverter](/user/FirestoreConverter)(defaultPath: 'someDataPathInFirestore') 注解，将生成两个辅助函数：

• ${modelClassName}Collection
• ${modelClassName}Doc

请注意，这些是函数而不是成员，因为目前无法通过代码生成向模型类添加静态函数。模型名称的首字母将被转换为小写，以符合 Dart 的函数命名规范。

实现 fromJson 和 toJson

firestore_converter 依赖于 fromJson 和 toJson 方法的存在或实现。你可以使用 freezed、json_serializable 或其他注解库来方便地实现这两个方法。当然，你也可以手动实现它们，但这可能会违背使用代码生成的目的。

注意事项

• 必须启用或实现 JSON 转换的 fromJson 和 toJson 方法。
• 使用给定的路径作为集合和文档的默认参数。
• 不支持 build.yaml 中的默认设置，因为路径设置是针对每个模型类的。

示例：使用 firestore_converter 和 freezed

定义你的模型类，例如 example.dart：

part 'example.firestore_converter.dart';
part 'example.freezed.dart';
part 'example.g.dart';

[@freezed](/user/freezed)
[@FirestoreConverter](/user/FirestoreConverter)(defaultPath: 'examples')
class Example<T> with _$Example<T> {
  factory Example(int a) = _Example;
  factory Example.fromJson(Map<String, Object?> json) => _$ExampleFromJson(json);
}

运行代码生成以生成 example.firestore_converter.dart：

flutter pub run build_runner build --delete-conflicting-outputs

开始使用：

// 现在可以轻松创建完全类型的 CollectionReferences、DocumentReferences 或 SnapShot 对象：
CollectionReference<Example> col1 = exampleCollection().orderBy('date', descending: true); // 默认路径为注解中的 'examples'
CollectionReference<Example> col2 = exampleCollection('some_other_path').orderBy('a', descending: true);
DocumentReference<Example> doc1 = exampleDoc(docId: 'exampleId'); // 默认路径为注解中的 'examples'
DocumentReference<Example> doc2 = exampleDoc(path: 'some_other_path', docId: 'exampleId');

// 检索某些文档数据
var myDoc = exampleDoc(path: 'some_other_path', docId: 'exampleId').get();
// 直接从快照访问类型化的成员
debugPrint(myDoc.data().a);

完整示例 Demo

以下是一个完整的示例，展示了如何使用 firestore_converter 和 freezed 来创建一个简单的 Flutter 应用程序，该应用程序连接到 Firestore 并显示用户列表：

// 这个示例需要 Firestore 模拟器正在运行！
// 通过以下命令启动：
// firebase emulators:start --project demo-example

import 'package:cloud_firestore/cloud_firestore.dart';
import 'package:faker/faker.dart';
import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_ui_firestore/firebase_ui_firestore.dart';
import 'package:firestore_converter/firestore_converter.dart';
import 'package:flutter/material.dart';
import 'package:freezed_annotation/freezed_annotation.dart';

part 'main.firestore_converter.dart';
part 'main.freezed.dart';
part 'main.g.dart';

var faker = Faker();

[@FirestoreConverter](/user/FirestoreConverter)(defaultPath: 'users')
[@freezed](/user/freezed)
class User with _$User {
  factory User({
    required String name,
    required String email,
    required int salary,
  }) = _User;

  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
}

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 这个示例需要 Firestore 模拟器正在运行！
  // 通过以下命令启动：
  // firebase emulators:start --project demo-example

  await Firebase.initializeApp(
    options: const FirebaseOptions(
      apiKey: 'not-required-for-emulator',
      appId: 'not-required-for-emulator',
      messagingSenderId: 'not-required-for-emulator',
      projectId: 'demo-example',
    ),
  );

  try {
    FirebaseFirestore.instance.useFirestoreEmulator('localhost', 8080);
  } catch (e) {
    print(e);
    rethrow;
  }

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        floatingActionButton: Builder(builder: (context) {
          return FloatingActionButton(
            key: const Key('addButton'),
            onPressed: () async {
              var newUser = User(
                email: faker.internet.email(),
                name: faker.person.name(),
                salary: faker.randomGenerator.integer(100000),
              );
              try {
                await userCollection().add(newUser);
                ScaffoldMessenger.of(context).showSnackBar(const SnackBar(
                  content: Text('New user added'),
                  key: Key('snackbar'),
                ));
              } catch (e) {
                debugPrint(e.toString());
                rethrow;
              }
            },
            child: const Icon(Icons.add),
          );
        }),
        body: FirestoreListView<User>(
          query: userCollection().orderBy('name'),
          itemBuilder: (context, snapshot) => Card(
            child: ListTile(
              key: Key(snapshot.data().name),
              title: Text(snapshot.data().name),
              subtitle: Row(
                children: [
                  Text(snapshot.data().email),
                  const Expanded(child: Center()),
                  Text(snapshot.data().salary.toString()),
                ],
              ),
            ),
          ),
        ),
      ),
    );
  }
}