Các trường của form

Subscribe to my newsletter and never miss my upcoming articles

Khi bạn tạo một form trong Django, phần quan trọng nhất là định nghĩa các trường của form này. Mỗi trường có một lôgic xác thực tùy chỉnh cùng với một số hook khác.

Mặc dù cách chính bạn sử dụng trường là trong ngữ cảnh một form, bạn cũng có thể khởi tạo một trường độc lập với form và sử dụng chúng trực tiếp để hiểu rõ hơn về cách chúng hoạt động. Mỗi thực thể của một loại trường có phương thức clean(), phương thức này nhận một đối số duy nhất là dữ liệu thô của trường. Nó trả về hoặc một ngoại lệ django.core.exceptions.ValidationError hoặc một giá trị sau khi đã thực hiện xác thực:

>>> from django import forms

>>>field = forms.EmailField()

>>> field .clean('foo@example.com')
'foo@example.com'
>>> field.clean('invalid email address.')
Traceback (most recent call last):
...
ValidationError: ['Enter a valid email address.']

Các tùy chọn côt lõi khi khởi tạo trường

Đây là các tùy chọn có thể áp dụng cho mọi loại trường.

required

Mặc định là True, tức mọi trường đều bắt buộc phải cung cấp dữ liệu theo mặc định. Nếu bạn truyền giá trị trống gồm None hoặc chuỗi trống "" - thì clean() sẽ tạo ra lỗi ValidationError.

>>> from django import forms
>>> field = forms.CharField()
>>> field.clean('foo')
'foo'
>>> field.clean('')
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> field.clean(None)
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> field.clean(' ')
' '
>>> field.clean(0)
'0'
>>> field.clean(True)
'True'
>>> field.clean(False)
'False'

Cho nên để tạo ra trường không bắt buộc, truyền required=False tới hàm tạo Field:

>>> field = forms.CharField(required=False)
>>> field.clean('')
''
>>> field.clean(None)
''

Với trường dựa trên ký tự, khi dữ liệu là None hoặc '' giá trị trả về là chuỗi trống. Với các loại trường khác, nó có thể là None.

Trong widget của các trường bắt buộc sẽ có thuộc tính HTML required theo mặc định.

label

Nội dung của phần tử <label> trong HTML widget của trường.

label_suffix

Đối số label_suffix của trường sẽ ghi đè tùy chọn label_suffix của form trên một trường cụ thể.

initial

Cung cấp giá trị ban đầu cho trường, sử dụng dùng khi render trường này trong một form không ràng buộc.

Chú ý rằng initial chỉ hiển thị trong biểu mẫu không ràng buộc. Với biểu mẫu bị ràng buộc, dữ liệu ràng buộc sẽ được hiển thị thay vì initial.

widget

Chỉ định widget mà trường này sẽ sử dụng khi render.

help_text

Văn bản mô tả trường, hiển thị ngay bên dưới <input> khi render.

Mặc định giá trị help_text không được escape tự động.

Mặc định, nó được render trong một thẻ <span class="helptext">.

error_messages

Giúp bạn ghi đè các thông báo lỗi mặc định cho mỗi kiểu xác thực mà trường này có. Truyền cho nó một từ điển với khóa phù hợp với kiểu xác thực mà bạn muốn ghi đè và giá trị là thông báo lỗi do tự bạn định nghĩa.

>>> name = forms.CharField(error_messages={'required': 'Please enter your name'})
>>> name.clean('')
Traceback (most recent call last):
...
ValidationError: ['Please enter your name']

validators

Cho phép cung cấp một danh sách các validator cho trường này.

localize

Cho phép bạn bật bản địa hóa cho form input cũng như cho widget HTML.

disabled

