Khung công tác Django REST Tìm kiếm Trước Kế tiếp GitHub

trường nổi
Trường thập phân
Trường ngày và giờ

Trường ngày giờ

Trường ngày
trường thời gian
Trường thời lượng
Các trường lựa chọn lựa chọn

Trường lựa chọn

Trường Nhiều Lựa Chọn
Các trường tải lên tệp

Trình phân tích cú pháp và tải lên tập tin.

Trường tệp
Trường hình ảnh
Trường tổng hợp

trường danh sách

DictField
HStoreField
trường JSON
Các trường khác

trường chỉ đọc

Giấu trang
trường mẫu
SerializerMethodField
Trường tùy chỉnh

Ví dụ
Gói của bên thứ ba

Trường hợp chất DRF

Trường bổ sung DRF
djangorestframework-đệ quy
django-rest-framework-gis
django-rest-framework-hstore

lĩnh vực.py

Các trường nối tiếp

Mỗi trường trong lớp Biểu mẫu không chỉ chịu trách nhiệm xác thực dữ liệu mà
còn chịu trách nhiệm "làm sạch" dữ liệu - chuẩn hóa dữ liệu thành định dạng
nhất quán.
 - Tài liệu Django

“
Các trường tuần tự hóa xử lý việc chuyển đổi giữa các giá trị nguyên thủy và kiểu dữ liệu nội bộ. Chúng cũng
xử lý việc xác thực các giá trị đầu vào cũng như truy xuất và thiết lập các giá trị từ các đối tượng cha của
chúng.

Lưu ý: Các trường serializer được khai báo bằng fields.py , nhưng theo quy ước, bạn nên nhập chúng bằng
cách sử dụng from rest_framework import serializers và tham chiếu đến các trường dưới dạng
serializers.<FieldName> .

Lập luận cốt lõi

Mỗi hàm tạo của lớp trường tuần tự hóa có ít nhất các đối số này. Một số lớp Trường có các đối số bổ sung,
dành riêng cho từng trường, nhưng những đối số sau phải luôn được chấp nhận:

read_only

Các trường chỉ đọc được đưa vào đầu ra API nhưng không được đưa vào đầu vào trong quá trình tạo hoặc
cập nhật. Bất kỳ trường 'read_only' nào được đưa vào không chính xác trong đầu vào của bộ nối tiếp sẽ bị bỏ
qua.

Đặt giá trị này True để đảm bảo rằng trường được sử dụng khi tuần tự hóa một biểu diễn nhưng không được
sử dụng khi tạo hoặc cập nhật một phiên bản trong quá trình giải tuần tự hóa.

Mặc định là False

write_only

Đặt giá trị này True để đảm bảo rằng trường có thể được sử dụng khi cập nhật hoặc tạo một phiên bản,
nhưng không được đưa vào khi tuần tự hóa biểu diễn.

Mặc định là False

required

Thông thường, một lỗi sẽ xuất hiện nếu một trường không được cung cấp trong quá trình khử lưu lượng. Đặt
thành sai nếu trường này không bắt buộc phải có trong quá trình khử lưu huỳnh.

Việc đặt cài đặt này thành False cũng cho phép loại bỏ thuộc tính đối tượng hoặc khóa từ điển khỏi đầu ra
khi tuần tự hóa phiên bản. Nếu khóa không có, nó sẽ không được đưa vào biểu diễn đầu ra.

Mặc định là True . Nếu bạn đang sử dụng Model Serializer, giá trị mặc định sẽ là False nếu bạn đã chỉ định
blank=True or default tại null=True trường của bạn trong Model .

default

Nếu được đặt, giá trị này sẽ cung cấp giá trị mặc định sẽ được sử dụng cho trường nếu không có giá trị đầu
vào nào được cung cấp. Nếu không được đặt, hành vi mặc định là không điền thuộc tính nào cả.
Việc này default không được áp dụng trong các hoạt động cập nhật một phần. Trong trường hợp cập nhật
một phần, chỉ các trường được cung cấp trong dữ liệu đến mới có giá trị được xác thực được trả về.

Có thể được đặt thành một hàm hoặc có thể gọi khác, trong trường hợp đó, giá trị sẽ được đánh giá mỗi khi
nó được sử dụng. Khi được gọi, nó sẽ không nhận được đối số. Nếu khả năng gọi được có một
requires_context = True thuộc tính thì trường tuần tự hóa sẽ được chuyển làm đối số.

Ví dụ:

class CurrentUserDefault:
"""
May be applied as a `default=...` value on a serializer field.
Returns the current user.
"""
requires_context = True

def __call__(self, serializer_field):

return serializer_field.context['request'].user

Khi tuần tự hóa phiên bản, mặc định sẽ được sử dụng nếu thuộc tính đối tượng hoặc khóa từ điển không có
trong phiên bản.

Lưu ý rằng việc đặt default giá trị có nghĩa là trường này không bắt buộc. Việc bao gồm cả đối số từ khóa
default và required là không hợp lệ và sẽ gây ra lỗi.

allow_null

Thông thường, một lỗi sẽ xuất hiện nếu None được chuyển đến trường bộ tuần tự hóa. Đặt đối số từ khóa
này thành True if None sẽ được coi là giá trị hợp lệ.

Lưu ý rằng, nếu không có đối số rõ ràng default , việc đặt đối số này thành True sẽ ngụ ý default giá trị
của null đầu ra tuần tự hóa, nhưng không ngụ ý giá trị mặc định cho quá trình khử tuần tự hóa đầu vào.

Mặc định là False

source

Tên của thuộc tính sẽ được sử dụng để điền vào trường. Có thể là một phương thức chỉ lấy một self đối số,
chẳng hạn như URLField(source='get_absolute_url') , hoặc có thể sử dụng ký hiệu chấm để duyệt
qua các thuộc tính, chẳng hạn như EmailField(source='user.email') .

Khi tuần tự hóa các trường có ký hiệu chấm, có thể cần phải cung cấp một default giá trị nếu bất kỳ đối
tượng nào không xuất hiện hoặc trống trong quá trình truyền tải thuộc tính. Cảnh giác với các vấn đề n+1 có
thể xảy ra khi sử dụng thuộc tính nguồn nếu bạn đang truy cập mô hình orm quan hệ. Ví dụ:

