t01f4065cea3024e598.jpg

序列化器字段

布尔字段

布尔字段：BooleanField()

使用HTML编码的表单输入时，请注意False，即使已default=True指定选项，也将始终将忽略值视为将字段设置为。这是因为HTML复选框输入通过省略值来表示未选中状态，因此REST框架将忽略视为其为空复选框输入。
请注意，Django 2.1从中删除了blankkwarg models.BooleanField。在Django 2.1之前，models.BooleanField字段始终为blank=True。因此，由于Django 2.1的默认serializers.BooleanField实例将不带requiredkwarg（即等价于required=True）生成，而在Django 的早期版本中，默认BooleanField实例将带有required=False选项。如果要手动控制此行为，请BooleanField在序列化程序类上显式声明，或使用 extra_kwargs选项设置required标志。
对应于django.db.models.fields.BooleanField。
签名： BooleanField()

布尔字段：NullBooleanField()

布尔表示形式，也接受None为有效值。
对应于django.db.models.fields.NullBooleanField。
签名： NullBooleanField()

数值字段

数值字段：IntegerField()

整数表示。
对应于django.db.models.fields.IntegerField，django.db.models.fields.SmallIntegerField，django.db.models.fields.PositiveIntegerField和django.db.models.fields.PositiveSmallIntegerField。
签名：IntegerField(max_value=None, min_value=None)

  • max_value 验证提供的数字不大于此值。

  • min_value 验证提供的数字不小于此值。

    数值字段：FloatField()

    浮点表示。
    对应于django.db.models.fields.FloatField。
    签名：FloatField(max_value=None, min_value=None)

  • max_value 验证提供的数字不大于此值。

  • min_value 验证提供的数字不小于此值。

    数值字段：DecimalField()

    十进制表示形式，在Python中由Decimal实例表示。
    对应于django.db.models.fields.DecimalField。
    签名：DecimalField(max_digits, decimal_places, coerce_to_string=None, max_value=None, min_value=None)

  • max_digits数字中允许的最大位数。必须是None或大于或等于的整数decimal_places。

  • decimal_places 与数字一起存储的小数位数。
  • coerce_to_string设置为True是否应该为表示形式返回字符串值，或者False是否Decimal应该返回对象。默认值为与COERCE_DECIMAL_TO_STRING设置键相同的值，True除非覆盖，否则为默认值。如果Decimal对象由序列化程序返回，则最终输出格式将由渲染器确定。请注意，设置localize会将值强制设为True。
  • max_value 验证提供的数字不大于此值。
  • min_value 验证提供的数字不小于此值。
  • localize设置为True启用基于当前语言环境的输入和输出本地化。这也将迫使coerce_to_string到True。默认为False。请注意，如果您USE_L10N=True在设置文件中进行了设置，则会启用数据格式设置。
  • rounding将量化时使用的舍入模式设置为配置的精度。有效值为decimal模块舍入模式。默认为None。**

用法示例
要验证最大为999且分辨率为2位小数的数字，请使用：

  1. serializers.DecimalField(max_digits=5, decimal_places=2)

并使用十进制小数位数来验证小于十亿的数字：

  1. serializers.DecimalField(max_digits=19, decimal_places=10)

该字段还带有可选参数coerce_to_string。如果设置为True表示形式，则将作为字符串输出。如果设置为False，表示将作为Decimal实例保留，最终表示将由渲染器确定。
如果未设置，则默认为与COERCE_DECIMAL_TO_STRING设置相同的值，True除非另有设置。

日期和时间字段

日期和时间字段：DateTimeField()

