Flutter数据转换插件flutterfire_json_converters的使用

flutterfire_json_converters 是一个用于FlutterFire应用的JSON转换插件，支持与 json_serializable 或 freezed 结合使用。它提供了一些有用的JSON转换器，特别是在处理Cloud Firestore的时间戳字段时非常有用。

如何使用

要求

该包使用了Dart 3的一些特性，因此需要兼容的Dart（Flutter）SDK版本：

environment:
  sdk: '>=3.0.0 <4.0.0'
  flutter: '>=3.10.0'

安装

为了在项目中使用 flutterfire_json_converters，你需要安装以下依赖包：

使用 build_runner 进行代码生成：

flutter pub add --dev build_runner

如果你使用 freezed：

flutter pub add freezed_annotation
flutter pub add --dev freezed

如果你使用 json_serializable：

flutter pub add json_serializable
flutter pub add json_annotation
flutter pub add --dev json_serializable

示例：sealedTimestampConverter

当处理Cloud Firestore的 Timestamp 字段时，可能会遇到以下几种情况：

• 希望将字段作为Dart的 DateTime 类型进行操作。
• 在创建或更新Cloud Firestore文档时，希望某些字段（例如 updatedAt）自动设置为 FieldValue.serverTimestamp()。
• 对于其他字段（例如 createdAt），有时希望指定客户端的 DateTime 并将其保存到Cloud Firestore文档中，而有时则希望自动设置为 FieldValue.serverTimestamp()。

针对这些情况，可以定义 DateTime/Timestamp 字段为 SealedTimestamp 类型，并使用 [@sealedTimestampConverter](/user/sealedTimestampConverter) 或 [@alwaysUseServerTimestampSealedTimestampConverter](/user/alwaysUseServerTimestampSealedTimestampConverter) 注解：

import 'package:flutterfire_json_converters/flutterfire_json_converters.dart';
import 'package:json_annotation/json_annotation.dart';

part 'main.g.dart';

[@JsonSerializable](/user/JsonSerializable)()
class Entity {
  Entity({
    required this.name,
    this.createdAt = const ServerTimestamp(),
    this.updatedAt = const ServerTimestamp(),
  });

  factory Entity.fromJson(Map<String, dynamic> json) => _$EntityFromJson(json);

  final String name;

  // 处理Dart的 `DateTime` 和 Cloud Firestore的 `Timestamp` 类型
  [@sealedTimestampConverter](/user/sealedTimestampConverter)
  final SealedTimestamp createdAt;

  // 处理Dart的 `DateTime` 和 Cloud Firestore的 `Timestamp` 类型，并且在创建/更新文档时总是使用 `FieldValue.serverTimestamp()`
  [@alwaysUseServerTimestampSealedTimestampConverter](/user/alwaysUseServerTimestampSealedTimestampConverter)
  final SealedTimestamp updatedAt;

  Map<String, dynamic> toJson() => _$EntityToJson(this);
}

void main() {
  final epoch = DateTime(1970);
  final entity = Entity(name: 'foo', createdAt: ClientDateTime(epoch));

  print(entity.name); // 输出: 'foo'
  print(entity.createdAt.dateTime); // 输出: 1970-01-01 00:00:00.000
  print(entity.updatedAt.dateTime); // 输出: null

  final json = entity.toJson();

  print(json['name']); // 输出: 'foo'
  print(json['createdAt']); // 输出: Timestamp(seconds=0, nanoseconds=0)
  print(json['updatedAt']); // 输出: FieldValue(Instance of 'MethodChannelFieldValue')
}

获取 DateTime 值

当你想在Dart客户端获取 DateTime 值时，可以调用 SealedTimestamp.dateTime 方法：

final epoch = DateTime(1970);
final entity = Entity(name: 'foo', createdAt: ClientDateTime(epoch));

print(entity.createdAt.dateTime); // 输出: 1970-01-01 00:00:00.000

完整示例

以下是一个完整的示例，展示了如何在Flutter项目中使用 flutterfire_json_converters：

import 'package:flutter/material.dart';
import 'package:flutterfire_json_converters/flutterfire_json_converters.dart';
import 'package:json_annotation/json_annotation.dart';
import 'package:cloud_firestore/cloud_firestore.dart';

part 'main.g.dart';

[@JsonSerializable](/user/JsonSerializable)()
class Entity {
  Entity({
    required this.name,
    this.createdAt = const ServerTimestamp(),
    this.updatedAt = const ServerTimestamp(),
  });

  factory Entity.fromJson(Map<String, dynamic> json) => _$EntityFromJson(json);

  final String name;

  [@sealedTimestampConverter](/user/sealedTimestampConverter)
  final SealedTimestamp createdAt;

  [@alwaysUseServerTimestampSealedTimestampConverter](/user/alwaysUseServerTimestampSealedTimestampConverter)
  final SealedTimestamp updatedAt;

  Map<String, dynamic> toJson() => _$EntityToJson(this);
}

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

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  MyHomePage({Key? key, required this.title}) : super(key: key);

  final String title;

  [@override](/user/override)
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  [@override](/user/override)
  void initState() {
    super.initState();

    final epoch = DateTime(1970);
    final entity = Entity(name: 'foo', createdAt: ClientDateTime(epoch));
    final json = entity.toJson();

    print(json['name']); // 输出: 'foo'
    print(json['createdAt']); // 输出: Timestamp(seconds=0, nanoseconds=0)
    print(json['updatedAt']); // 输出: FieldValue(Instance of 'MethodChannelFieldValue')
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text(
              'You have pushed the button this many times:',
            ),
          ],
        ),
      ),
    );
  }
}