json_serializable 3.3.0

  • Readme
  • Changelog
  • Example
  • Installing
  • 99

Pub Package

提供用于处理JSON的Dart构建系统构建器.

当构建者找到使用package:json_annotation中定义的类进行注释的成员时,它们将生成代码.

  • 要为类生成与JSON代码之间的关系,请使用@JsonSerializable对其进行@JsonSerializable . 您可以向JsonSerializable提供参数以配置生成的代码. 您还可以通过使用@JsonKey注释各个字段并提供自定义参数来定制各个字段. 有关注释值的详细信息,请参见下表.

  • 要使用包含JSON的文件的内容生成Dart字段,请使用JsonLiteral批注.

要为您的项目配置json_serializable的最新发行版,请参见示例 .

Example #

给定一个example.dart库,其中包含一个用@JsonSerializable()注释的Person类:

import 'package:json_annotation/json_annotation.dart';

part 'example.g.dart';

@JsonSerializable(nullable: false)
class Person {
  final String firstName;
  final String lastName;
  final DateTime dateOfBirth;
  Person({this.firstName, this.lastName, this.dateOfBirth});
  factory Person.fromJson(Map<String, dynamic> json) => _$PersonFromJson(json);
  Map<String, dynamic> toJson() => _$PersonToJson(this);
}

建筑会创建相应的零件example.g.dart

part of 'example.dart';

Person _$PersonFromJson(Map<String, dynamic> json) {
  return Person(
    firstName: json['firstName'] as String,
    lastName: json['lastName'] as String,
    dateOfBirth: DateTime.parse(json['dateOfBirth'] as String),
  );
}

Map<String, dynamic> _$PersonToJson(Person instance) => <String, dynamic>{
      'firstName': instance.firstName,
      'lastName': instance.lastName,
      'dateOfBirth': instance.dateOfBirth.toIso8601String(),
    };

Annotation values #

使用此包的唯一注释是@JsonSerializable . 当应用于一个类(在正确配置的包中)时,在构建时将生成toJsonfromJson代码. 有三种方法可以控制代码的生成方式:

  1. @JsonSerializable上设置属性.
  2. @JsonKey批注添加到字段中并在此处设置属性.
  3. 将配置添加到build.yaml参见下文 .
build.yaml keyJsonSerializableJsonKey
any_mapJsonSerializable.anyMap
checkedJsonSerializable.checked
create_factoryJsonSerializable.createFactory
create_to_jsonJsonSerializable.createToJson
disallow_unrecognized_keysJsonSerializable.disallowUnrecognizedKeys
explicit_to_jsonJsonSerializable.explicitToJson
field_renameJsonSerializable.fieldRename
ignore_unannotatedJsonSerializable.ignoreUnannotated
include_if_nullJsonSerializable.includeIfNullJsonKey.includeIfNull
nullableJsonSerializable.nullableJsonKey.nullable
JsonKey.defaultValue
JsonKey.disallowNullValue
JsonKey.fromJson
JsonKey.ignore
JsonKey.name
JsonKey.required
JsonKey.toJson
JsonKey.unknownEnumValue

注意:每个JsonSerializable字段都可以通过build.yaml配置–参见表以获取相应的密钥. 如果发现希望所有或大多数类都具有相同的配置,则在YAML文件中一次指定值可能会更容易. 在@JsonSerializable显式设置的值优先于build.yaml设置.

注意: JsonKeyJsonSerializable上的字段之间有些重叠. 在这些情况下,如果通过JsonKey显式设置了一个值,则它将优先于JsonSerializable设置的任何值.

Build configuration #

除了在关联的注释类上设置参数外,还可以通过在build.yaml设置值来配置代码生成.

targets:
  $default:
    builders:
      json_serializable:
        options:
          # Options configure how source code is generated for every
          # `@JsonSerializable`-annotated class in the package.
          #
          # The default value for each is listed.
          any_map: false
          checked: false
          create_factory: true
          create_to_json: true
          disallow_unrecognized_keys: false
          explicit_to_json: false
          field_rename: none
          ignore_unannotated: false
          include_if_null: true
          nullable: true

