Flutter性能监控与分析插件truesight_flutter的使用

引言

本README描述了truesight_flutter包。如果你将此包发布到pub.dev，此README的内容将出现在你的包的首页。

有关如何编写好的包README的信息，请参阅编写包页面指南。

有关开发包的一般信息，请参阅Dart指南创建包和Flutter指南开发包和插件。

目录

• 介绍
• 开始使用
• 安装
• 使用
• 小部件文档
• 自定义图像提供程序
• Cookie管理
• 日期和时间格式
• 附加信息

开始使用

要安装此包，请运行：

flutter pub add truesight_flutter go_router intl

依赖项

此包依赖于一些必须手动安装的库：

dependencies:
  # ...others
  carbon_icons:
    git: https://github.com/thanhtunguet/carbon-icons.git

使用

JSON序列化

该库提供了以下类：

• DataModel：表示应用程序中的实体，通常映射到后端数据库中的表。
• DataFilter：特定DataModel的过滤集。

约定：每个DataModel应该有一个对应的DataFilter。

应用程序中的实体和过滤器应该扩展这两个类。

要定义一个新类，请考虑以下示例，其中包含AppUser类：

class AppUser extends DataModel {
  @override
  List<JsonField> get fields => [
    username,
    password,
    email,
    isAdmin,
    dateOfBirth,
    age,
    level,
    manager,
    members,
  ];

  JsonString username = JsonString('username', isRequired: false, helper: '用户名');
  JsonString password = JsonString('password', isRequired: false, helper: '密码');
  JsonString email = JsonString('email', isRequired: false, helper: '电子邮件');
  JsonBoolean isAdmin = JsonBoolean('isAdmin', isRequired: false, helper: '用户是否为管理员');
  JsonDate dateOfBirth = JsonDate('dateOfBirth', isRequired: false, helper: '用户的出生日期');
  JsonInteger age = JsonInteger('age', isRequired: false, helper: '用户的年龄');
  JsonDouble level = JsonDouble('level', isRequired: false, helper: '用户的等级');
  JsonObject<AppUser> manager = JsonObject('manager', isRequired: false, helper: '用户的经理');
  JsonList<AppUser> members = JsonList<AppUser>('members', isRequired: false, helper: '用户管理的成员');
}

解释：

• fields getter：这些是从后端获取数据时自动映射的JSON字段。
• JSON数据字段由以下类表示：

JsonXYZ类继承自JsonField。

从JSON映射数据

final json = await requestFromAPI();
AppUser user = AppUser();
user.fromJSON(json);

转换为JSON

AppUser user = AppUser();
user.toJSON(); // 返回用户的一般JSON表示形式，通常是一个Dart Map对象。
user.toString(); // 返回用户作为Dart字符串的JSON表示形式。

高级过滤器

类似于JSON类，库定义了FilterField数据类型如下：

HTTP请求

存储库类执行对后端的API调用来获取数据。

每个HttpRepository类可以代表一组API，对应特定的业务逻辑，如用户登录(UserRepository)或产品管理(ProductRepository)。

HttpRepository类可以与@singleton注解一起使用，来自injectable包结合get_it进行依赖注入。

HttpRepository类中的每个方法都对应一个特定的API。

@singleton
class UserRepository extends HttpRepository {
  @override
  InterceptorsWrapper interceptorWrapper = InterceptorsWrapper();

  @override
  String? get baseUrl => 'https://app.example.com';

  Future<AppUser> login(String username, String password) {
    return post("/login", data: {
      'username': username,
      'password': password,
    })
    .then((response) => response.body<AppUser>(AppUser));
  }
}

TrueSightService

TrueSightService是一个单例类，旨在使用Hive进行本地存储和dotenv进行环境变量管理来处理应用程序范围的设置和配置管理。此服务提供了一种初始化必要配置并管理faceIdEnabled和baseApiUrl等设置的方式。

初始化

initialize

使用可选参数初始化服务以启用dotenv和Hive。

参数

• enableDotenv (bool): 如果为true，则使用flutter_dotenv包加载环境变量。默认值为true。
• enableHive (bool): 如果为true，则初始化Hive并打开用于存储的盒。默认值为true。

使用

await truesightService.initialize(
  enableDotenv: true,
  enableHive: true,
);

属性

faceIdEnabled

faceIdEnabled设置的getter和setter。此设置控制应用中是否启用Face ID。

Getter

