Flutter 插件flamingo的使用_Flamingo 是一个基于 Firebase Firestore 的模型框架库

简介

Flamingo 是一个基于 Firebase Firestore 的模型框架库。它简化了与 Firestore 交互的过程，并提供了多种实用功能如 CRUD 操作、分页、事务处理等。

Flamingo GitHub

安装

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

dependencies:
  flamingo:
  flamingo_annotation:

dev_dependencies:
  build_runner:
  flamingo_generator:

设置

请参考 cloud_firestore 设置文档进行初始设置。

使用

初始化

在 main.dart 中添加初始化代码：

import 'package:flamingo/flamingo.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Flamingo.initializeApp();
  runApp(MyApp());
}

创建模型

创建继承自 Document 的类，并实现 JSON 映射代码。可以使用 flamingo_generator 自动生成映射代码。

import 'package:flamingo/flamingo.dart';
import 'package:flamingo_annotation/flamingo_annotation.dart';

part 'user.flamingo.dart';

class User extends Document<User> {
  User({
    String? id,
    DocumentSnapshot<Map<String, dynamic>>? snapshot,
    Map<String, dynamic>? values,
  }) : super(id: id, snapshot: snapshot, values: values);

  @Field()
  String? name;

  @override
  Map<String, dynamic> toData() => _$toData(this);

  @override
  void fromData(Map<String, dynamic> data) => _$fromData(this, data);
}

执行以下命令生成数据映射代码：

flutter pub run build_runner build

CRUD 操作

使用 DocumentAccessor 或 Batch 或 Transaction 进行 CRUD 操作。

final user = User()
      ..name = 'hoge';

final documentAccessor = DocumentAccessor();

// 保存
await documentAccessor.save(user);

// 更新
await documentAccessor.update(user);

// 删除
await documentAccessor.delete(user);

// 批量操作
final batch = Batch()
  ..save(user)
  ..update(user);
  ..delete(user);
await batch.commit();

分页查询

使用 CollectionPaging 和 CollectionPagingListener 实现分页和监听功能。

final collectionPaging = CollectionPaging<User>(
  query: User().collectionRef.orderBy('createdAt', descending: true),
  limit: 20,
  decode: (snap) => User(snapshot: snap),
);

// 加载
List<User> items = await collectionPaging.load();

// 加载更多
final _items = await collectionPaging.loadMore();
items.addAll(_items);

快照监听

监听文档快照的变化。

// 监听
final user = User(id: '0')
  ..name = 'hoge';

final dispose = user.reference.snapshots().listen((snap) {
  final user = User(snapshot: snap);
  print('${user.id}, ${user.name}');
});

// 保存、更新、删除
DocumentAccessor documentAccessor = DocumentAccessor();
await documentAccessor.save(user);

user.name = 'fuga';
await documentAccessor.update(user);

await documentAccessor.delete(user);

await dispose.cancel();

子集合

示例：排名文档具有计数子集合。

// 排名模型
class Ranking extends Document<Ranking> {
  Ranking(
      {String? id,
      DocumentSnapshot<Map<String, dynamic>>? snapshot,
      Map<String, dynamic>? values,
      CollectionReference<Map<String, dynamic>>? collectionRef})
      : super(
            id: id,
            snapshot: snapshot,
            values: values,
            collectionRef: collectionRef) {
    count = Collection(this, RankingKey.count.value);
  }

  @Field()
  String? title;

  @SubCollection()
  late Collection<Count> count;

  @override
  Map<String, dynamic> toData() => _$toData(this);

  @override
  void fromData(Map<String, dynamic> data) => _$fromData(this, data);
}

// 计数模型
class Count extends Document<Count> {
  Count({
    String? id,
    DocumentSnapshot<Map<String, dynamic>>? snapshot,
    Map<String, dynamic>? values,
    CollectionReference<Map<String, dynamic>>? collectionRef,
  }) : super(
            id: id,
            snapshot: snapshot,
            values: values,
            collectionRef: collectionRef);

  @Field()
  String? userId;

  @Field()
  int count = 0;

  @override
  Map<String, dynamic> toData() => _$toData(this);

  @override
  void fromData(Map<String, dynamic> data) => _$fromData(this, data);
}

保存和获取子集合

final ranking = Ranking(id: '20201007')
  ..title = 'userRanking';

// 保存子集合
final countA = Count(collectionRef: ranking.count.ref)
  ..userId = '0'
  ..count = 10;
final countB = Count(collectionRef: ranking.count.ref)
  ..userId = '1'
  ..count = 100;
final batch = Batch()
  ..save(ranking)
  ..save(countA)
  ..save(countB);
await batch.commit();

// 获取子集合
final path = ranking.count.ref.path;
final snapshot = await firestoreInstance.collection(path).get();
final list = snapshot.docs.map((item) => Count(snapshot: item)).toList()
  ..forEach((count) {
    print(count);
  });

文件操作

可以对 Firebase Storage 进行文件上传和删除操作。

final post = Post();
final storage = Storage();
final file = ... // 加载图片。

// 获取上传器流
storage.fetch();

// 检查状态
storage.uploader.listen((data){
  print('total: ${data.totalBytes} transferred: ${data.bytesTransferred}');
});

// 上传文件到 Firebase Storage 并保存文件元数据到 Firestore
final path = '${post.documentPath}/${PostKey.file.value}';
post.file = await storage.save(path, file, mimeType: mimeTypePng, metadata: {'newPost': 'true'});
await documentAccessor.save(post);

// 处理上传器流
storage.dispose();

增量操作

示例：信用卡文档具有积分和分数字段，这些字段是增量类型。

class CreditCard extends Document<CreditCard> {
  CreditCard({
    String? id,
    DocumentSnapshot<Map<String, dynamic>>? snapshot,
    Map<String, dynamic>? values,
  }) : super(id: id, snapshot: snapshot, values: values);

  @Field()
  Increment<int> point = Increment<int>();

  @Field()
  Increment<double> score = Increment<double>();

  @override
  Map<String, dynamic> toData() => _$toData(this);

  @override
  void fromData(Map<String, dynamic> data) => _$fromData(this, data);

  /// 在创建、更新、删除后调用。
  @override
  void onCompleted(ExecuteType executeType) {
    point = point.onRefresh();
    score = score.onRefresh();
  }
}

增量和递减数据

// 增量
final card = CreditCard()
  ..point.incrementValue = 1
  ..score.incrementValue = 1.25;
await documentAccessor.save(card);
print('point ${card.point.value}, score: ${card.score.value}'); // point 1, score 1.25

// 递减
card
  ..point.incrementValue = -1
  ..score.incrementValue = -1.00;
await documentAccessor.update(card);
print('point ${card.point.value}, score: ${card.score.value}'); // point 0, score 0.25

示例 Demo

以下是一个简单的 Flutter 应用示例，展示了如何使用 Flamingo 进行基本操作：

import 'package:flutter/material.dart';
import 'package:flamingo/flamingo.dart';
import 'package:flamingo_example/firebase_options.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Flamingo.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Flamingo Example')),
        body: Center(
          child: ElevatedButton(
            onPressed: () async {
              final user = User()..name = 'John Doe';
              final documentAccessor = DocumentAccessor();
              await documentAccessor.save(user);
              print('User saved with ID: ${user.id}');
            },
            child: Text('Save User'),
          ),
        ),
      ),
    );
  }
}

以上示例展示了如何使用 Flamingo 保存用户信息到 Firestore 数据库中。通过这种方式，您可以轻松地扩展应用以支持更多复杂的功能。