3.3.0 #

  • 添加对带字段注释的JsonKey子类的JsonKey .
  • package:json_serializable/type_helper.dart导出以下TypeHelper实现和接口:
    • DurationHelper
    • TypeHelperContextWithConfig

3.2.5 #

  • 修复影响pub.dev得分的棉绒.

3.2.4 #

  • Require package:analyzer ^0.39.0.

3.2.3 #

  • 分析仪0.38.5的错误修复.

3.2.2 #

  • 在属性JsonConverter上支持JsonConverter批注

3.2.1 #

  • Support package:analyzer >=0.33.3 <0.39.0

3.2.0 #

  • Require package:json_annotation ^3.0.0.
  • 添加了对JsonSerializable.ignoreUnannotated支持.
  • 添加了对JsonKey.unknownEnumValue支持.
  • enum支持代码的生成方式enum更改.
  • 至少需要Dart 2.3.0 .

3.1.0 #

  • 支持类型为intBigIntDateTimeUri Map键.
  • 现在,尾随逗号已添加到生成的构造函数参数和Map文字中的元素.
  • Support package:analyzer >=0.33.3 <0.38.0

3.0.0 #

此版本完全是BREAKING更改. 它删除了未充分使用的功能,这些功能为该程序包增加了不成比例的复杂性. 此清理将简化将来的功能工作.

  • 删除了对JsonSerializable.useWrappers支持.
  • 删除了对JsonSerializable.generateToJsonFunction支持.
  • 删除了对encodeEmptyCollection支持.
  • 如果字段定义了转换函数( JsonKey.toJson或自定义JsonConverter批注),即使nullable显式设置为false ,也不要截获null值. 这使这些函数可以提供null替代值(例如,空集合),从而替代encodeEmptyCollection提供的功能.
    • 注意:这是无声的. 此更改没有相应的弃用. 如果您使用转换器,请确保测试您的代码!

2.3.0 #

  • 添加了pascal作为附加的fieldRename选项.

2.2.3 #

  • 由于package:analyzer更改,删除了对未定义类型的特殊处理. 这些类型现在被视为dynamic类型.

2.2.2 #

  • 至少需要Dart 2.2.0 .
  • Allow build_config 0.4.x.

2.2.1 #

  • 修复了在mixin定义属性/字段时的错误.

2.2.0 #

  • 如果字段定义了转换函数( JsonKey.toJson或自定义JsonConverter批注),则处理该函数返回nullnullableincludeIfNull均为false .

2.1.2 #

  • Support package:json_annotation >=2.1.0 <2.3.0.

2.1.1 #

  • Support package:analyzer >=0.33.3 <0.37.0

2.1.0 #

  • 至少需要Dart 2.1.1 .

  • 增加了支持encodeEmptyCollectionJsonKeyJsonSerializable .

  • Added support for BigInt.

  • Added BigIntTypeHelper to type_helper.dart library.

  • 如果构建器配置不正确,请提供更有用的错误.

2.0.3 #

  • 在字段类型上调用fromJson构造函数时,生成一个从构造函数参数类型派生的转换表达式.

  • 对受支持的ListSetMap类型更加严格. 在以前生成无效代码的情况下,这可能会引起错误. 它还允许这些类型的实现添加fromJson构造函数以支持自定义解码.

  • 格式化生成的代码时,对转换后的地图周围的空白进行很小的更改可以改善非常慢的路径.

2.0.2 #

  • JsonKey.defaultValue与其他字段JsonKey.defaultValue设置时,记录警告.

    • 使用toJson :使用nullable: false而不是defaultValue .
    • disallowNullValuerequired设置为true .
  • 解码Set类型的字段时,避免无操作调用map .

  • Support package:analyzer >=0.33.3 <0.36.0

