Flutter插件soar_quest的介绍与使用

Flutter插件soar_quest的介绍与使用

Soar Quest 是一个基于 Flutter 的框架，旨在帮助开发者更快地构建 Telegram 小程序（Mini Apps）。通过抽象许多传统开发中常见的问题，它允许开发者专注于为用户提供价值。尽管如此，开发者仍然可以完全利用 Flutter 的强大功能。

功能概览

Soar Quest 提供了一系列的功能和组件：

• 应用构建器: SQApp
• 认证系统: 包括个人资料页面和登录页面
• 数据库: 集合（表）和文档（行）
• 用于显示集合和文档的屏幕
• 数据操作动作
• 用户设置
• 文件存储系统

这些功能将在以下部分中简要描述。

安装

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

dependencies:
  flutter:
    sdk: flutter
  soar_quest: ^0.8.0

然后运行 flutter pub get 来安装依赖。

QR 码扫描设置

如果需要启用 QR 码扫描功能，请参考 mobile_scanner 的平台特定设置说明。

使用 SQApp 构建应用

SQApp 是应用的根组件。以下代码展示了如何用 Soar Quest 创建第一个小程序应用：

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

void main() async {
  // 初始化应用
  await SQApp.init("My Cool App");

  // 启动应用并定义初始屏幕
  SQApp.run([
    Screen("Hello World"),
    Screen("Second Screen"),
  ]);
}

设计小程序

Soar Quest 自动捕获用户的自定义主题参数，并根据 Material Design 3 调整主题。

用户数据字段

可以通过 userDocFields 参数包含自定义用户数据字段：

await SQApp.init("My Cool App",
      userDocFields: [SQStringField("Telegram Handle")]);

用户设置

用户设置用于配置应用程序的本地数据，例如深色模式与浅色模式。设置屏幕会自动出现在抽屉中（如果启用了抽屉）：

await UserSettings.setSettings([
  SQBoolField("Enable feature X")
]);

SQApp.run([
  CollectionScreen(collection: testCollection),
], drawer: SQDrawer([]));

数据：集合、文档和字段

Soar Quest 中的数据模型类似于 Google 表格或 SQL 数据库：

• 集合: 类似于表格
• 文档: 类似于行
• 字段: 类似于列单元格

每个集合都有描述其文档数据的一组字段。

SQCollection

Soar Quest 提供了多种类型的集合，存储位置不同但行为相同：

• LocalCollection: 本地存储
• InMemoryCollection: 内存存储

CollectionSlice

CollectionSlice 方法可以从集合中过滤文档，并作为 SQCollection 使用：

CollectionSlice slice =
      CollectionSlice(testCollection, filter: ValueFilter("Status", "Done"));

SQApp.run([CollectionScreen(collection: slice)]);

文档条件和字段

SQDoc

每个应用的信息都包含在一个文档中，文档具有包含值的字段。

字段类型

Soar Quest 提供了许多字段类型：

• SQStringField: 文本
• SQBoolField: 布尔值（真/假）
• SQIntField: 整数
• SQDoubleField: 浮点数
• SQRefField: 指向另一个文档的引用
• SQInverseRefsField: 自动生成的引用此文档的文档列表
• SQTimestampField: 日期
• SQTimeOfDayField: 时间
• SQFileField: 存储文件
• SQImageField: 存储图像

屏幕

屏幕默认包含 AppBar 和底部 NavBar。

自定义屏幕

以下代码展示如何创建自定义屏幕。在 screenBody 方法中实现自定义逻辑：

class MyCustomScreen extends Screen {
  const MyCustomScreen(String title, {Key? key}) : super(title, key: key);

  @override
  State<MyCustomScreen> createState() => _MyCustomScreenState();
}

class _MyCustomScreenState extends ScreenState<MyCustomScreen> {
  @override
  Widget screenBody(BuildContext context) {
    // 实现自定义屏幕主体
    return super.screenBody(context);
  }
}

集合屏幕

预构建的屏幕用于显示集合中的文档：

• CollectionScreen: 默认文档列表屏幕
• GalleryScreen: 网格视图屏幕（每行 2 个）
• TableScreen: 以表格形式显示文档字段和值

示例代码：

SQApp.run([
  CollectionScreen(collection: testCollection),
  GalleryScreen(collection: testCollection),
  TableScreen(collection: testCollection),
]);

自定义 CollectionScreen

创建自定义 CollectionScreen：

class MyCustomCollectionScreen extends CollectionScreen {
  MyCustomCollectionScreen({super.title, required super.collection, super.key});

  @override
  State<MyCustomCollectionScreen> createState() =>
      _MyCustomCollectionScreenState();
}

class _MyCustomCollectionScreenState
    extends CollectionScreenState<MyCustomCollectionScreen> {
  @override
  Widget screenBody(BuildContext context) {
    // 实现自定义 CollectionScreen 主体
    return super.screenBody(context);
  }
}

DocScreen

显示单个文档的字段：

class MyCustomDocScreen extends DocScreen {
  MyCustomDocScreen(super.doc, {super.key});

  @override
  State<MyCustomDocScreen> createState() => _MyCustomDocScreenState();
}

class _MyCustomDocScreenState extends DocScreenState<MyCustomDocScreen> {
  @override
  Widget screenBody(BuildContext context) {
    // 实现自定义 DocScreen 主体
    return super.screenBody(context);
  }
}

FormScreen

用于编辑文档字段的屏幕：

FormScreen(doc: myDoc);

动作

动作是对数据（文档）的操作。可以在创建 SQCollection 时分配动作。

示例动作

• SetFieldsAction: 设置字段值
• GoScreenAction: 跳转到其他屏幕
• CreateDocAction: 创建新文档
• OpenUrlAction: 打开 URL
• CustomAction: 自定义动作

示例代码：

late SQCollection simpleCollection;

simpleCollection = LocalCollection(
  id: "Simple Collection",
  fields: [
    SQStringField("Name"),
    SQBoolField("Magic"),
    SQStringField("Status", value: "To-Do"),
    SQIntField("Points"),
  ],
  actions: [
    SetFieldsAction(
      "Mark as Done",
      getFields: (doc) => {
        "Status": "Done",
        "Points": (doc.value<int>("Points") ?? 0) + 1,
      },
    ),
    CreateDocAction(
      "Create Magic Doc",
      getCollection: () => simpleCollection,
      initialFields: (doc) => [
        SQStringField("Name", value: "Magic Doc"),
        SQBoolField("Magic", value: true),
        SQIntField("Points", value: 99),
      ],
    ),
    CustomAction(
      "Do Maths",
      customExecute: (doc, context) async {
        int x = doc.value<int>("Points") ?? 0;
        int y = x + 5;
        print("Magic number: $y");
      },
    ),
    CustomAction(
      "print hi",
      customExecute: (doc, context) async => print("hi"),
    ),
  ],
);