Đặt là True nếu bạn muốn vô hiệu hóa trường này sử dụng thuộc tính HTML disabled để nó không thể bị thay đổi bởi người dùng. Thậm chí khi người dùng cố tính loại bỏ thuộc tính disabled bằng cách xem mã nguồn của form để thay đổi giá trị trường và gửi tới máy chủ, Django cũng sẽ bỏ qua giá trị trường này và không cập nhật gì.

Kiểm tra xem trường có bị thay đổi không

Phương thức has_changed() của trường cho phép ta biết được giá trị của trường có bị thay đổi so với giá trị initial hay không. Giá trị trả về của nó là True hoặc False.

Các loại trường có sẵn

BooleanField

  • Widget mặc định: CheckboxInput
  • Giá trị trống: False
  • Kiểu giá trị sau khi xác thực: True hoặc False.
  • Các kiểu xác thực hỗ trợ:
    • required
  • Tên khóa lỗi: 'required'

NullBooleanField

  • Widget mặc định: NullBooleanSelect. Có thể sử dụng với các widget khác như Select hoặc RadioSelect, bằng cách cung cấp đối số choices cho những widget này:
    NullBooleanField(
      widget=Select(
          choices=[
              ('', 'Unknown'),
              (True, 'Yes'),
              (False, 'No'),
          ]
      )
    )
    
  • Giá trị trống: None.
  • Chuyển đổi thành: True, False hoặc None.
  • Không cần xác thực vì nó không bao giờ ném ra lỗi ValidationError.

CharField

  • Widget mặc định: TextInput
  • Giá trị trống: định nghĩa qua đối số empty_value.
  • Kiểu giá trị sau khi xác thực: kiểu chuỗi.
  • Các loại xác thực hỗ trợ:
    • required
    • MaxLengthValidator nếu cung cấp đối số max_length
    • MinLengthValidator nếu cung cấp đối số min_length
  • Tên các khóa lỗi: required, max_length, min_length

Có thêm các đối số tùy chọn sau:

  • max_length: chiều dài tối đa, sử dụng MaxLengthValidator.
  • min_length: chiều dài tối thiểul, sử dụng MinLengthValidator.
  • strip: nếu True, các khoảng trắng ở đầu và cuối bị loại bỏ.
  • empty_value: giá trị đại diện cho giá trị trống. Mặc định là chuỗi trống.

SlugField

  • Widget mặc định: TextInput.
  • Giá trị trống: lấy tử empty_value.
  • Chuyển đổi thành: chuỗi
  • Các loại xác thực hỗ trợ:
    • Mặc định nó sử dụng hàm validate_slug hoặc validate_unicode_slug để xác thực giá trị có đúng là một slug hay không.
  • Tên các khóa lỗi: required, invalid.

Nó có thêm các đối số tùy chọn sau:

  • allow_unicode: cho phép sử dụng các kí tự Unicode. Mặc định là False.
  • empty_value: giá trị đại diện cho giá trị trống. Mặc định là chuỗi trống.

URLField

  • Widget mặc định: URLInput
  • Giá trị trống: lấy từ empty_value.
  • Chuyển đổi thành: chuỗi.
  • Các loại xác thực hỗ trợ:
    • Mặc định sử dụng URLValidator để xác thực.
  • Tên các khóa lỗi: required, invalid.

Có thêm ba đối số bổ sung: max_length, min_lengthempty_value như CharField.

UUIDField

  • Widget mặc định: TextInput.
  • Giá trị trống: None.
  • Chuyển đổi thành: đối tượng UUID.
  • Tên các khóa lỗi: required, invalid.

Chấp nhận thêm đối số: hex để truyền đến hàm tạo UUID.

ChoiceField

  • Widget mặc định: Select
  • Giá trị trống: chuỗi trống.
  • Kiểu giá trị sau khi xác thực: chuỗi
  • Các loại xác thực hỗ trợ:
    • Yêu cầu giá trị phải nằm trong danh sách lựa chọn.
  • Tên các khóa lỗi: required, invalid_choice. Thông báo lỗi của khóa invalid_choice hỗ trợ %(value)s, với value được thay bằng giá trị đã chọn.