2.0.1 #

  • Support package:analyzer v0.34.0.

2.0.0 #

  • 支持所有build.yaml加入了许多领域对类配置选项JsonSerializableanyMapcheckedexplicitToJsongenerateToJsonFunctionuseWrappers .

  • 支持dart:core解码/编码dart:core Duration

  • 为使用JsonConverter实例注释的字段和类生成的代码现在可以正确处理可为空的字段.

  • 构建配置

    • 您现在可以配置由暴露的所有设置JsonSerializable内注释build.yaml .

    • BREAKING build.yaml定义的不受支持的选项将导致异常,而不是被记录和忽略.

  • json_serializable.dart

    • BREAKING JsonSerializableGenerator现在公开一个config类型的财产JsonSerializable而不是个别属性的checkedanyMay等,这将影响到任何人创建,或通过代码使用这个类.
  • type_helper.dart

    • BREAKING SerializeContextDeserializeContext已被新的TypeHelperContext类替换.

    • TypeHelper现在具有一个类型参数,允许实现TypeHelperContext为调用serializedeserialize serialize指定TypeHelperContext的特定实现. 许多包含的TypeHelper实现已更新,表明它们希望从源生成器获取更多信息.

1.5.1 #

  • 支持最新的package:analyzer .

1.5.0 #

  • 添加了对字段上JsonConvert批注的支持.

1.4.0 #

  • type_helper.dart

    • TypeHelper serializedeserialize serialize具有返回类型Object而不是String . 这允许实例之间进行协调以支持更多高级功能,例如使用新的LambdaResult类避免创建不必要的lambda. 创建TypeHelper实现时,通过对无法识别的值调用toString()来处理非String结果.
  • 声明对package:build版本1.xx .

1.3.0 #

  • 添加对使用从package:json_annotation扩展JsonConverter类注释的类型的支持.

  • package:json_serializable/type_helper.dart导出以下TypeHelper实现: ConvertHelperEnumHelperIterableHelperJsonConverterHelperMapHelperValueHelper

  • 添加了对Set类型作为目标的支持.

1.2.1 #

  • 为使用checked: true配置生成的地图添加了返回const .

1.2.0 #

  • 现在,对于某些类的构造函数错误,抛出InvalidGenerationSourceError而不是UnsupportedError .

  • JsonKey上支持toJsonfromJson类静态函数.

  • 提供有关仅被忽略的setter属性的警告,而不是崩溃.

  • 为使用disallowUnrecognizedKeysrequireddisallowNullValue生成的列表添加了const返回.

  • 修复了启用disallowUnrecognizedKeys时的错误.

  • 修复了处理继承属性时的许多问题.

1.1.0 #

  • 添加了对自动将字段名称转换为snake_case kebab-casesnake_case JSON映射键的支持,并在JsonSerializable批注中添加了新选项.

1.0.1 #

  • 不再显式newconst .

1.0.0 #

  • 打破了由默认情况下,生成的支持代码toJson现在创建一个顶级函数,而不是混入. 现在generate_to_json_function的默认值为true . 要选择退出此更改,请将generate_to_json_function设置为false .

  • 现在支持使用JsonValue更改枚举的序列化值.

    enum AutoApply {
      none,
      dependents,
      @JsonValue('all_packages')
      allPackages,
      @JsonValue('root_package')
      rootPackage
    }
    
  • JsonSerializableGenerator.generateForAnnotatedElement现在返回Iterable<String>而不是String .

  • SerializeContextDeserializeContext现在具有addMember函数,该函数允许TypeHelper实例在处理字段时添加其他成员. 例如,这对于生成共享帮助程序很有用.

  • BREAKING不再支持header选项,必须将其从build.yaml删除.

  • 如果使用手动生成脚本json_serializable建设者必须切换到hideOutput: truecombiningBuildersource_gen必须包括以下这建设者. 在pub run build_runnerwebdev使用生成的生成脚本时,将自动处理该脚本.