class CommentSerializer(serializers.Serializer):
email = serializers.EmailField(source="user.email")

Trường hợp này sẽ yêu cầu tìm nạp đối tượng người dùng từ cơ sở dữ liệu khi nó không được tìm nạp trước.
Nếu điều đó không được mong muốn, hãy đảm bảo sử dụng prefetch_related và select_related áp
dụng các phương pháp thích hợp. Để biết thêm thông tin về các phương pháp, hãy tham khảo tài liệu django .

Giá trị này source='*' có ý nghĩa đặc biệt và được sử dụng để chỉ ra rằng toàn bộ đối tượng phải được
chuyển qua trường. Điều này có thể hữu ích khi tạo các biểu diễn lồng nhau hoặc cho các trường yêu cầu
quyền truy cập vào đối tượng hoàn chỉnh để xác định biểu diễn đầu ra.

Mặc định là tên của trường.

validators

Danh sách các hàm xác thực sẽ được áp dụng cho đầu vào của trường đến và sẽ gây ra lỗi xác thực hoặc chỉ
đơn giản là trả về. Các hàm xác thực thường sẽ tăng lên serializers.ValidationError , nhưng tính năng
tích hợp sẵn của Django ValidationError cũng được hỗ trợ để tương thích với các trình xác thực được xác
định trong cơ sở mã Django hoặc các gói Django của bên thứ ba.

error_messages

Từ điển mã lỗi cho các thông báo lỗi.

label

Một chuỗi văn bản ngắn có thể được sử dụng làm tên trường trong các trường biểu mẫu HTML hoặc các
thành phần mô tả khác.

help_text

Một chuỗi văn bản có thể được sử dụng làm mô tả trường trong các trường biểu mẫu HTML hoặc các thành
phần mô tả khác.

initial

Một giá trị nên được sử dụng để điền trước giá trị của các trường biểu mẫu HTML. Bạn có thể chuyển một
lệnh gọi đến nó, giống như bạn có thể làm với bất kỳ Django thông thường nào Field :

import datetime
from rest_framework import serializers
class ExampleSerializer(serializers.Serializer):
day = serializers.DateField(initial=datetime.date.today)

style

Từ điển gồm các cặp khóa-giá trị có thể được sử dụng để kiểm soát cách trình kết xuất hiển thị trường.

Hai ví dụ ở đây là 'input_type' và 'base_template' :

# Use <input type="password"> for the input.

password = serializers.CharField(
style={'input_type': 'password'}
 )

# Use a radio input instead of a select input.

color_channel = serializers.ChoiceField(
choices=['red', 'green', 'blue'],
style={'base_template': 'radio.html'}
)

Để biết thêm chi tiết, hãy xem tài liệu HTML & Biểu mẫu .

trường Boolean
Trường Boolean
Một biểu diễn boolean.

Khi sử dụng đầu vào biểu mẫu được mã hóa HTML, hãy lưu ý rằng việc bỏ qua một giá trị sẽ luôn được coi là
đặt trường thành False , ngay cả khi trường đó có default=True tùy chọn được chỉ định. Điều này là do
đầu vào hộp kiểm HTML biểu thị trạng thái không được chọn bằng cách bỏ qua giá trị, do đó, khung REST xử
lý phần thiếu sót như thể đó là đầu vào hộp kiểm trống.

Lưu ý rằng Django 2.1 đã xóa blank kwarg khỏi models.BooleanField . Trước
models.BooleanField các trường Django 2.1 luôn là blank=True . Do đó, vì các phiên bản mặc định của
Django 2.1 serializers.BooleanField sẽ được tạo mà không có required kwarg (tức là tương đương
với required=True ) trong khi với các phiên bản trước của Django, BooleanField các phiên bản mặc định
sẽ được tạo bằng một required=False tùy chọn. Nếu bạn muốn kiểm soát hành vi này theo cách thủ công,
hãy khai báo rõ ràng BooleanField trên lớp serializer hoặc sử dụng extra_kwargs tùy chọn để đặt
required cờ.

Tương ứng với django.db.models.fields.BooleanField .

Chữ ký: BooleanField()

Trường chuỗi
CharField
Một đại diện văn bản. Tùy chọn xác thực văn bản ngắn hơn max_length và dài hơn min_length .

Tương ứng với django.db.models.fields.CharField hoặc django.db.models.fields.TextField .

Chữ ký: CharField(max_length=None, min_length=None, allow_blank=False,

trim_whitespace=True)

max_length - Xác thực rằng đầu vào không chứa nhiều hơn số ký tự này.
min_length - Xác thực rằng đầu vào chứa không ít hơn số ký tự này.
allow_blank - Nếu được đặt thành True thì chuỗi trống sẽ được coi là giá trị hợp lệ. Nếu được đặt
thành False thì chuỗi trống được coi là không hợp lệ và sẽ gây ra lỗi xác thực. Mặc định là False .
 trim_whitespace - Nếu được đặt thành True thì khoảng trắng ở đầu và cuối sẽ bị cắt bớt. Mặc định là
True .

Tùy chọn này allow_null cũng có sẵn cho các trường chuỗi, mặc dù việc sử dụng nó không được khuyến
khích allow_blank . Việc đặt cả hai allow_blank=True và allow_null=True , nhưng làm như vậy có
nghĩa là sẽ có hai loại giá trị trống khác nhau được phép biểu diễn chuỗi, điều này có thể dẫn đến sự không
nhất quán về dữ liệu và các lỗi ứng dụng tinh vi.

Trường email
Một bản trình bày văn bản, xác nhận văn bản là một địa chỉ e-mail hợp lệ.

Tương ứng với django.db.models.fields.EmailField

Chữ ký: EmailField(max_length=None, min_length=None, allow_blank=False)

Trường Regex
Một biểu diễn văn bản xác thực giá trị đã cho khớp với một biểu thức chính quy nhất định.

Tương ứng với django.forms.fields.RegexField .

Chữ ký: RegexField(regex, max_length=None, min_length=None, allow_blank=False)

Đối số bắt buộc regex có thể là một chuỗi hoặc một đối tượng biểu thức chính quy python được biên dịch.