Có thêm đối số tùy chọn sau:

  • choices: một đối tượng của thể lặp chứa các tuple 2 phần tử. Định dạng của nó tương tự như choices của một trường trong model.

TypedChoiceField

Giống với ChoiceField nhưng cho phép kiểu giá trị sau khi xác thực có thể là một kiểu khác, không phải chuỗi. Nó cũng cho phép định nghĩa giá trị trống mặc định khác thay cho chuỗi trống.

Nó giống hệt ChoiceField nhưng có thêm hai đối số tùy chọn sau:

  • coerce: hàm nhận vào giá trị của trường sau khi đã xác thực và trả về giá trị đã ép kiểu.
  • emtpy_value: giá trị đại diện cho trường nếu nó bị bỏ trống. Giá trị mặc định là chuỗi trống.

MutipleChoiceField

  • Widget mặc định: SelectMultiple
  • Giá trị trống: []
  • Chuyển đổi thành: danh sách các chuỗi.
  • Các loại xác thực hỗ trợ:
    • Yêu cầu tất cả các giá trị đã chọn đều phải nằm trong danh sách lựa chọn.
  • Tên các khóa lỗi: required, invalid_choice, invalid_list. Lỗi invalid_choice có thể chứa %(value)s, sẽ được thay bằng giá trị đã chọn.

Nó nhận thêm đối số bổ sung là choices giống như ChoiceField.

TypedMultipleChoiceField

Giống như MultipleChoiceField ngoại trừ nó nhận thêm hai đối số bổ sung như TypedChoiceField.

  • coerce
  • empty_value

DateField

  • Widget mặc định: DateInput
  • Giá trị trống: None
  • Kiểu giá trị sau khi xác thực: đối tượng datetime.date
  • Các loại xác thực hỗ trợ:
    • Yêu cầu giá trị phải là chuỗi định dạng đúng kiểu datime.date hoặc datetime.datetime.
  • Tên các khóa lỗi: required, invalid.

Nó chấp nhận thêm các đối số sau:

  • input_formats: danh sách các format được dùng để chuyển đổi chuỗi thành đối tượng datetime.date hợp lệ. Format mặc định được lấy từ DATE_INPUT_FORMATS nếu USE_L10NFalse hoặc từ DATE_INPUT_FORMATS nếu bản địa hóa được bật.

TimeField

  • Widget mặc định: TimeInput
  • Giá trị trống: None.
  • Chuyển đổi thành: datetime.time
  • Các loại xác thực hỗ trợ:
    • Xác thực rằng giá trị là một datetime.time hoặc một chuỗi định dạng hợp lệ.
  • Tên các khóa lỗi: required, invalid.

Chấp nhận các đối số tùy chọn sau:

  • input_formats.

DateTimeField

  • Widget mặc định: DateTimeInput
  • Giá trị trống: None
  • Kiểu giá trị sau khi xác thực: datetime.datetime.
  • Các loại xác thực hỗ trợ:
    • Yêu cầu giá trị phải là chuỗi định dạng đúng kiểu datime.date hoặc datetime.datetime.
  • Tên các khóa lỗi: required, invalid.

Nó chấp nhận thêm các đối số sau:

  • input_formats

IntegerField

  • Widget mặc định: NumberInput nếu không bật bản địa hóa, nếu không thì là TextInput.
  • Giá trị trống: None.
  • Chuyển đổi thành: int.
  • Các loại xác thực hỗ trợ:
    • MaxValueValidator khi sử dụng max_value.
    • MinValueValidator khi sử dụng min_value.
    • Các khoảng trắng ở đầu và cuối bị bỏ qua như khi sử dụng với int() trong Python.
  • Tên các khóa lỗi: required, invalid, max_value, min_value. Các thông báo lỗi của max_valuemin_value có thể tham chiếu tới các giá trị giới hạn bằng %(limit_value)s.