0.5.8+1 #

  • 支持Dart 2.0稳定版本.

0.5.8 #

  • 支持Dart 2运行时语义的小补丁.

  • 如果平台特定的库(例如Flutter)使用自定义转换功能,则它们支持序列化类型.

0.5.7 #

  • 添加了对JsonKey.required支持.

    • 如果为true ,则如果用于填充带注释的字段的JSON映射中不存在键,则生成的代码将引发MissingRequiredKeysException .
    • 将被捕获并包裹在CheckedFromJsonException如果checked中被启用json_serializable .
  • Added JsonKey.disallowNullValue.

    • true ,如果JSON映射中存在相应的键,则生成的代码将引发DisallowedNullValueException ,但其值为null.
    • 将被捕获并包裹在CheckedFromJsonException如果checked中被启用json_serializable .
  • 添加了对Uri转换的支持.

  • JsonSerializableGenerator.withDefaultHelpers构造函数添加了丢失的checked参数.

  • 添加了explicit_to_json配置选项.

    • 有关详细信息,请参见JsonSerializableGenerator.explicitToJson .
  • 添加了generate_to_json_function配置选项.

    • 有关详细信息,请参见JsonSerializableGenerator.generateToJsonFunction .

0.5.6 #

  • 添加了对JsonSerializable.disallowUnrecognizedKeys支持.
    • 如果它在用于填充带注释的字段的JSON映射中找到无法识别的键,则抛出UnrecognizedKeysException .
    • 将被捕获并包裹在CheckedFromJsonException如果checked中被启用json_serializable .
  • All fromJson constructors now use block syntax instead of fat arrows.

0.5.5 #

  • 添加了对JsonKey.defaultValue支持.

  • enum反序列化现在使用json_annotation提供的json_annotation .

  • 对可为空的Map值进行反序列化的方式稍有更改.

  • JsonLiteral生成进行小的空白更改以与dartfmt保持一致.

  • 改进对嵌套类型中toJsonfromJson检测.

0.5.4+1 #

  • 修复了在某些情况下枚举值嵌套在集合中的情况下在0.5.4中引入的错误.

0.5.4 #

  • 添加checked配置选项. 如果为true ,则fromJson函数生成的fromJson包括额外的检查,以验证类型的正确反序列化.

  • 在配置中添加了any_map . 允许fromJson代码支持不是显式Map<String, dynaimc>动态Map实例.

  • 添加了对带有类型参数的类的支持.

  • 使用Map.map进行更多地图转换. 简化了生成的代码,并修复了Map键类型为dynamicObject时的细微问题.

0.5.3 #

  • 需要最新版本的package:analyzer - v0.32.0 .

  • 如果JsonKey.fromJson函数参数为IterableMap的类型参数为dynamicObject ,则在生成JsonKey.fromJson类型转换时忽略这些参数. _myHelper(json['key'] as Map)而不是_myHelper(json['key'] as Map<dynamic, dynamic>) .

  • JsonKey.fromJson / .toJson现在支持带有可选参数的函数.

0.5.2 #

  • 如果设置了JsonKey.fromJson / toJson ,请在任何自定义或默认TypeHelper实例之前应用它们. 通过抢占现有的DateTime TypeHelper ,这允许自定义DateTime解析.

0.5.1 #

  • JsonKey上支持fromJsontoJson字段中的新字段.

  • 使用package:build公开的log . 这要求最终用户至少具有package:build_runner ^0.8.2 .

  • 将最小package:source_gen依赖性更新为0.8.1 ,其中包括改进的错误消息.

0.5.0 #

  • BREAKINGbuild_runner配置中删除了对require_library_directive / requireLibraryDirective弃用支持.

  • BREAKING删除了不推荐使用的generators.dart库.

  • BREAKING从公共API中删除了jsonPartBuilder函数.

  • 支持最新的package:source_gen .

  • 现在,使用@JsonKey(ignore: true)生成序列化和反序列化代码时,将排除私有字段和忽略字段.

  • Throw an exception if a private field or an ignored field is referenced by a required constructor argument.

  • 字符串文字的更全面的转义.