返回一个bool指示Face ID是否已启用。如果未设置，则默认为true。

Setter

设置faceIdEnabled值。

使用

// 获取faceIdEnabled
bool isFaceIdEnabled = truesightService.faceIdEnabled;

// 设置faceIdEnabled
truesightService.faceIdEnabled = false;

baseApiUrl

baseApiUrl设置的getter和setter。此设置包含API的基本URL。如果未在Hive中设置，则从环境变量检索。

Getter

返回包含基本API URL的String。如果在Hive中未设置值，则从环境变量中检索。

Setter

设置baseApiUrl值。

使用

// 获取baseApiUrl
String apiUrl = truesightService.baseApiUrl;

// 设置baseApiUrl
truesightService.baseApiUrl = 'https://api.example.com';

私有方法

_getOrCreate

一个实用方法，从Hive检索值或使用默认值创建不存在的值。

参数

• key (String): 在Hive中的值键。
• defaultValue (dynamic): 如果键不存在，则使用的默认值。

返回

• 与键关联的值，或如果键不存在则返回默认值。

示例

以下是如何在Flutter应用程序中使用TrueSightService的示例：

import 'package:flutter/material.dart';
import 'path_to_your_service/truesight_app_service.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await truesightService.initialize();

  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: Text('Truesight App Service Example'),
        ),
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Text('Face ID Enabled: ${truesightService.faceIdEnabled}'),
              Text('Base API URL: ${truesightService.baseApiUrl}'),
              ElevatedButton(
                onPressed: () {
                  truesightService.faceIdEnabled = !truesightService.faceIdEnabled;
                },
                child: Text('切换Face ID'),
              ),
              ElevatedButton(
                onPressed: () {
                  truesightService.baseApiUrl = 'https://newapi.example.com';
                },
                child: Text('设置新的API URL'),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

自定义图像提供程序

设计了一个自定义图像提供程序，用于从服务器获取带有附加身份验证令牌的图像。

概述

TrueSightImageProvider类扩展了ImageProvider<Uri>，并修改了图像加载行为以包括从cookie中获取的身份验证令牌。

构造函数

TrueSightImageProvider(String url)

构造一个TrueSightImageProvider实例，并提供图像URL。

方法

• obtainKey(ImageConfiguration configuration): 异步获取图像的键。将身份验证令牌附加到URL的查询参数中。
• loadImage(Uri key, ImageDecoderCallback decode): 使用HTTP客户端从指定的URL加载图像，并添加身份验证头。通过块事件跟踪加载进度。

示例用法

import 'package:flutter/material.dart';

class MyImageWidget extends StatelessWidget {
  final String imageUrl = 'https://example.com/image.jpg';

  @override
  Widget build(BuildContext context) {
    final imageProvider = TrueSightImageProvider(imageUrl);

    return Image(
      image: imageProvider,
      fit: BoxFit.cover,
    );
  }
}

在这个例子中，TrueSightImageProvider被用作Image小部件的图像提供程序，确保图像被正确地带身份验证地获取。

小部件文档

• AppNavigationBar
• AppTitle
• BodyText
• CarbonButton
• ConfirmationDialog
• EllipsisText
• GoBackButton
• IconPlaceholder
• ImagePlaceholder
• SignInButton
• SimpleInfiniteList
• StatefulTextFormField

Cookie管理

在我们的应用中，Cookie被管理以高效地处理用户会话和身份验证令牌。Cookie使用SharedPreferences包进行存储，允许持久存储设备上的键值对。

概述

Cookie对于维护用户会话和处理身份验证至关重要。以下扩展方法和函数简化了应用中Cookie的存储、检索和清除。

存储Cookie

Cookie从Set-Cookie头解析出来，并带有前缀存储在SharedPreferences中。parseSetCookie函数处理此解析：

Map<String, String> parseSetCookie(String setCookieString) {
  Map<String, String> cookies = {};
  List<String> parts = setCookieString.split('; ');
  if (parts.isNotEmpty && parts[0].contains('=')) {
    List<String> keyValue = parts[0].split('=');
    if (keyValue.length == 2) {
      cookies[_getCookieKey(keyValue[0])] = keyValue[1];
    }
  }
  return cookies;
}

检索Cookie

Cookie从SharedPreferences中使用getCookies函数检索。此函数检索所有具有指定前缀的键，并构建一个Cookie的映射：

Future<Map<String, dynamic>> getCookies() async {
  final SharedPreferences prefs = await SharedPreferences.getInstance();
  final Set<String> keys = prefs.getKeys();
  final Map<String, dynamic> prefsMap = {};

  for (String key in keys) {
    if (_isCookieKey(key)) {
      prefsMap[_getCookieKeyReversed(key)] = prefs.get(key);
    }
  }

  return prefsMap;
}

清除Cookie

Cookie可以从SharedPreferences中使用clearCookies函数清除。此函数移除所有具有指定前缀的键：

Future<void> clearCookies() async {
  final SharedPreferences prefs = await SharedPreferences.getInstance();
  final Set<String> keys = prefs.getKeys();

  for (String key in keys) {
    if (_isCookieKey(key)) {
      prefs.remove(key);
    }
  }
}

Cookie扩展方法

Map<String, dynamic>上的扩展方法提供了对特定Cookie（如token和refreshToken）的便捷访问：

extension TrueSightCookies on Map<String, dynamic> {
  String? get token => this['Token'];
  String? get refreshToken => this['RefreshToken'];
  bool get hasToken => this['Token'] != null;
  bool get hasRefreshToken => this['RefreshToken'] != null;
}

这些方法简化了在应用各部分中检索和使用Cookie的过程。

示例用法

以下是应用中如何使用Cookie管理函数的示例：

// 解析并存储Set-Cookie头
String setCookieHeader = 'Token=abc123; Path=/; HttpOnly';
Map<String, String> cookies = parseSetCookie(setCookieHeader);
// 使用SharedPreferences存储解析后的Cookie
// ...

// 检索存储的Cookie
Future<void> printStoredCookies() async {
  Map<String, dynamic> cookies = await getCookies();
  print('Stored Token: ${cookies.token}');
}

// 清除存储的Cookie
Future<void> clearStoredCookies() async {
  await clearCookies();
  print('Cookies cleared');
}

通过这些函数和扩展，管理应用中的Cookie变得简单且高效。

日期和时间格式

我们的应用使用各种日期和时间格式，以确保一致性和可读性，特别是针对越南本地化。这些格式定义在DateTimeFormatsVN类中，可以在整个应用中轻松使用。

可用格式

DateTimeFormatsVN类定义了几种常见的日期和时间格式：

• 完整日期和时间：dd/MM/yyyy HH:mm:ss

  • 示例：01/01/2024 14:30:45

• 不带秒的日期和时间：dd/MM/yyyy HH:mm

  • 示例：01/01/2024 14:30

• 仅日期：dd/MM/yyyy

  • 示例：01/01/2024

• 仅时间：HH:mm:ss

  • 示例：14:30:45

• 仅天和月：dd/MM

  • 示例：01/01

• 仅年份：yyyy

  • 示例：2024

• 带有星期几的日期：EEEE, dd/MM/yyyy

  • 示例：Thứ Hai, 01/01/2024

• 带有月份名称的日期：dd MMMM yyyy

  • 示例：01 Tháng Giêng 2024

• 带有月份名称的短日期：dd MMM

  • 示例：01 Thg 01

格式化日期

DateTimeFormatsVN类包括一个辅助函数，使用指定的格式格式化DateTime对象：

static String format(DateTime dateTime, String format) {
  return DateFormat(format, 'vi').format(dateTime);
}

你可以使用此函数根据预定义的格式格式化日期。例如：

DateTime now = DateTime.now();
String formattedDate = DateTimeFormatsVN.format(now, DateTimeFormatsVN.dateTime);
print(formattedDate); // 输出：01/01/2024 14:30:45

日期扩展方法

我们还提供了一个DateTime类的扩展方法，简化了格式化过程。此方法使用默认格式但允许自定义：

extension DateTimeFormatter on DateTime {
  String format({
    String dateFormat = DateTimeFormatsVN.dateOnly,
  }) {
    return DateFormat(dateFormat).format(toLocal());
  }
}

使用扩展方法的示例：

DateTime now = DateTime.now();
String formattedDate = now.format();
print(formattedDate); // 输出：01/01/2024

String customFormattedDate = now.format(dateFormat: DateTimeFormatsVN.dateWithDayName);
print(customFormattedDate); // 输出：Thứ Hai, 01/01/2024

总结

通过使用DateTimeFormatsVN类和DateTimeFormatter扩展，你可以轻松地在应用中格式化日期和时间，确保一致性并为越南用户提供本地化支持。

附加信息

此包正在开发中。如有问题请随时提出。