Nó chấp nhận thêm các đối số sau:

  • max_value: giá trị lớn nhất cho phép.
    • min_value: giá trị nhỏ nhất cho phép.

FloatField

  • Widet mặc định: NumberInput nếu không bật bản địa hóa, nếu không thì là TextInput.
  • Giá trị trống: None.
  • Chuyển đổi thành: float.
  • Các loại xác thực hỗ trợ:
    • MaxValueValidator nếu sử dụng max_value.
    • MinValueValidator nếu sử dụng min_value.
    • Các khoảng trắng ở đầu và cuối bị bỏ qua nhưng khi sử dụng với hàm float() trong Python.
  • Tên các khóa lỗi: required, invalid, max_value, min_value.

Nó chấp nhận thêm các đối số sau:

  • max_value: giá trị tối đa cho phép.
  • min_value: giá trị tối thiểu cho phép.

DecimalField

  • Widget mặc định: NumberInput khi không bật bản địa hóa nếu không thì là TextInput.
  • Giá trị trống: None.
  • Kiểu giá trị sau khi xác thực: decimal
  • Các loại xác thực hỗ trợ:
    • required
    • MaxValueValidator nếu có max_value.
    • MinValueValidator nếu có min_value.
    • Các khoảng trắng ở đầu và cuối bị bỏ qua.
  • Tên các khóa lỗi: required, invalid, max_value, min_value, max_digits, max_decimal_places, max_whole_digits. Thông báo lỗi cho max_valuemin_value có thể chứa %(limit_value)s cho biết giá trị giới hạn. Tương tự max_digits, max_decimal_placesmax_whole_digits có thể chứa %(max)s.

Nó nhận thêm các tùy chọn bổ sung sau:

  • max_value: giá trị tối đa cho phép.
  • min_value: giá trị tối thiểu cho phép.
  • max_digits: số chữ số tối đa cho phép.
  • decimal_places: số chữ số thập phân.

DurationField

  • Widget mặc định: TextInput.
  • Giá trị trống mặc định: None.
  • Kiểu giá trị sau khi xác thực: timedelta.
  • Các loại xác thực hỗ trợ:
    • Yêu cầu chuỗi được cung cấp có thể chuyển đổi thành timedelta.
    • Giá trị phải nằm giữa datetime.timedelta.mindatetime.timedelta.max.
  • Tên các khóa lỗi: required, invalid, overflow.

EmailField

  • Widget mặc định: EmailInput
  • Giá trị trống: lấy từ empty_value
  • Chuyển đổi thành: chuỗi
  • Các loại xác thực hỗ trợ:
    • Sử dụng EmailValidator theo mặc định.
  • Tên các khóa lỗi: required, invalid.

Nó chấp nhận thêm các đối số tùy chọn sau:

  • max_length
  • min_length
  • empty_value

FileField

  • Widget mặc định: ClearableFileInput
  • Giá trị trống: None
  • Chuyển đổi thành: đối tượng UploadedFile.
  • Tên các khóa lỗi: required, invalid, missing, empty, max_length. Thông báo lỗi của max_length có thể tham chiếu đến chiều dài của tên file thông qua %(length)d và chiều dài tối đa thông qua %(max)d.

Nó chấp nhận thêm các đối số tùy chọn sau:

  • max_length: chiều dài cực đại của tên file.
  • allow_empty_file: cho phép file có nội dung trống.

ImageField

  • Widget mặc định: ClearableFileInput.
  • Giá trị trống: None.
  • Chuyển đổi thành: đối tượng UploadedFile.
  • Các loại xác thực hỗ trợ:
    • Mặc định nó sử dụng FileExtensionValidator để đảm bảo rằng file phải là ảnh. Xác thực này cần sử dụng thư viên Pillow, nên bạn phải cài đặt nó.
  • Tên các khóa lỗi: required, invalid, missing, empty, invalid_image.

No Comments Yet