日期和时间表示。
对应于django.db.models.fields.DateTimeField。
签名： DateTimeField(format=api_settings.DATETIME_FORMAT, input_formats=None, default_timezone=None)

  • format-代表输出格式的字符串。如果未指定，则默认为与DATETIME_FORMAT设置键相同的值，'iso-8601'除非设置，否则为默认值。设置为格式字符串表示to_representation返回值应强制为字符串输出。格式字符串如下所述。将此值设置为None表示Python datetime对象应由to_representation。在这种情况下，日期时间编码将由渲染器确定。
  • input_formats-表示可用于解析日期的输入格式的字符串列表。如果未指定，DATETIME_INPUT_FORMATS将使用该设置，默认为['iso-8601']。

  • default_timezone- pytz.timezone代表时区。如果未指定并且USE_TZ设置已启用，则默认为当前时区。如果USE_TZ被禁用，则日期时间对象将是幼稚的。

    DateTimeField 格式化字符串。

    格式字符串可以是显式指定格式的Python strftime格式，也可以是特殊字符串'iso-8601'，它指示应使用ISO 8601样式的日期时间。（例如'2013-01-29T12:34:56.000000Z'）
    当将值None用于格式时，datetime将返回对象to_representation，最终输出表示形式将由renderer类确定。

    auto_now和auto_now_add模型字段。

    使用ModelSerializer或时HyperlinkedModelSerializer，请注意，带有auto_now=True或的任何模型字段auto_now_add=True都将使用read_only=True默认情况下的序列化器字段。
    如果要覆盖此行为，则需要DateTimeField在序列化程序上显式声明。例如：

    1. class CommentSerializer(serializers.ModelSerializer):
    2.   created = serializers.DateTimeField()
    3.   class Meta:
    4.       model = Comment

    日期和时间字段：DateField()

    日期表示。
    对应于 django.db.models.fields.DateField
    签名： DateField(format=api_settings.DATE_FORMAT, input_formats=None)

  • format-代表输出格式的字符串。如果未指定，则默认为与DATE_FORMAT设置键相同的值，'iso-8601'除非设置，否则为默认值。设置为格式字符串表示to_representation返回值应强制为字符串输出。格式字符串如下所述。将此值设置为None表示Python date对象应由to_representation。在这种情况下，日期编码将由渲染器确定。

  • input_formats-表示可用于解析日期的输入格式的字符串列表。如果未指定，DATE_INPUT_FORMATS将使用该设置，默认为['iso-8601']。

    DateField 格式化字符串

    格式字符串可以是显式指定格式的Python strftime格式，也可以是特殊字符串'iso-8601'（指示应使用ISO 8601样式日期）。（例如'2013-01-29'）

    日期和时间字段：TimeField()

    时间表示。
    对应于 django.db.models.fields.TimeField
    签名： TimeField(format=api_settings.TIME_FORMAT, input_formats=None)

  • format-代表输出格式的字符串。如果未指定，则默认为与TIME_FORMAT设置键相同的值，'iso-8601'除非设置，否则为默认值。设置为格式字符串表示to_representation返回值应强制为字符串输出。格式字符串如下所述。将此值设置为None表示Python time对象应由to_representation。在这种情况下，时间编码将由渲染器确定。

  • input_formats-表示可用于解析日期的输入格式的字符串列表。如果未指定，TIME_INPUT_FORMATS将使用该设置，默认为['iso-8601']。

    TimeField 格式化字符串

    格式字符串可以是显式指定格式的Python strftime格式，也可以是特殊字符串'iso-8601'（指示应使用ISO 8601样式时间）。（例如'12:34:56.000000'）

    日期和时间字段：DurationField()

    持续时间表示。对应于django.db.models.fields.DurationField
    在validated_data这些字段将包含一个datetime.timedelta实例。该表示形式是遵循此格式的字符串'[DD] [HH:[MM:]]ss[.uuuuuu]'。
    签名： DurationField(max_value=None, min_value=None)

  • max_value 验证提供的持续时间不大于此值。

  • min_value 验证提供的持续时间不小于此值。

选择选择字段

选择选择字段：ChoiceField()

可以接受一组有限选择中的值的字段。
ModelSerializer如果相应的模型字段包含choices=…参数，则用于自动生成字段。
签名： ChoiceField(choices)

  • choices-有效值列表或(key, display_name)元组列表。
  • allow_blank-如果设置为True，则应将空字符串视为有效值。如果设置为，False则认为空字符串无效，并且将引发验证错误。默认为False。
  • html_cutoff-如果设置，则将是HTML select下拉列表将显示的最大选择数。可以用于确保自动生成的ChoiceFields（具有非常大的可能选择）不会阻止模板的呈现。默认为None。
  • html_cutoff_text-如果设置了此选项，则如果在HTML选择下拉列表中已截断最大数量的项目，则它将显示文本指示器。默认为"More than {count} items…"

无论是allow_blank与allow_null上有效的选项ChoiceField，但我们强烈建议您只使用一个，而不是两个。allow_blank应该首选用于文本选择，并且allow_null应该首选用于数字或其他非文本选择。

选择选择字段：MultipleChoiceField()

一个可以接受一组零，一个或多个值的字段，这些值是从一组有限的选择中选择的。接受一个强制性参数。to_internal_value返回set包含所选值的。
签名： MultipleChoiceField(choices)

  • choices-有效值列表或(key, display_name)元组列表。
  • allow_blank-如果设置为True，则应将空字符串视为有效值。如果设置为，False则认为空字符串无效，并且将引发验证错误。默认为False。
  • html_cutoff-如果设置，则将是HTML select下拉列表将显示的最大选择数。可以用于确保自动生成的ChoiceFields（具有非常大的可能选择）不会阻止模板的呈现。默认为None。
  • html_cutoff_text-如果设置了此选项，则如果在HTML选择下拉列表中已截断最大数量的项目，则它将显示文本指示器。默认为"More than {count} items…"