package:json_serializable/type_helper.dart #

  • 中断 TypeHelper.serialize.deserialize上的nullable参数已被删除. 现在,它在SerializeContextDeserializeContext抽象类中作为只读属性公开.

  • 可能破坏metadata的属性SerializeContextDeserializeContext现在是只读的. 这可能会破坏扩展这些类的代码-这是不期望的.

0.4.0 #

  • 现在,在生成序列化和反序列化代码时,将处理和使用潜在破坏继承字段. 对于v0.3注释的类,生成的代码可能会以不希望的方式更改.

  • 避免在字符串转义符中使用不必要的括号.

  • 生成代码时使用单引号.

0.3.2 #

  • 现在require_library_directive选项默认为false . 该选项将在0.4.0完全删除.

0.3.1+2 #

  • 支持最新版本的analyzer软件包.

0.3.1+1 #

  • 扩展的package:build支持以允许版本0.12.0 .

0.3.1 #

  • 添加一个build.yaml以便build_runner 0.7.0版的用户可以使用该构建器.

  • 现在需要Dart 2.0.0-dev版本.

0.3.0 #

  • 新的顶级库json_serializable.dart .

    • 替换现已弃用的generators.dart以访问JsonSerializableGeneratorJsonLiteralGenerator .

    • 添加jsonPartBuilder函数使创建PartBuilder变得容易,而无需在source_gen上创建显式依赖.

  • BREAKING UnsupportedTypeError增加了新的要求的构造函数的参数: reason .

  • BREAK弃用的annotations.dart .dart库已被删除. 使用package:json_annotation代替.

  • BREAKING TypeHelper serializedeserialize serialize的参数已更改.

    • 现在传递SerializeContextDeserializeContext (新类),而不是TypeHelperGenerator typedef(已删除).
  • JsonSerializableGenerator现在在生成和使用包装器类(希望)提高序列化的速度和内存使用量时支持可选的useWrappers参数,但需要更多代码.

    注意 :不能保证useWrappers可以提高序列化的性能. 建议进行基准测试.

  • 使null字段处理更智能. 如果将字段分类为不可为nullable ,则在生成序列化代码时使用此知识–即使includeIfNullfalse .

0.2.5 #

  • 如果检测到重复的JSON密钥,则引发异常.

  • JsonSerializable类注释上支持nullable字段.

0.2.4+1 #

  • 缺少构造函数时,抛出一个更有用的错误.

0.2.4 #

  • 将注解package:json_annotations中的annotations.dart移动到package:json_annotations .

    • Allows package authors to release code that has the corresponding annotations without requiring package users to inherit all of the transitive dependencies.
  • Deprecated annotations.dart.

0.2.3 #

  • 当第一个写入的字段未被null检查方法拦截时,可以更有效地写出toJson方法.

0.2.2+1 #

  • 当不需要对values转换时,简化Map实例的序列化.

  • 处理分配给double字段的JSON中的int文字.

0.2.2 #

  • 启用对enum值的支持.
  • Added asConst to JsonLiteral.
  • 改进了JSON字符串中Dart特定字符的处理.

0.2.1 #

  • 升级至package:source_gen v0.7.0

0.2.0+1 #

  • 序列化实现自己的fromJson构造函数的类时,请fromJson其构造函数参数类型.