Sử dụng Django django.core.validators.RegexValidator để xác thực.

SlugField
A RegexField xác nhận đầu vào theo mẫu [a-zA-Z0-9_-]+ .

Tương ứng với django.db.models.fields.SlugField .

Chữ ký: SlugField(max_length=50, min_length=None, allow_blank=False)

Trường URL
A RegexField xác thực dữ liệu đầu vào dựa trên mẫu khớp URL. Yêu cầu các URL đủ điều kiện có dạng
http://<host>/<path> .

Tương ứng với django.db.models.fields.URLField . Sử dụng Django

django.core.validators.URLValidator để xác thực.

Chữ ký: URLField(max_length=200, min_length=None, allow_blank=False)

UUIDField
Trường đảm bảo đầu vào là chuỗi UUID hợp lệ. Phương thức này to_internal_value sẽ trả về một
uuid.UUID thể hiện. Ở đầu ra, trường sẽ trả về một chuỗi ở định dạng gạch nối chính tắc, ví dụ:

"de305d54-75b4-431b-adb2-eb6b9e546013"
Chữ ký: UUIDField(format='hex_verbose')

format : Xác định định dạng biểu diễn của giá trị uuid
'hex_verbose' - Cách biểu diễn hex chuẩn, bao gồm dấu gạch nối: "5ce0e9a5-5ffa-654b-cee0-
1238041fb31a"
'hex' - Cách biểu diễn dạng hex thu gọn của UUID, không bao gồm dấu gạch
nối: "5ce0e9a55ffa654bcee01238041fb31a"
'int' - Biểu diễn số nguyên 128 bit của UUID: "123456789012312313134124512351145145114"
'urn' - RFC 4122 URN biểu diễn UUID: "urn:uuid:5ce0e9a5-5ffa-654b-cee0-1238041fb31a"
Việc thay đổi format tham số chỉ ảnh hưởng đến giá trị biểu diễn. Tất cả các định dạng được chấp
nhận bởi to_internal_value

Trường đường dẫn tệp

Trường có các lựa chọn bị giới hạn ở tên tệp trong một thư mục nhất định trên hệ thống tệp

Tương ứng với django.forms.fields.FilePathField .

Chữ ký: FilePathField(path, match=None, recursive=False, allow_files=True,

allow_folders=False, required=None, **kwargs)

path - Đường dẫn hệ thống tập tin tuyệt đối đến một thư mục mà FilePathField này sẽ nhận được sự lựa
chọn của nó.
match - Một biểu thức chính quy, dưới dạng một chuỗi, mà FilePathField sẽ sử dụng để lọc tên tệp.
recursive - Chỉ định xem có nên bao gồm tất cả các thư mục con của đường dẫn hay không. Mặc định
là False .
allow_files - Chỉ định xem có nên đưa các tập tin vào vị trí đã chỉ định hay không. Mặc định là True .
Hoặc là thế này hoặc allow_folders phải là thế này True .
allow_folders - Chỉ định xem có nên đưa các thư mục vào vị trí đã chỉ định hay không. Mặc định là
False . Hoặc là thế này hoặc allow_files phải là thế này True .

Trường địa chỉ IP

Trường đảm bảo đầu vào là chuỗi IPv4 hoặc IPv6 hợp lệ.

Tương ứng với django.forms.fields.IPAddressField và

django.forms.fields.GenericIPAddressField .

Chữ ký : IPAddressField(protocol='both', unpack_ipv4=False, **options)

protocol Giới hạn đầu vào hợp lệ đối với giao thức được chỉ định. Các giá trị được chấp nhận là 'cả hai'
(mặc định), 'IPv4' hoặc 'IPv6'. Kết hợp không phân biệt chữ hoa chữ thường.
unpack_ipv4 Giải nén các địa chỉ được ánh xạ IPv4 như ::ffff:192.0.2.1. Nếu tùy chọn này được bật, địa
chỉ đó sẽ được giải nén thành 192.0.2.1. Mặc định bị vô hiệu hóa. Chỉ có thể được sử dụng khi giao thức
được đặt thành 'cả hai'.

Trường số
trường số nguyên
Một biểu diễn số nguyên.

Tương ứng với django.db.models.fields.IntegerField ,

django.db.models.fields.SmallIntegerField ,
django.db.models.fields.PositiveIntegerField và
django.db.models.fields.PositiveSmallIntegerField .

Chữ ký : IntegerField(max_value=None, min_value=None)

max_value Xác thực rằng số được cung cấp không lớn hơn giá trị này.
min_value Xác thực rằng số được cung cấp không nhỏ hơn giá trị này.

trường nổi
Một biểu diễn dấu phẩy động.

Tương ứng với django.db.models.fields.FloatField .

Chữ ký : FloatField(max_value=None, min_value=None)

max_value Xác thực rằng số được cung cấp không lớn hơn giá trị này.
min_value Xác thực rằng số được cung cấp không nhỏ hơn giá trị này.

Trường thập phân

Biểu diễn thập phân, được biểu thị bằng Python bằng một Decimal phiên bản.

Tương ứng với django.db.models.fields.DecimalField .

Chữ ký : DecimalField(max_digits, decimal_places, coerce_to_string=None, max_value=None,

min_value=None)