与一样ChoiceField，allow_blank和allow_null选项都有效，尽管强烈建议您只使用一个，而不要同时使用。allow_blank应该首选用于文本选择，并且allow_null应该首选用于数字或其他非文本选择。

字符串字段

字符字段：CharField()

文本表示形式。（可选）验证文本是否短于max_length和长于min_length。
对应于django.db.models.fields.CharField或django.db.models.fields.TextField。
签名： CharField(max_length=None, min_length=None, allow_blank=False, trim_whitespace=True)

  • max_length -验证输入的字符数不超过此数量。
  • min_length -验证输入的字符数不少于此。
  • allow_blank-如果设置为True，则应将空字符串视为有效值。如果设置为，False则认为空字符串无效，并且将引发验证错误。默认为False。
  • trim_whitespace-如果设置为，True则修剪前后的空白。默认为True。

该allow_null选项也可用于字符串字段，尽管不建议使用allow_blank。设置allow_blank=True和都是有效的allow_null=True，但是这样做意味着对于字符串表示而言，将存在两种不同类型的空值，这可能导致数据不一致和细微的应用程序错误。

字符字段：EmailField()

文本表示形式，将文本验证为有效的电子邮件地址。
对应于 django.db.models.fields.EmailField
签名： EmailField(max_length=None, min_length=None, allow_blank=False)

字符字段：RegexField()

文本表示形式，用于验证给定值是否与某个正则表达式匹配。
对应于django.forms.fields.RegexField。
签名： RegexField(regex, max_length=None, min_length=None, allow_blank=False)
强制regex参数可以是字符串，也可以是已编译的python正则表达式对象。
使用Django django.core.validators.RegexValidator进行验证。

字符字段：SlugField()

阿RegexField那验证对所述图案的输入[a-zA-Z0-9_-]+。
对应于django.db.models.fields.SlugField。
签名： SlugField(max_length=50, min_length=None, allow_blank=False)

字符字段：URLField()

阿RegexField那验证对一个URL匹配模式的输入。要求使用以下格式的完全限定网址http://<host>/<path>。
对应于django.db.models.fields.URLField。使用Django django.core.validators.URLValidator进行验证。
签名： URLField(max_length=200, min_length=None, allow_blank=False)

字符字段：FilePathField()

一个字段，其选择仅限于文件系统上某个目录中的文件名
对应于django.forms.fields.FilePathField。
签名： FilePathField(path, match=None, recursive=False, allow_files=True, allow_folders=False, required=None, **kwargs)

  • path -目录的绝对文件系统路径，应从中选择此FilePathField。
  • match -FilePathField将用于过滤文件名的正则表达式，作为字符串。
  • recursive-指定是否应包含路径的所有子目录。默认值为False。
  • allow_files-指定是否应包含指定位置的文件。默认值为True。要么是，要么allow_folders必须是True。

  • allow_folders-指定是否应包含指定位置的文件夹。默认值为False。要么是，要么allow_files必须是True。

    字符字段：IPAddressField()

    确保输入为有效IPv4或IPv6字符串的字段。
    对应于django.forms.fields.IPAddressField和django.forms.fields.GenericIPAddressField。
    签名：IPAddressField(protocol='both', unpack_ipv4=False, **options)

  • protocol将有效输入限制为指定的协议。接受的值是“两个”（默认），“ IPv4”或“ IPv6”。匹配不区分大小写。

  • unpack_ipv4解压缩IPv4映射的地址，例如:: ffff：192.0.2.1。如果启用此选项，则该地址将解压缩为192.0.2.1。默认设置为禁用。只能在协议设置为“ both”和“ both”时使用。

    字符字段：UUIDField()

    确保输入为有效UUID字符串的字段。该to_internal_value方法将返回一个uuid.UUID实例。在输出时，该字段将返回标准连字符格式的字符串，例如：

    1. "de305d54-75b4-431b-adb2-eb6b9e546013"

    签名： UUIDField(format='hex_verbose')

  • format：确定uuid值的表示形式

    • 'hex_verbose' -规范的十六进制表示形式，包括连字符： "5ce0e9a5-5ffa-654b-cee0-1238041fb31a"
    • 'hex' -UUID的紧凑十六进制表示形式，不包括连字符： "5ce0e9a55ffa654bcee01238041fb31a"
    • 'int' -UUID的128位整数表示： "123456789012312313134124512351145145114"
    • 'urn'-UUID的RFC 4122 URN表示形式："urn:uuid:5ce0e9a5-5ffa-654b-cee0-1238041fb31a" 更改format参数仅影响表示形式值。所有格式均被接受to_internal_value

文件上传字段