0.2.0 #

  • BREAK现在,类型已细分为自己的库.

    • package:json_serializable/generators.dart contains Generator implementations.

    • package:json_serializable/annotations.dart包含注释. 该库应与您的目标类一起导入.

    • package:json_serializable/type_helpers.dart包含TypeHelper类和相关的帮助器,这些类允许自定义生成特定类型.

  • BREAK对于非JSON原语或不显式支持JSON序列化的类型,生成失败.

  • BREAKING TypeHelper:

    • 删除了can方法. 如果不支持提供的类型,则从(de)serialize返回null .

    • 为允许通用类型的(de)serialize方法添加了(de)serializeNested参数. 这就是实现对IterableListMap方式.

  • BREAKING JsonKey.jsonName被重命名为name ,现在是一个命名参数.

  • 添加了对可选非空字段的支持.

  • 添加了对生成JSON时排除null值的支持.

  • 消除了生成代码中的所有隐式强制转换. 在大多数情况下,这些最终将成为运行时检查.

  • 当由于未定义类型而导致生成失败时,提供有用的错误.

0.1.0+1 #

  • pubspec.yaml修复主页.

0.1.0 #

  • source_gen拆分.

  • 在可能不安全的生成的输出中添加/* unsafe */注释.

  • Map支持(反)序列化值.

  • 修复通过构造函数初始化字段时的顺序.

  • 计算要反序列化的字段时,请不要使用静态成员.

example/example.dart

// Copyright (c) 2017, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

import 'package:json_annotation/json_annotation.dart';

part 'example.g.dart';

@JsonSerializable(nullable: false)
class Person {
  final String firstName;
  final String lastName;
  final DateTime dateOfBirth;
  Person({this.firstName, this.lastName, this.dateOfBirth});
  factory Person.fromJson(Map<String, dynamic> json) => _$PersonFromJson(json);
  Map<String, dynamic> toJson() => _$PersonToJson(this);
}

Use this package as a library

1. Depend on it

将此添加到包的pubspec.yaml文件中:


dependencies:
  json_serializable: ^3.3.0

2. Install it

您可以从命令行安装软件包:

与酒吧:


$ pub get

另外,您的编辑器可能支持pub get . 查看您的编辑器文档以了解更多信息.

3. Import it

现在,在Dart代码中,您可以使用:


import 'package:json_serializable/json_serializable.dart';
  
Popularity:
描述该程序包相对于其他程序包的受欢迎程度. [更多]
98
Health:
从静态分析得出的代码运行状况. [更多]
100
Maintenance:
反映出软件包的整洁和最新状态. [更多]
100
Overall:
以上的加权分数. [更多]
99
了解有关得分的更多信息.

我们在2020年5月24日对该软件包进行了分析,并在下面提供了得分,详细信息和建议. using: 分析已完成,状态使用以下命令 :

  • 飞镖:2.8.1
  • 直到:0.13.8-dev

Dependencies

Package Constraint Resolved Available
直接依赖
Dart SDK > = 2.6.0 <3.0.0
analyzer ^0.39.0 0.39.8
build > = 0.12.6 <2.0.0 1.3.0
build_config > = 0.2.6 <0.5.0 0.4.2
json_annotation > = 3.0.0 <3.1.0 3.0.1
meta ^1.1.0 1.1.8
path ^1.3.2 1.7.0
source_gen ^0.9.0 0.9.5
传递依存关系
_fe_analyzer_shared 3.0.0
args 1.6.0
async 2.4.1
charcode 1.1.3
checked_yaml 1.0.2
convert 2.1.1
crypto 2.1.5
csslib 0.16.1
glob 1.2.0
html 0.14.0+3
js 0.6.1+1
node_interop 1.1.1
node_io 1.1.1
package_config 1.9.3
pedantic 1.9.0
pubspec_parse 0.1.5
source_span 1.7.0
string_scanner 1.0.5
term_glyph 1.1.0
typed_data 1.1.6
watcher 0.9.7+15
开发依赖
build_runner ^1.0.0
build_verify ^1.1.0
build_web_compilers > = 1.0.0 <3.0.0
collection ^1.14.0 1.14.12
dart_style ^1.2.0 1.3.6
logging ^0.11.3+1 0.11.4
pub_semver ^1.4.0 1.4.4
source_gen_test ^0.1.0
test ^1.6.0
yaml ^2.1.13 2.2.1

by  ICOPY.SITE