Flutter功能未知插件katana_model的潜在用途探索

Flutter功能未知插件katana_model的潜在用途探索

介绍

katana_model 是一个用于简化Flutter应用中数据读写的库。它提供了CRUD（创建、读取、更新、删除）操作，支持多种数据存储方式（如本地数据库、Firestore等），并且可以通过简单的接口进行切换。此外，它还提供了实时更新、事务处理、批量处理等功能，使得开发者可以更轻松地管理应用中的数据。

功能概述

• CRUD操作：支持创建、读取、更新和删除数据。
• 灵活的数据结构：数据可以是任何Map类型对象及其列表。
• 查询和过滤：支持简单的查询和过滤功能。
• 多数据库支持：可以轻松切换本地数据库、模拟数据和远程数据库（如Firestore）。
• 事务处理：支持类似Firestore的事务功能，适用于需要同步更新多个文档的场景。
• 批量处理：支持批量更新和删除操作，适合大规模数据操作。
• 特殊字段值：支持计数器和时间戳等特殊字段值。
• 引用字段：支持跨文档引用，自动加载相关数据。
• 单元测试：提供模拟数据库适配器，便于单元测试。

安装

首先，你需要安装 katana_model 包：

flutter pub add katana_model

如果你使用本地数据库或Firestore，还需要安装相应的包：

// 本地数据库
flutter pub add katana_model_local

// Firestore
flutter pub add katana_model_firestore

示例代码

以下是一个完整的示例，展示了如何使用 katana_model 创建一个简单的Flutter应用，该应用允许用户添加、查看、更新和删除数据项。

1. 创建模型类

我们首先创建两个类：ModelDocument 和 ModelCollection，分别用于表示单个文档和文档集合。

class ModelDocument extends DocumentBase<Map<String, dynamic>> {
  ModelDocument(super.modelQuery);

  @override
  Map<String, dynamic> fromMap(DynamicMap map) => map;

  @override
  DynamicMap toMap(Map<String, dynamic> value) => value;
}

class ModelCollection extends CollectionBase<ModelDocument> {
  ModelCollection(super.modelQuery);

  @override
  ModelDocument create([String? id]) {
    return ModelDocument(modelQuery.create(id));
  }
}

2. 创建主应用程序

在 main.dart 中，我们使用 ModelAdapterScope 来设置数据库适配器，并创建一个包含 ModelPage 的 MaterialApp。

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

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

  @override
  Widget build(BuildContext context) {
    return ModelAdapterScope(
      adapter: const RuntimeModelAdapter(), // 使用运行时适配器，适用于模拟数据
      child: MaterialApp(
        home: const ModelPage(),
        title: "Flutter Demo",
        theme: ThemeData(
          primarySwatch: Colors.blue,
        ),
      ),
    );
  }
}

3. 创建页面

ModelPage 是一个 StatefulWidget，它负责显示和管理数据。我们使用 FutureBuilder 来加载数据，并使用 ListView 来显示数据项。每个数据项都可以通过点击来更新，或者通过删除按钮来删除。

class ModelPage extends StatefulWidget {
  const ModelPage({super.key});

  @override
  State<StatefulWidget> createState() => ModelPageState();
}

class ModelPageState extends State<ModelPage> {
  final collection = ModelCollection(const CollectionModelQuery("/user"));

  @override
  void initState() {
    super.initState();
    collection.addListener(_handledOnUpdate); // 监听集合变化
    collection.load(); // 加载数据
  }

  void _handledOnUpdate() {
    setState(() {}); // 当数据变化时，重新绘制页面
  }

  @override
  void dispose() {
    super.dispose();
    collection.removeListener(_handledOnUpdate); // 移除监听器
    collection.dispose(); // 释放资源
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text("Flutter Demo")),
      body: FutureBuilder(
        future: collection.loading ?? Future.value(), // 等待数据加载完成
        builder: (context, snapshot) {
          if (snapshot.connectionState != ConnectionState.done) {
            return const Center(
              child: CircularProgressIndicator(), // 显示加载指示器
            );
          }
          return ListView(
            children: [
              ...collection.mapListenable((doc) { // 监听每个文档的变化
                return ListTile(
                  title: Text(doc.value?["count"].toString() ?? "0"), // 显示计数值
                  trailing: IconButton(
                    onPressed: () {
                      doc.delete(); // 删除文档
                    },
                    icon: const Icon(Icons.delete),
                  ),
                  onTap: () {
                    doc.save({
                      "count": Random().nextInt(100), // 更新计数值
                    });
                  },
                );
              }),
            ],
          );
        },
      ),
      floatingActionButton: FloatingActionButton(
        child: const Icon(Icons.add),
        onPressed: () {
          final doc = collection.create(); // 创建新文档
          doc.save({
            "count": Random().nextInt(100), // 初始化计数值
          });
        },
      ),
    );
  }
}

数据库切换

katana_model 支持多种数据库适配器，可以通过更改 ModelAdapterScope 中的适配器来切换使用的数据库。例如，你可以将运行时适配器替换为本地数据库适配器或 Firestore 适配器。

// 使用本地数据库
ModelAdapterScope(
  adapter: const LocalModelAdapter(), // 本地数据库适配器
  child: MaterialApp(
    home: const ModelPage(),
    title: "Flutter Demo",
    theme: ThemeData(
      primarySwatch: Colors.blue,
    ),
  ),
)

// 使用 Firestore 数据库
ModelAdapterScope(
  adapter: FirestoreModelAdapter(options: DefaultFirebaseOptions.currentPlatform), // Firestore 适配器
  child: MaterialApp(
    home: const ModelPage(),
    title: "Flutter Demo",
    theme: ThemeData(
      primarySwatch: Colors.blue,
    ),
  ),
)

高级用法

• 集合查询：你可以使用 CollectionModelQuery 进行条件查询，例如过滤、排序和限制结果数量。
• 文本搜索：通过混合 SearchableDocumentMixin 和 SearchableCollectionMixin，可以在集合中实现全文搜索功能。
• 事务处理：使用 transaction() 方法可以执行多个文档的原子性更新。
• 批量处理：使用 batch() 方法可以一次性更新多个文档，提高性能。
• 特殊字段值：支持计数器和时间戳等特殊字段值，适用于需要服务器端处理的场景。
• 引用字段：通过 ModelRefMixin 和 ModelRefLoaderMixin，可以实现跨文档引用，自动加载相关数据。

单元测试

为了方便单元测试，katana_model 提供了 RuntimeModelAdapter，它可以在测试中模拟数据库行为。你可以通过传递 NoSqlDatabase 和 rawData 来初始化测试数据。

test("runtimeDocumentModel.test", () async {
  final adapter = RuntimeModelAdapter(
    database: NoSqlDatabase(),
    rawData: const {
      "test/doc": {"name": "aaa", "text": "bbb"},
    },
  );
  final query = DocumentModelQuery("test/doc", adapter: adapter);
  final document = ModelDocument(query);
  await document.load();
  expect(document.value, {"name": "aaa", "text": "bbb"});
});