解析器和文件上传。
FileField和ImageField类是仅适用于使用MultiPartParser或FileUploadParser。大多数解析器（例如JSON）不支持文件上传。Django的常规FILE_UPLOAD_HANDLERS用于处理上传的文件。

文件上传字段：FileField()

文件表示。执行Django的标准FileField验证。
对应于django.forms.fields.FileField。
签名： FileField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)

  • max_length -指定文件名的最大长度。
  • allow_empty_file -指定是否允许空文件。

  • use_url-如果设置为，True则URL字符串值将用于输出表示。如果设置为，False则文件名字符串值将用于输出表示。默认为UPLOADED_FILES_USE_URL设置键的值，True除非另有设置，否则为默认值。

    文件上传字段：ImageField()

    图像表示。验证上传的文件内容是否与已知图像格式匹配。
    对应于django.forms.fields.ImageField。
    签名： ImageField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)

  • max_length -指定文件名的最大长度。

  • allow_empty_file -指定是否允许空文件。
  • use_url-如果设置为，True则URL字符串值将用于输出表示。如果设置为，False则文件名字符串值将用于输出表示。默认为UPLOADED_FILES_USE_URL设置键的值，True除非另有设置，否则为默认值。

需要Pillow包装或PIL包装。Pillow推荐该软件包，因为PIL不再积极维护该软件包。

复合字段

复合字段：ListField()

验证对象列表的字段类。
签名：ListField(child=<A_FIELD_INSTANCE>, allow_empty=True, min_length=None, max_length=None)

  • child-应该用于验证列表中对象的字段实例。如果未提供此参数，则将不验证列表中的对象。
  • allow_empty -指定是否允许空列表。
  • min_length -验证列表中包含的元素不少于此数量。
  • max_length -验证列表中所包含的元素数量不超过此数量。

例如，要验证整数列表，可以使用如下所示的内容：

  1. scores = serializers.ListField(
  2.    child=serializers.IntegerField(min_value=0, max_value=100)
  3. )

该ListField班还支持声明的风格，使您可以编写可重用列表字段类。

  1. class StringListField(serializers.ListField):
  2.     child = serializers.CharField()

现在，我们可以StringListField在整个应用程序中重用自定义类，而不必为其提供child参数。

复合字段：DictField()

验证对象字典的字段类。钥匙放在DictField总是假定为字符串值。
签名：DictField(child=<A_FIELD_INSTANCE>, allow_empty=True)

  • child-应该用于验证字典中值的字段实例。如果未提供此参数，则将不验证映射中的值。
  • allow_empty -指定是否允许使用空字典。

例如，要创建一个验证字符串到字符串映射关系的字段，您可以编写如下代码：

  1. document = DictField(child=CharField())

您也可以像使用一样使用声明式样式ListField。例如：

  1. class DocumentField(DictField):
  2.     child = CharField()

复合字段：HStoreField()

DictField与Django的postgres兼容的预配置HStoreField。
签名：HStoreField(child=<A_FIELD_INSTANCE>, allow_empty=True)

  • child-用于验证字典中值的字段实例。默认的子字段接受空字符串和空值。
  • allow_empty -指定是否允许使用空字典。

请注意，子字段必须是的实例CharField，因为hstore扩展将值存储为字符串。

复合字段：JSONField()

一个字段类，用于验证传入的数据结构是否包含有效的JSON原语。在其备用二进制模式下，它将表示并验证JSON编码的二进制字符串。
签名：JSONField(binary, encoder)

  • binary-如果设置为，True则该字段将输出并验证JSON编码的字符串，而不是原始数据结构。默认为False。
  • encoder-使用此JSON编码器序列化输入对象。默认为None。

杂项字段

杂项字段：ReadOnlyField()

一个字段类，仅返回该字段的值而无需修改。
ModelSerializer当包含与属性而非模型字段相关的字段名称时，默认情况下使用此字段。
签名：ReadOnlyField()
例如，如果has_expired是Account模型的属性，则以下序列化器将自动将其生成为ReadOnlyField：

  1. class AccountSerializer(serializers.ModelSerializer):
  2.     class Meta:
  3.         model = Account
  4.         fields = ['id', 'account_name', 'has_expired']

杂项字段：HiddenFeid()

字段类不基于用户输入获取值，而是从默认值或可调用对象获取其值。
签名：HiddenField()
例如，要包括一个始终提供当前时间的字段作为序列化程序验证数据的一部分，则可以使用以下代码：

  1. modified = serializers.HiddenField(default=timezone.now)

的HiddenField，如果你有一些验证需要运行基于一些预先提供的字段值通常只需要一流的，但你不希望将所有这些领域的暴露给最终用户。
有关更多示例，HiddenField请参见验证程序文档。

更多信息，请参照官方文档