max_digits Số chữ số tối đa được phép trong số. Nó phải là một None hoặc một số nguyên lớn hơn
hoặc bằng decimal_places .
decimal_places Số vị trí thập phân cần lưu trữ cùng với số.
coerce_to_string Đặt thành True nếu các giá trị chuỗi phải được trả về cho biểu diễn hoặc
False nếu Decimal các đối tượng sẽ được trả về. Mặc định có cùng giá trị với
COERCE_DECIMAL_TO_STRING khóa cài đặt, trừ True khi bị ghi đè. Nếu Decimal các đối tượng được
bộ tuần tự hóa trả về thì định dạng đầu ra cuối cùng sẽ được trình kết xuất xác định. Lưu ý rằng cài đặt
localize sẽ buộc giá trị là True .
max_value Xác thực rằng số được cung cấp không lớn hơn giá trị này.
min_value Xác thực rằng số được cung cấp không nhỏ hơn giá trị này.
localize Đặt thành True để bật bản địa hóa đầu vào và đầu ra dựa trên ngôn ngữ hiện tại. Điều này
cũng sẽ buộc coerce_to_string phải True . Mặc định là False . Lưu ý rằng định dạng dữ liệu sẽ
được bật nếu bạn đã thiết lập USE_L10N=True trong tệp cài đặt của mình.
rounding Đặt chế độ làm tròn được sử dụng khi lượng tử hóa theo độ chính xác đã định cấu hình. Các
giá trị hợp lệ là decimal các chế độ làm tròn mô-đun . Mặc định là None .
normalize_output Sẽ bình thường hóa giá trị thập phân khi được tuần tự hóa. Điều này sẽ loại bỏ tất
cả các số 0 ở cuối và thay đổi độ chính xác của giá trị thành độ chính xác yêu cầu tối thiểu để có thể biểu
thị giá trị mà không làm mất dữ liệu. Mặc định là False .

Cách sử dụng ví dụ
Để xác thực các số lên tới 999 với độ phân giải 2 chữ số thập phân, bạn sẽ sử dụng:
 serializers.DecimalField(max_digits=5, decimal_places=2)

Và để xác thực các số lên tới dưới một tỷ với độ phân giải 10 chữ số thập phân:

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

Trường ngày và giờ

Trường ngày giờ
Một đại diện ngày và thời gian.

Tương ứng với django.db.models.fields.DateTimeField .

Chữ ký: DateTimeField(format=api_settings.DATETIME_FORMAT, input_formats=None,

default_timezone=None)

format - Một chuỗi đại diện cho định dạng đầu ra. Nếu không được chỉ định, giá trị mặc định này có
cùng giá trị với DATETIME_FORMAT khóa cài đặt, trừ 'iso-8601' khi được đặt. Việc đặt thành chuỗi
định dạng cho biết rằng to_representation các giá trị trả về phải được ép buộc thành đầu ra chuỗi.
Chuỗi định dạng được mô tả dưới đây. Việc đặt giá trị này để None cho biết rằng các đối tượng Python
datetime phải được trả về bởi to_representation . Trong trường hợp này, mã hóa ngày giờ sẽ được
xác định bởi trình kết xuất.
input_formats - Danh sách các chuỗi đại diện cho các định dạng đầu vào có thể được sử dụng để
phân tích ngày tháng. Nếu không được chỉ định, DATETIME_INPUT_FORMATS cài đặt này sẽ được sử
dụng, mặc định là ['iso-8601'] .
default_timezone - Một tzinfo lớp con ( zoneinfo hoặc pytz ) đại diện cho múi giờ. Nếu không
được chỉ định và USE_TZ cài đặt được bật, cài đặt này sẽ mặc định là múi giờ hiện tại . Nếu USE_TZ bị
tắt thì đối tượng datetime sẽ không có giá trị.

DateTimeField chuỗi định dạng.

