Flutter数据映射插件dart_mappable的使用

dart_mappable 是一个用于 Dart 和 Flutter 的数据映射库，它简化了 JSON 序列化和反序列化的过程，并提供了对泛型、继承、多态等复杂用例的支持。本文将详细介绍如何在 Flutter 项目中使用 dart_mappable，并提供一个完整的示例。

快速开始

添加依赖

首先，在你的 pubspec.yaml 文件中添加 dart_mappable 作为依赖项，并添加 build_runner 和 dart_mappable_builder 作为开发依赖项：

dependencies:
  dart_mappable: ^latest_version

dev_dependencies:
  build_runner: ^latest_version
  dart_mappable_builder: ^latest_version

然后运行以下命令来安装这些包：

flutter pub add dart_mappable
flutter pub add build_runner --dev
flutter pub add dart_mappable_builder --dev

定义模型类

接下来，创建一个 Dart 文件（例如 model.dart），并在其中定义你要使用的模型类。使用 @MappableClass() 注解这些类，并添加适当的 part 指令以包含生成的 .mapper.dart 文件。

// model.dart
import 'package:dart_mappable/dart_mappable.dart';

part 'model.mapper.dart';

@MappableClass()
class Person with PersonMappable {
  final String name;
  final int age;
  final Car? car;

  Person(this.name, {this.age = 18, this.car});
}

@MappableEnum()
enum Brand { Toyota, Audi, BMW }

@MappableClass()
class Car with CarMappable {
  final double miles;
  final Brand brand;

  const Car(this.miles, this.brand);
}

生成代码

为了生成序列化代码，运行以下命令：

dart pub run build_runner build

如果你在开发过程中频繁修改模型类，可以使用 watch 命令自动监视更改：

dart pub run build_runner watch

使用生成的映射器

最后一步是使用生成的映射器进行序列化和反序列化操作。以下是几个常见的用法示例：

void main() {
  // 解码 JSON 字符串
  String json = '{"name": "Max", "car": {"miles": 1000, "brand": "Audi"}}';
  Person person = PersonMapper.fromJson(json);

  // 使用 toString()
  print(person); // Person(name: Max, age: 18, car: Car(miles: 1000.0, brand: Brand.Audi))

  // 创建副本
  Person person2 = person.copyWith(name: 'Anna', age: 20);
  print(person2); // Person(name: Anna, age: 20, car: ...)

  // 编码为 Map
  Map<String, dynamic> map = person.toMap();
  print(map); // {name: Max, age: 18, car: {miles: 1000, brand: Audi}}

  // 从 Map 解码
  Person person3 = PersonMapper.fromMap(map);
  print(person3); // Person(name: Max, age: 18, car: ...)

  // 检查相等性
  print(person3 == person); // true

  // 直接转换为 JSON 字符串
  print(person3.toJson()); // '{"name":"Max","age":18,"car":{"miles":1000,"brand":"Audi"}}'

  // 确保 Confetti 可以被序列化
  ConfettiMapper.ensureInitialized();

  // 使用泛型对象
  var box = Box<Confetti>(10, content: Confetti('Rainbow'));
  String boxJson = box.toJson();
  print(boxJson); // {"size":10,"content":{"color":"Rainbow"}}

  // ... 在其他地方
  dynamic whatAmI = BoxMapper.fromJson<Confetti>(boxJson);
  print(whatAmI.runtimeType); // Box<Confetti>

  // 也适用于列表和集合
  List<int> numbers = MapperContainer.globals.fromJson('[2, 4, 105]');
  print(numbers); // [2, 4, 105]
}

示例代码

下面是一个完整的示例代码，展示了如何使用 dart_mappable 进行数据映射：

import 'package:dart_mappable/dart_mappable.dart';

part 'main.mapper.dart';

@MappableClass()
class Person with PersonMappable {
  final String name;
  final int age;
  final Car? car;

  Person(this.name, {this.age = 18, this.car});
}

@MappableEnum()
enum Brand { Toyota, Audi, BMW }

@MappableClass()
class Car with CarMappable {
  final double miles;
  final Brand brand;

  const Car(this.miles, this.brand);
}

@MappableClass()
class Box<T> with BoxMappable<T> {
  int size;
  T content;

  Box(this.size, {required this.content});
}

@MappableClass()
class Confetti with ConfettiMappable {
  String color;
  Confetti(this.color);
}

void main() {
  // 解码 JSON 字符串
  String json = '{"name": "Max", "car": {"miles": 1000, "brand": "Audi"}}';
  Person person = PersonMapper.fromJson(json);

  // 使用 toString()
  print(person);
  // Person(name: Max, age: 18, car: Car(miles: 1000.0, brand: Brand.Audi))

  // 创建副本
  Person person2 = person.copyWith(name: 'Anna', age: 20);
  print(person2); // Person(name: Anna, age: 20, car: ...

  // 编码为 Map
  Map<String, dynamic> map = person.toMap();
  print(map); // {name: Max, age: 18, car: {miles: 1000, brand: Audi}}

  // 从 Map 解码
  Person person3 = PersonMapper.fromMap(map);
  print(person3); // Person(name: Max, age: 18, car: ...

  // 检查相等性
  print(person3 == person); // true

  // 直接转换为 JSON 字符串
  print(person3.toJson()); // '{"name":"Max","age":18,"car":{"miles":1000,"brand":"Audi"}}'

  // 确保 Confetti 可以被序列化
  ConfettiMapper.ensureInitialized();

  // 使用泛型对象
  var box = Box<Confetti>(10, content: Confetti('Rainbow'));
  String boxJson = box.toJson();
  print(boxJson); // {"size":10,"content":{"color":"Rainbow"}}

  // ... 在其他地方
  dynamic whatAmI = BoxMapper.fromJson<Confetti>(boxJson);
  print(whatAmI.runtimeType); // Box<Confetti>

  // 也适用于列表和集合
  List<int> numbers = MapperContainer.globals.fromJson('[2, 4, 105]');
  print(numbers); // [2, 4, 105]
}

通过以上步骤和示例代码，你应该能够在 Flutter 项目中成功使用 dart_mappable 进行数据映射。更多详细信息和高级用法，请参考 官方文档。