Flutter地图描述插件mapdescriptor的使用

Flutter 地图描述插件 mapdescriptor 的使用

特性

这是一个 MapDescriptor 插件，允许用户在给定的键值对映射（Map）中将时间戳（Timestamp）值转换为字符串，反之亦然。该插件特别适用于从 Firestore 接收数据的用户，他们需要将 ISO 8601 字符串值用于应用需求。该插件提供了四个方法：convertTimeStampToStr 和 convertStrToTimeStamp 分别处理时间戳值到字符串和字符串到时间戳的转换。containsTimeStamp 和 containsISO8601Str 分别检查映射是否包含时间戳或时间戳的字符串形式。

使用场景

该插件可以将时间戳对象转换为给定映射中的 ISO 8601 字符串。同样，该插件也可以将 ISO 8601 字符串转换为给定映射中的时间戳对象。该插件能够处理包含时间戳对象的嵌套映射。该插件设计用于与从 Firestore 检索的数据一起工作，在 Firestore 中，时间戳对象通常用于存储日期和时间信息。总体而言，该插件为 Dart 和 Firestore 中的时间戳对象提供了简单的处理方式，使开发人员更容易在他们的应用程序中处理日期和时间信息。

开始使用

使用该插件的前提条件包括：

• 创建一个使用 Flutter SDK 的 Flutter 项目。
• 将 cloud_firestore 包作为依赖项添加到项目中。
• 基本了解如何在 Flutter 中处理映射和 Firestore。

要开始使用该插件，用户只需导入 MapDescriptor 类并创建其实例。然后，用户可以使用 convertTimeStampToStr 方法将映射中的任何时间戳值转换为字符串，使用 convertStrToTimeStamp 方法将任何字符串转换回时间戳值。建议用户阅读包中提供的文档和示例以有效使用该插件。

示例代码

以下是一些使用 MapDescriptor 的示例代码：

1. 将 Firestore 文档中的时间戳转换为 ISO 8601 字符串格式

import 'package:mapdescriptor/mapdescriptor.dart';

void main() async {
  final doc = await FirebaseFirestore.instance.collection('my_collection').doc('my_doc').get();
  Map<String, dynamic> myMap = doc.data()!; // 等于：{'name': 'John Doe', 'age': 30, 'birthday': Timestamp(seconds=1560523991, nanoseconds=286000000)}
  final convertedMap = MapDescriptor().convertStrToTimeStamp(myMap);
  print(convertedMap['birthday']); // 应输出 1990-12-12T05:14:15.541Z
}

2. 将嵌套 JSON 对象中的所有时间戳转换为 ISO 8601 字符串

import 'package:mapdescriptor/mapdescriptor.dart';

void main() {
  final myMap = {
    'name': 'Sami Youssuf',
    'age': 45,
    'timestamp': Timestamp(1560523991, 286000000),
    'activities': {
      'activity1': {
        'type': 'sport',
        'start': Timestamp(1560523991, 286000000),
      },
      'activity2': {
        'type': 'Sing',
        'start': Timestamp(1560523991, 286000000),
      }
    }
  };

  final convertedMap = MapDescriptor().convertTimeStampToStr(myMap);
  print(convertedMap['timestamp']); // 应输出 ISO 8601 字符串形式的日期
  print(convertedMap['activities']['activity1']['start']); // 应输出 ISO 8601 字符串形式的日期
  print(convertedMap['activities']['activity2']['start']); // 应输出 ISO 8601 字符串形式的日期
}

3. 将嵌套 JSON 对象中的所有 ISO 8601 字符串转换为时间戳

import 'package:mapdescriptor/mapdescriptor.dart';

void main() {
  final myMap = {
    'name': 'Andrew Tate',
    'age': 30,
    'birthday': "1990-12-12T05:14:15.541Z",
    'activities': {
      'activity1': {
        'type': 'Boxing',
        'start': "1999-07-04T05:14:15.541Z",
      },
      'activity2': {
        'type': 'Netflix',
        'start': "2019-01-06T04:15:15.746Z",
      }
    }
  };

  final convertedMap = MapDescriptor().convertStrToTimeStamp(myMap);
  print(convertedMap['birthday']); // 应输出 Timestamp(seconds=1560523991, nanoseconds=286000000)
  print(convertedMap['activities']['activity1']['start']); // 应输出 Timestamp(seconds=1560523991, nanoseconds=286000000)
  print(convertedMap['activities']['activity2']['start']); // 应输出 Timestamp(seconds=1560523991, nanoseconds=286000000)
}

4. 检查映射中是否存在时间戳值

import 'package:mapdescriptor/mapdescriptor.dart';

void main() async {
  final map1 = {
    'name': 'Khalid Ibn Walid',
    'age': 70,
    'birthday': Timestamp(1560523991, 286000000),
  };
  print(MapDescriptor().containsTimeStamp(map1)); // 输出 True

  final map2 = {
    'name': 'Andrew Tate',
    'age': 30,
  };
  print(MapDescriptor().containsTimeStamp(map2)); // 输出 False
}

5. 检查映射中是否包含 ISO 8601 字符串（时间戳的字符串形式）

import 'package:mapdescriptor/mapdescriptor.dart';

void main() {
  Map<String, dynamic> myMap = {
    'name': 'Hicham Hatri',
    'age': 32,
    'birthday': "1990-12-12T12:14:40.412Z",
    "activities": {
      "sport": {
        "type": "Boxing",
        "start": "2001-11-06T12:14:40.412Z",
      },
    }
  };

  Map<String, dynamic> myMap2 = {
    'name': 'Ayoub Arabi',
    'age': 30,
    'birthday': Timestamp(12115454, 121254),
    "activities": {
      "sport": {
        "type": "Soccer",
        "start": Timestamp(12115454, 121254),
      },
    }
  };

  bool contains = MapDescriptor().containsISO8601Str(myMap); // 输出 True
  bool notContains = MapDescriptor().containsISO8601Str(myMap2); // 输出 False
}

6. 比较两个包含时间戳值的嵌套映射

在 Firestore 中，时间戳存储为时间戳对象，这些对象不能直接与其他数据类型进行比较。当比较两个包含时间戳对象的映射时，DeepCollectionEquality 类的 equals() 方法可能返回 false，即使映射具有相同的数据，因为时间戳对象不被视为相等。这就是为什么 MapDescriptor 包中的 isEqual() 方法成为一个解决方案。

import 'package:mapdescriptor/mapdescriptor.dart';

void main() {
  final map1 = {
    'name': 'John',
    'age': 30,
    'timestamp': Timestamp.fromMillisecondsSinceEpoch(1650000000000),
    'address': {
      'street': '123 Main St',
      'city': 'Anytown',
      'state': 'CA',
    },
  };

  final map2 = {
    'name': 'John',
    'age': 30,
    'timestamp': Timestamp.fromMillisecondsSinceEpoch(1650000000000),
    'address': {
      'street': '123 Main St',
      'city': 'Anytown',
      'state': 'CA',
    },
  };

  final map3 = {
    'name': 'Jane',
    'age': 25,
    'timestamp': Timestamp.fromMillisecondsSinceEpoch(1650000000000),
    'address': {
      'street': '456 Oak St',
      'city': 'Sometown',
      'state': 'NY',
    },
  };

  print(MapDescriptor().isEqual(map1, map2)); // 输出 True
  print(MapDescriptor().isEqual(map1, map3)); // 输出 False
}