Chuỗi định dạng có thể là định dạng strftime của Python chỉ định rõ ràng định dạng hoặc chuỗi đặc biệt
'iso-8601' cho biết nên sử dụng ngày giờ theo kiểu ISO 8601 . (ví dụ '2013-01-
29T12:34:56.000000Z' )

Khi một giá trị của None được sử dụng cho các datetime đối tượng định dạng sẽ được trả về
to_representation và biểu diễn đầu ra cuối cùng sẽ được xác định bởi lớp trình kết xuất.

auto_now và auto_now_add các trường mẫu.

Khi sử dụng ModelSerializer or HyperlinkedModelSerializer , hãy lưu ý rằng bất kỳ trường mô hình
nào có auto_now=True hoặc auto_now_add=True sẽ sử dụng các trường bộ tuần tự hóa
read_only=True theo mặc định.

Nếu bạn muốn ghi đè hành vi này, bạn sẽ cần khai báo DateTimeField rõ ràng trên bộ nối tiếp. Ví dụ:
 class CommentSerializer(serializers.ModelSerializer):
created = serializers.DateTimeField()

class Meta:
model = Comment

Trường ngày
Một đại diện ngày.

Tương ứng với django.db.models.fields.DateField

Chữ ký: DateField(format=api_settings.DATE_FORMAT, input_formats=None)

format - Một chuỗi đại diện cho định dạng đầu ra. Nếu không được chỉ định, giá trị mặc định này có
cùng giá trị với DATE_FORMAT khóa cài đặt, trừ 'iso-8601' khi được đặt. Việc đặt thành chuỗi định
dạng cho biết rằng to_representation các giá trị trả về phải được ép buộc thành đầu ra chuỗi. Chuỗi
định dạng được mô tả dưới đây. Việc đặt giá trị này để None cho biết rằng các đối tượng Python
date phải được trả về bởi to_representation . Trong trường hợp này, mã hóa ngày sẽ được xác định
bởi trình kết xuất.
input_formats - Danh sách các chuỗi đại diện cho các định dạng đầu vào có thể được sử dụng để
phân tích ngày tháng. Nếu không được chỉ định, DATE_INPUT_FORMATS cài đặt này sẽ được sử dụng,
mặc định là ['iso-8601'] .

DateField chuỗi định dạng

Chuỗi định dạng có thể là định dạng strftime của Python chỉ định rõ ràng định dạng hoặc chuỗi đặc biệt
'iso-8601' cho biết nên sử dụng ngày theo kiểu ISO 8601 . (ví dụ '2013-01-29' )

trường thời gian

Một đại diện thời gian.

Tương ứng với django.db.models.fields.TimeField

Chữ ký: TimeField(format=api_settings.TIME_FORMAT, input_formats=None)

format - Một chuỗi đại diện cho định dạng đầu ra. Nếu không được chỉ định, giá trị mặc định này có
cùng giá trị với TIME_FORMAT khóa cài đặt, trừ 'iso-8601' khi được đặt. Việc đặt thành chuỗi định
dạng cho biết rằng to_representation các giá trị trả về phải được ép buộc thành đầu ra chuỗi. Chuỗi
định dạng được mô tả dưới đây. Việc đặt giá trị này để None cho biết rằng các đối tượng Python
time phải được trả về bởi to_representation . Trong trường hợp này, mã hóa thời gian sẽ được xác
định bởi trình kết xuất.
input_formats - Danh sách các chuỗi đại diện cho các định dạng đầu vào có thể được sử dụng để
phân tích ngày tháng. Nếu không được chỉ định, TIME_INPUT_FORMATS cài đặt này sẽ được sử dụng,
mặc định là ['iso-8601'] .

TimeField chuỗi định dạng

Chuỗi định dạng có thể là định dạng strftime của Python chỉ định rõ ràng định dạng hoặc chuỗi đặc biệt
'iso-8601' cho biết nên sử dụng thời gian kiểu ISO 8601 . (ví dụ '12:34:56.000000' )
Trường thời lượng
Một đại diện cho thời lượng. Tương ứng với django.db.models.fields.DurationField

Đối validated_data với các trường này sẽ chứa một datetime.timedelta phiên bản. Biểu diễn là một
chuỗi theo định dạng này '[DD] [HH:[MM:]]ss[.uuuuuu]' .

Chữ ký: DurationField(max_value=None, min_value=None)

max_value Xác thực rằng thời lượng được cung cấp không lớn hơn giá trị này.
min_value Xác thực rằng thời lượng được cung cấp không nhỏ hơn giá trị này.

Các trường lựa chọn lựa chọn

Trường lựa chọn
Một trường có thể chấp nhận một giá trị từ một tập hợp các lựa chọn có giới hạn.

Được sử dụng bởi ModelSerializer để tự động tạo các trường nếu trường mô hình tương ứng bao gồm
một choices=… đối số.

Chữ ký: ChoiceField(choices)

choices - Danh sách các giá trị hợp lệ hoặc danh sách (key, display_name) các bộ dữ liệu.
allow_blank - Nếu được đặt thành True thì chuỗi trống sẽ được coi là giá trị hợp lệ. Nếu được đặt
thành False thì chuỗi trống được coi là không hợp lệ và sẽ gây ra lỗi xác thực. Mặc định là False .
html_cutoff - Nếu được đặt, đây sẽ là số lượng lựa chọn tối đa sẽ được hiển thị bằng trình đơn thả
xuống chọn HTML. Có thể được sử dụng để đảm bảo rằng các Trường lựa chọn được tạo tự động với các
lựa chọn có thể có rất lớn không ngăn mẫu hiển thị. Mặc định là None .
html_cutoff_text - Nếu được đặt, điều này sẽ hiển thị chỉ báo văn bản nếu số lượng mục tối đa đã bị
cắt trong trình đơn thả xuống chọn HTML. Mặc định là "More than {count} items…"

Cả hai allow_blank và đều allow_null là các tùy chọn hợp lệ trên ChoiceField , mặc dù chúng tôi
khuyên bạn chỉ nên sử dụng một chứ không phải cả hai. allow_blank nên được ưu tiên cho các lựa chọn
văn bản và allow_null nên được ưu tiên cho các lựa chọn số hoặc phi văn bản khác.

Trường Nhiều Lựa Chọn

Trường có thể chấp nhận một tập hợp 0, một hoặc nhiều giá trị, được chọn từ một tập hợp các lựa chọn giới
hạn. Nhận một đối số bắt buộc duy nhất. to_internal_value trả về a set chứa các giá trị đã chọn.

Chữ ký: MultipleChoiceField(choices)

choices - Danh sách các giá trị hợp lệ hoặc danh sách (key, display_name) các bộ dữ liệu.
allow_blank - Nếu được đặt thành True thì chuỗi trống sẽ được coi là giá trị hợp lệ. Nếu được đặt
thành False thì chuỗi trống được coi là không hợp lệ và sẽ gây ra lỗi xác thực. Mặc định là False .
html_cutoff - Nếu được đặt, đây sẽ là số lượng lựa chọn tối đa sẽ được hiển thị bằng trình đơn thả
xuống chọn HTML. Có thể được sử dụng để đảm bảo rằng các Trường lựa chọn được tạo tự động với các
lựa chọn có thể có rất lớn không ngăn mẫu hiển thị. Mặc định là None .
html_cutoff_text - Nếu được đặt, điều này sẽ hiển thị chỉ báo văn bản nếu số lượng mục tối đa đã bị
cắt trong trình đơn thả xuống chọn HTML. Mặc định là "More than {count} items…"
Đối với ChoiceField , cả hai tùy chọn allow_blank và allow_null đều hợp lệ, mặc dù chúng tôi khuyên
bạn chỉ nên sử dụng một chứ không phải cả hai. allow_blank nên được ưu tiên cho các lựa chọn văn bản
và allow_null nên được ưu tiên cho các lựa chọn số hoặc phi văn bản khác.

Các trường tải lên tệp

Trình phân tích cú pháp và tải lên tập tin.
Các lớp FileField and ImageField chỉ thích hợp để sử dụng với MultiPartParser or
FileUploadParser . Hầu hết các trình phân tích cú pháp, chẳng hạn như JSON không hỗ trợ tải tệp lên.
FILE_UPLOAD_HANDLERS thông thường của Django được sử dụng để xử lý các tệp đã tải lên.

Trường tệp
Một đại diện tập tin. Thực hiện xác thực FileField tiêu chuẩn của Django.

Tương ứng với django.forms.fields.FileField .

Chữ ký: FileField(max_length=None, allow_empty_file=False,

use_url=UPLOADED_FILES_USE_URL)

max_length - Chỉ định độ dài tối đa cho tên file.

allow_empty_file - Chỉ định nếu các tập tin trống được cho phép.
use_url - Nếu được đặt thành True thì các giá trị chuỗi URL sẽ được sử dụng để biểu diễn đầu ra. Nếu
được đặt thành False thì giá trị chuỗi tên tệp sẽ được sử dụng để biểu diễn đầu ra. Mặc định là giá trị
của UPLOADED_FILES_USE_URL khóa cài đặt, trừ True khi được đặt khác.

Trường hình ảnh

Một hình ảnh đại diện. Xác thực nội dung tệp được tải lên phù hợp với định dạng hình ảnh đã biết.

Tương ứng với django.forms.fields.ImageField .

Chữ ký: ImageField(max_length=None, allow_empty_file=False,

use_url=UPLOADED_FILES_USE_URL)

max_length - Chỉ định độ dài tối đa cho tên file.

allow_empty_file - Chỉ định nếu các tập tin trống được cho phép.
use_url - Nếu được đặt thành True thì các giá trị chuỗi URL sẽ được sử dụng để biểu diễn đầu ra. Nếu
được đặt thành False thì giá trị chuỗi tên tệp sẽ được sử dụng để biểu diễn đầu ra. Mặc định là giá trị
của UPLOADED_FILES_USE_URL khóa cài đặt, trừ True khi được đặt khác.

Yêu cầu Pillow gói hoặc PIL gói. Gói này Pillow được khuyến nghị vì PIL không còn được duy trì tích
cực nữa.

Trường tổng hợp

trường danh sách
Một lớp trường xác nhận danh sách các đối tượng.

Chữ ký : ListField(child=<A_FIELD_INSTANCE>, allow_empty=True, min_length=None,

max_length=None)

child - Một trường hợp nên được sử dụng để xác thực các đối tượng trong danh sách. Nếu đối số này
không được cung cấp thì các đối tượng trong danh sách sẽ không được xác thực.
allow_empty - Chỉ định nếu danh sách trống được phép.
min_length - Xác thực rằng danh sách chứa không ít hơn số phần tử này.
max_length - Xác thực rằng danh sách không chứa nhiều hơn số phần tử này.

Ví dụ: để xác thực danh sách các số nguyên, bạn có thể sử dụng một số thứ như sau:

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

Lớp này ListField cũng hỗ trợ kiểu khai báo cho phép bạn viết các lớp trường danh sách có thể sử dụng
lại.

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

Bây giờ chúng ta có thể sử dụng lại StringListField lớp tùy chỉnh của mình trong suốt ứng dụng của mình
mà không cần phải cung cấp child đối số cho nó.

DictField
Một lớp trường xác nhận từ điển của các đối tượng. Các khóa trong DictField luôn được coi là giá trị chuỗi.

Chữ ký : DictField(child=<A_FIELD_INSTANCE>, allow_empty=True)

child - Một trường hợp nên được sử dụng để xác thực các giá trị trong từ điển. Nếu đối số này không
được cung cấp thì các giá trị trong ánh xạ sẽ không được xác thực.
allow_empty - Chỉ định nếu từ điển trống được cho phép.

Ví dụ: để tạo một trường xác thực việc ánh xạ các chuỗi thành chuỗi, bạn sẽ viết một cái gì đó như thế này:

document = DictField(child=CharField())

Bạn cũng có thể sử dụng kiểu khai báo, như với ListField . Ví dụ:

class DocumentField(DictField):
child = CharField()

HStoreField
Một cấu hình sẵn DictField tương thích với postgres của Django HStoreField .

Chữ ký : HStoreField(child=<A_FIELD_INSTANCE>, allow_empty=True)

child - Một trường hợp được sử dụng để xác thực các giá trị trong từ điển. Trường con mặc định chấp
nhận cả chuỗi trống và giá trị null.
allow_empty - Chỉ định nếu từ điển trống được cho phép.

Lưu ý rằng trường con phải là một phiên bản của CharField , vì phần mở rộng hstore lưu trữ các giá trị dưới
dạng chuỗi.

trường JSON
Một lớp trường xác thực rằng cấu trúc dữ liệu đến bao gồm các nguyên hàm JSON hợp lệ. Ở chế độ nhị phân
thay thế, nó sẽ biểu diễn và xác thực các chuỗi nhị phân được mã hóa JSON.

Chữ ký : JSONField(binary, encoder)

binary - Nếu được đặt thành True thì trường sẽ xuất ra và xác thực chuỗi được mã hóa JSON chứ
không phải cấu trúc dữ liệu nguyên thủy. Mặc định là False .
encoder - Sử dụng bộ mã hóa JSON này để tuần tự hóa đối tượng đầu vào. Mặc định là None .

Các trường khác

trường chỉ đọc
Một lớp trường chỉ trả về giá trị của trường mà không sửa đổi.

Trường này được sử dụng theo mặc định ModelSerializer khi bao gồm các tên trường liên quan đến một
thuộc tính thay vì trường mô hình.

Chữ ký : ReadOnlyField()

Ví dụ: nếu has_expired là một thuộc tính trên Account mô hình thì trình tuần tự hóa sau sẽ tự động tạo
thuộc tính đó dưới dạng ReadOnlyField :

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

Giấu trang
Một lớp trường không nhận giá trị dựa trên đầu vào của người dùng mà thay vào đó lấy giá trị của nó từ giá trị
mặc định hoặc có thể gọi được.

Chữ ký : HiddenField()

Ví dụ: để bao gồm một trường luôn cung cấp thời gian hiện tại như một phần của dữ liệu được xác thực bởi
bộ tuần tự hóa, bạn sẽ sử dụng như sau:
 modified = serializers.HiddenField(default=timezone.now)

Lớp này HiddenField thường chỉ cần thiết nếu bạn có một số xác thực cần chạy dựa trên một số giá trị
trường được cung cấp trước, nhưng bạn không muốn hiển thị tất cả các trường đó cho người dùng cuối.

Để biết thêm ví dụ, HiddenField hãy xem tài liệu về trình xác thực .

Lưu ý: HiddenField() không xuất hiện trong partial=True serializer (khi thực hiện PATCH yêu cầu).
Hành vi này có thể thay đổi trong tương lai, hãy theo dõi thông tin cập nhật về cuộc thảo luận trên github .

trường mẫu
Một trường chung có thể được gắn với bất kỳ trường mô hình tùy ý nào. Lớp này ModelField ủy quyền
nhiệm vụ tuần tự hóa/giải tuần tự hóa cho trường mô hình liên quan của nó. Trường này có thể được sử dụng
để tạo các trường trình tuần tự hóa cho các trường mô hình tùy chỉnh mà không cần phải tạo trường trình
tuần tự hóa tùy chỉnh mới.

Trường này được sử dụng để ModelSerializer tương ứng với các lớp trường mô hình tùy chỉnh.

Chữ ký: ModelField(model_field=<Django ModelField instance>)

Lớp này ModelField thường được thiết kế để sử dụng nội bộ nhưng API của bạn có thể sử dụng nếu cần. Để
khởi tạo chính xác một ModelField , nó phải được chuyển qua một trường được gắn vào một mô hình được
khởi tạo. Ví dụ: ModelField(model_field=MyModel()._meta.get_field('custom_field'))

SerializerMethodField
Đây là trường chỉ đọc. Nó nhận được giá trị bằng cách gọi một phương thức trên lớp serializer mà nó được
gắn vào. Nó có thể được sử dụng để thêm bất kỳ loại dữ liệu nào vào biểu diễn tuần tự của đối tượng của
bạn.

Chữ ký : SerializerMethodField(method_name=None)

method_name - Tên của phương thức trên serializer sẽ được gọi. Nếu không được bao gồm, giá trị mặc
định này là get_<field_name> .

Phương thức serializer được tham chiếu bởi method_name đối số phải chấp nhận một đối số duy nhất (ngoài
self ), đó là đối tượng được tuần tự hóa. Nó sẽ trả về bất cứ thứ gì bạn muốn đưa vào biểu diễn tuần tự của
đối tượng. Ví dụ:

from django.contrib.auth.models import User

from django.utils.timezone import now
from rest_framework import serializers

class UserSerializer(serializers.ModelSerializer):
days_since_joined = serializers.SerializerMethodField()

class Meta:
model = User
 fields = '__all__'

def get_days_since_joined(self, obj):

return (now() - obj.date_joined).days

Trường tùy chỉnh

Nếu muốn tạo trường tùy chỉnh, bạn cần phải phân lớp con Field rồi ghi đè một hoặc cả hai phương thức
.to_representation() and .to_internal_value() . Hai phương thức này được sử dụng để chuyển đổi
giữa kiểu dữ liệu ban đầu và kiểu dữ liệu nguyên thủy, có thể tuần tự hóa. Các kiểu dữ liệu nguyên thủy thường
là bất kỳ số, chuỗi, boolean, date / time / datetime ​hoặc None . Chúng cũng có thể là bất kỳ danh sách
hoặc từ điển nào giống như đối tượng chỉ chứa các đối tượng nguyên thủy khác. Các loại khác có thể được
hỗ trợ, tùy thuộc vào trình kết xuất mà bạn đang sử dụng.

Phương thức này .to_representation() được gọi để chuyển đổi kiểu dữ liệu ban đầu thành kiểu dữ liệu
nguyên thủy, có thể tuần tự hóa.

Phương thức này .to_internal_value() được gọi để khôi phục kiểu dữ liệu nguyên thủy thành biểu diễn
python bên trong của nó. Phương pháp này sẽ đưa ra serializers.ValidationError nếu dữ liệu không
hợp lệ.

Ví dụ

Trường tùy chỉnh cơ bản

Hãy xem một ví dụ về việc tuần tự hóa một lớp đại diện cho giá trị màu RGB:

class Color:
"""
A color represented in the RGB colorspace.
"""
def __init__(self, red, green, blue):
assert(red >= 0 and green >= 0 and blue >= 0)
assert(red < 256 and green < 256 and blue < 256)
self.red, self.green, self.blue = red, green, blue

class ColorField(serializers.Field):
"""
Color objects are serialized into 'rgb(#, #, #)' notation.
"""
def to_representation(self, value):
return "rgb(%d, %d, %d)" % (value.red, value.green, value.blue)

def to_internal_value(self, data):

data = data.strip('rgb(').rstrip(')')
red, green, blue = [int(col) for col in data.split(',')]
return Color(red, green, blue)
Theo mặc định, các giá trị trường được coi là ánh xạ tới một thuộc tính trên đối tượng. Nếu bạn cần tùy chỉnh
cách truy cập và đặt giá trị trường, bạn cần ghi đè .get_attribute() và/hoặc .get_value() .

Ví dụ: hãy tạo một trường có thể được sử dụng để thể hiện tên lớp của đối tượng đang được tuần tự hóa:

class ClassNameField(serializers.Field):
def get_attribute(self, instance):
# We pass the object instance onto `to_representation`,
# not just the field attribute.
return instance

def to_representation(self, value):

"""
Serialize the value's class name.
"""
return value.__class__.__name__

Tăng lỗi xác thực

Lớp của chúng tôi ColorField ở trên hiện không thực hiện bất kỳ xác thực dữ liệu nào. Để chỉ ra dữ liệu
không hợp lệ, chúng ta nên đưa ra serializers.ValidationError , như sau:

def to_internal_value(self, data):

if not isinstance(data, str):
msg = 'Incorrect type. Expected a string, but got %s'
raise ValidationError(msg % type(data).__name__)

if not re.match(r'^rgb\([0-9]+,[0-9]+,[0-9]+\)$', data):

raise ValidationError('Incorrect format. Expected `rgb(#,#,#)`.')

data = data.strip('rgb(').rstrip(')')
red, green, blue = [int(col) for col in data.split(',')]

if any([col > 255 or col < 0 for col in (red, green, blue)]):
raise ValidationError('Value out of range. Must be between 0 and 255.')

return Color(red, green, blue)

Phương thức này .fail() là một lối tắt để nâng cao ValidationError lấy một chuỗi thông báo từ
error_messages từ điển. Ví dụ:

default_error_messages = {
'incorrect_type': 'Incorrect type. Expected a string, but got {input_type}',
'incorrect_format': 'Incorrect format. Expected `rgb(#,#,#)`.',
'out_of_range': 'Value out of range. Must be between 0 and 255.'
}

def to_internal_value(self, data):

 if not isinstance(data, str):
self.fail('incorrect_type', input_type=type(data).__name__)

if not re.match(r'^rgb\([0-9]+,[0-9]+,[0-9]+\)$', data):

self.fail('incorrect_format')

data = data.strip('rgb(').rstrip(')')
red, green, blue = [int(col) for col in data.split(',')]

if any([col > 255 or col < 0 for col in (red, green, blue)]):
self.fail('out_of_range')

return Color(red, green, blue)

Kiểu này giúp thông báo lỗi của bạn sạch hơn và tách biệt hơn với mã của bạn và nên được ưu tiên.

sử dụng source='*'
Ở đây chúng ta sẽ lấy một ví dụ về mô hình phẳng DataPoint có các thuộc tính x_coordinate và
y_coordinate .

class DataPoint(models.Model):
label = models.CharField(max_length=50)
x_coordinate = models.SmallIntegerField()
y_coordinate = models.SmallIntegerField()

Sử dụng trường tùy chỉnh và source='*' chúng tôi có thể cung cấp biểu diễn lồng nhau của cặp tọa độ:

class CoordinateField(serializers.Field):

def to_representation(self, value):

ret = {
"x": value.x_coordinate,
"y": value.y_coordinate
}
return ret

def to_internal_value(self, data):

ret = {
"x_coordinate": data["x"],
"y_coordinate": data["y"],
}
return ret

class DataPointSerializer(serializers.ModelSerializer):
coordinates = CoordinateField(source='*')
 class Meta:
model = DataPoint
fields = ['label', 'coordinates']

Lưu ý rằng ví dụ này không xử lý việc xác thực. Một phần vì lý do đó, trong một dự án thực tế, việc lồng tọa độ
có thể được xử lý tốt hơn bằng trình tuần tự hóa lồng nhau bằng cách sử dụng source='*' , với hai
IntegerField trường hợp, mỗi trường hợp source có điểm riêng đến trường liên quan.

Tuy nhiên, những điểm chính từ ví dụ là:

to_representation được truyền toàn bộ DataPoint đối tượng và phải ánh xạ từ đó đến đầu ra mong
muốn.

>>> instance = DataPoint(label='Example', x_coordinate=1, y_coordinate=2)

>>> out_serializer = DataPointSerializer(instance)
>>> out_serializer.data
ReturnDict([('label', 'Example'), ('coordinates', {'x': 1, 'y': 2})])

Trừ khi trường của chúng tôi ở chế độ chỉ đọc, to_internal_value phải ánh xạ trở lại một lệnh phù hợp
để cập nhật đối tượng mục tiêu của chúng tôi. Với source='*' , trả về từ to_internal_value sẽ cập
nhật từ điển dữ liệu được xác thực gốc, thay vì một khóa duy nhất.

>>> data = {
... "label": "Second Example",
... "coordinates": {
... "x": 3,
... "y": 4,
... }
... }
>>> in_serializer = DataPointSerializer(data=data)
>>> in_serializer.is_valid()
True
>>> in_serializer.validated_data
OrderedDict([('label', 'Second Example'),
('y_coordinate', 4),
('x_coordinate', 3)])

Để hoàn thiện, hãy thực hiện lại điều tương tự nhưng với cách tiếp cận trình tuần tự hóa lồng nhau được đề
xuất ở trên:

class NestedCoordinateSerializer(serializers.Serializer):
x = serializers.IntegerField(source='x_coordinate')
y = serializers.IntegerField(source='y_coordinate')

class DataPointSerializer(serializers.ModelSerializer):
coordinates = NestedCoordinateSerializer(source='*')
 class Meta:
model = DataPoint
fields = ['label', 'coordinates']

Ở đây, việc ánh xạ giữa các cặp thuộc tính đích và nguồn ( x và x_coordinate , y và y_coordinate )
được xử lý trong IntegerField phần khai báo. Đó là của chúng NestedCoordinateSerializer tôi
source='*' .

Tính năng mới của chúng tôi DataPointSerializer thể hiện hành vi tương tự như cách tiếp cận trường tùy
chỉnh.

Tuần tự hóa:

>>> out_serializer = DataPointSerializer(instance)

>>> out_serializer.data
ReturnDict([('label', 'testing'),
('coordinates', OrderedDict([('x', 1), ('y', 2)]))])

Khử lưu huỳnh:

>>> in_serializer = DataPointSerializer(data=data)

>>> in_serializer.is_valid()
True
>>> in_serializer.validated_data
OrderedDict([('label', 'still testing'),
('x_coordinate', 3),
('y_coordinate', 4)])

Nhưng chúng tôi cũng nhận được xác thực tích hợp miễn phí:

>>> invalid_data = {
... "label": "still testing",
... "coordinates": {
... "x": 'a',
... "y": 'b',
... }
... }
>>> invalid_serializer = DataPointSerializer(data=invalid_data)
>>> invalid_serializer.is_valid()
False
>>> invalid_serializer.errors
ReturnDict([('coordinates',
{'x': ['A valid integer is required.'],
'y': ['A valid integer is required.']})])

Vì lý do này, phương pháp tuần tự hóa lồng nhau sẽ là phương pháp đầu tiên được thử. Bạn sẽ sử dụng
phương pháp tiếp cận trường tùy chỉnh khi trình tuần tự hóa lồng nhau trở nên không khả thi hoặc quá phức
tạp.

Gói của bên thứ ba

Các gói bên thứ ba sau đây cũng có sẵn.

Trường hợp chất DRF

Gói drf-comound-fields cung cấp các trường trình tuần tự hóa "kết hợp", chẳng hạn như danh sách các giá trị
đơn giản, có thể được mô tả bằng các trường khác thay vì các trường tuần tự hóa có many=True tùy chọn.
Ngoài ra còn có các trường dành cho từ điển được nhập và các giá trị có thể là một loại cụ thể hoặc một danh
sách các mục thuộc loại đó.

Trường bổ sung DRF

Gói drf-extra-fields cung cấp các trường tuần tự hóa bổ sung cho khung REST, bao gồm
Base64ImageField và PointField các lớp.

djangorestframework-đệ quy
gói đệ quy djangorestframework cung cấp RecursiveField khả năng tuần tự hóa và giải tuần tự hóa các
cấu trúc đệ quy

django-rest-framework-gis
Gói django-rest-framework-gis cung cấp các tiện ích bổ sung địa lý cho khung phần còn lại django như một
GeometryField trường và bộ tuần tự hóa GeoJSON.

django-rest-framework-hstore
Gói django-rest-framework-hstore cung cấp trường mô hình django-hstore HStoreField để hỗ trợ .
DictionaryField

Tài liệu được xây dựng bằng MkDocs .