编写自定义模型字段

我们的示例对象

创建自定义字段要求注意一些细节。为了简化问题，我们在本文档中全程使用同一实例：封装一个 Python 对象，代表手上 桥牌 的细节。不要担心，你不需要知道如何玩桥牌就能学习此例子。你只需知道 52 张牌被均分给 4 个玩家，一般称他们 北，东，南 和 西。我们的类长这样:

class Hand:
    """A hand of cards (bridge style)"""

    def __init__(self, north, east, south, west):
        # Input parameters are lists of cards ('Ah', '9s', etc.)
        self.north = north
        self.east = east
        self.south = south
        self.west = west

    # ... (other possibly useful methods omitted) ...

这是一个一般的 Python 类，其中没有特殊的 Django 内容。我们期望在我们的模块中做如下操作 (我们假设模型中的 hand 属性是 Hand 的一个实例):

example = MyModel.objects.get(pk=1)
print(example.hand.north)

new_hand = Hand(north, east, south, west)
example.hand = new_hand
example.save()

对模型中的 hand 属性的赋值与取值操作与其它 Python 类一直。技巧是告诉 Django 如何保存和加载对象。

为了在模型中使用 Hand 类，我们 不 需要修改这个类。这很不错，因为这以为着你仅需为已存在的类编写模型支持，即便你不能修改源码。

数据库存储

让我们从模型字段开始吧。把它们分开来看，一个模型字段可以在处理数据库时，提供处理一般 Python 对象的方法（字符串，布尔值， datetime ，或像 Hand 这样更复杂的类型），并将其转换成有用的格式。（对序列化而言这种格式是很有用的，但接下来我们会看到，如果数据库端处于控制之下，序列化会更简单）

模型中的字段必须能以某种方式转换为已存在的数据库列类型。不能的数据库提供不同的可用列类型集，但规则仍相同：你只需要处理这些类型。你想存在数据库中的任何数据都必须能适配这些类型中的某一个。

一般地讲，您要么编写一个 Django 字段来匹配特定的数据库列类型，要么需要一种方法将数据转换为字符串。

For our Hand example, we could convert the card data to a string of 104 characters by concatenating all the cards together in a predetermined order -- say, all the north cards first, then the east, south and west cards. So Hand objects can be saved to text or character columns in the database.

一个字段(Field)类做了什么？

所有的 Django 字段（本页提到的 字段 均指模型字段，而不是 表单字段）都是 django.db.models.Field 的子类。对于所有字段，Django 记录的大部分信息是一样的——名字，帮助文本，是否唯一，等等。存储行为由 Field 处理。稍后，我们会深入了解 Field 能做什么；现在， 可以说万物源于 Field，并在其基础上自定义了类的关键行为。

了解 Django 字段类不保存在模型属性中很重要。模型属性包含普通的 Python 对象。你所以定义的字段类实际上在模型类创建时在 Meta 类中（这是如何实现的在这里不重要）。这是因为在仅创建和修改属性时，字段类不是必须的。相反，他们提供了属性值间转换的机制，并决定了什么被存入数据库或发送给 序列化器。

在你创建自定义字段时牢记这点。你所写的 Django 的 Field 子类提供了多种在 Python 实例和数据库/序列化器之间的转换机制（比如，保存值和使用值进行查询之间是不同的）。听起来有点迷糊，但别担心——通过以下的例子会清晰起来。只要记住，在你需要一个自定义字段时，只需创建两个类：

• 第一个类是用户需要操作的 Python 对象。它们会复制给模型属性，它们会为了显示而读取属性，就想这样。这里本例中的 Hand 类。
• 第二类是 Field 的子类。这个类知道如何在永久存储格式和 Python 格式之间来回转换。

备注

许多 Django 模型字段可以接受并没有什么用的可选参数。比如，你可以同时将 auto_now 和:attr:~django.db.models.DateField.auto_now 传递给 django.db.models.DateField ，它将无视参数 editable （auto_now 被设置了就意味着 editable=False）。这种情况下不会抛出错误。

这种行为简化了字段类，因为它不需要检查那些没必要出现的可选参数。它们传递所有可选参数到父类，之后就不再使用它们了。您可以更严格地设置字段可选参数，或者对当前字段设置更放任的行为，一切都有您来决定。

字段解析

The counterpoint to writing your __init__() method is writing the deconstruct() method. It's used during model migrations to tell Django how to take an instance of your new field and reduce it to a serialized form - in particular, what arguments to pass to __init__() to recreate it.

如果你未在继承的字段之前添加任何选项，就不需要编写新的 deconstruct() 方法。然而，如果你正在修改传递给 __init__() 的参数（像 HandField 中的一样），你需要增补被传递的值。

deconstruct() 返回包含 4 个项目的元组：字段的属性名，字段类的完整导入路径，位置参数（以列表的形式），和关键字参数（以字典的形式）。注意，这与 为自定义类 的 deconstruct() 方法不同，它返回包含 3个项目的元组。

作为自定义字段的作者，你不需要担心前两个值；基类 Field 已包含处理字段属性名和导入路径的代码。然后，你仍必须关注位置参数和关键字参数，这些是你最有可能改的东西。

例如，在 HandField 类中，我们总是强制设置 __init__() 的长度。基类 Field 中的 deconstruct() 方法会看到这个值，并尝试在关键字参数中返回它；因此，我们能为了可读性从关键字参数中剔除它:

from django.db import models

class HandField(models.Field):

    def __init__(self, *args, **kwargs):
        kwargs['max_length'] = 104
        super().__init__(*args, **kwargs)

    def deconstruct(self):
        name, path, args, kwargs = super().deconstruct()
        del kwargs["max_length"]
        return name, path, args, kwargs

若你添加了一个新的关键字参数，你需要在 deconstruct 中新增代码，将其值传入 kwargs。如果不需要字段的重构状态，比如使用默认值的情况，还应该忽略 kwargs 中的值。

from django.db import models

class CommaSepField(models.Field):
    "Implements comma-separated storage of lists"

    def __init__(self, separator=",", *args, **kwargs):
        self.separator = separator
        super().__init__(*args, **kwargs)

    def deconstruct(self):
        name, path, args, kwargs = super().deconstruct()
        # Only include kwarg if it's not the default
        if self.separator != ",":
            kwargs['separator'] = self.separator
        return name, path, args, kwargs

更多的复杂例子超出本文的范围，但是请牢记——对于你的字段实例的任意配置，deconstruct() 必须返回能传递给 __init__ 的参数重构状态。

如果你在父类 Field 中设置了新的默认值需要额外注意；说明你希望总是包含它们，而不是在它们采用旧有值时消失。

另外，应当避免用位置参数来返回值，尽可能用关键字参数来返回值以保证在未来能拥有最大的兼容性。如果您在构造方法参数列表中修改参数名称比修改其位置更频繁，您可能会更喜欢位置参数，但请记住，在相当长的一段时间内（也许几年），人们将从序列化版本中重新构建您的字段，这取决于您迁移持续的时间。

您可以在包含字段的迁移文件里查看解析的结果，此外您可以在单元测试中通过解构和重构字段来测试。

name, path, args, kwargs = my_field_instance.deconstruct()
new_instance = MyField(*args, **kwargs)
self.assertEqual(my_field_instance.some_attribute, new_instance.some_attribute)

Field attributes not affecting database column definition

You can override Field.non_db_attrs to customize attributes of a field that don't affect a column definition. It's used during model migrations to detect no-op AlterField operations.

例子:

class CommaSepField(models.Field):

    @property
    def non_db_attrs(self):
        return super().non_db_attrs + ("separator",)

修改自定义字段的基类

你可能修改自定义字段的基类，因为 Django 无法检测到修改，并为其实施迁移。例如，如果你先这样:

class CustomCharField(models.CharField):
    ...

随后决定继承自 TextField，你不能像这样修改子类:

class CustomCharField(models.TextField):
    ...

替代方法是，你必须新建一个自定义字段类，并将你的模型指向此类:

class CustomCharField(models.CharField):
    ...

class CustomTextField(models.TextField):
    ...

就像文档 移除字段 中讨论的一样，你必须保留原 CustomCharField 类只要你还有迁移指向它。

为自定义字段编写文档

像之前一样，你需要为自定义字段类型编写文档，这样用户就会知道这他喵到底是啥。除了为其提供对开发者很有用的 docstring 外，你也需要让后台管理员应用程序的用户通过应用程序 django.contrib.admindocs 1 看到一个关于字段类型的简单介绍。只需在自定义字段的 description 属性提供描述性文本。在上述例子中，由 admindocs 应用为 HandField 字段提供的描述是 'A hand of cards (bridge style)'。

在 django.contrib.admindocs 展示的内容中，字段描述在 field.__dict__ 中差值，它允许描述包含字段参数。例如， CharField 的说明是:

description = _("String (up to %(max_length)s)")

实用方法

一旦你已创建了 Field 的子类，你可能会考虑重写一些标准方法，这取决于你的字段行为。以下列表中的方法大致按重要性降序排列，即从上至下。

from django.db import models

class MytypeField(models.Field):
    def db_type(self, connection):
        return 'mytype'

class Person(models.Model):
    name = models.CharField(max_length=80)
    something_else = MytypeField()

class MyDateField(models.Field):
    def db_type(self, connection):
        if connection.vendor == 'mysql':
            return 'datetime'
        else:
            return 'timestamp'

# This is a silly example of hard-coded parameters.
class CharMaxlength25Field(models.Field):
    def db_type(self, connection):
        return 'char(25)'

# In the model:
class MyModel(models.Model):
    # ...
    my_field = CharMaxlength25Field()

# This is a much more flexible example.
class BetterCharField(models.Field):
    def __init__(self, max_length, *args, **kwargs):
        self.max_length = max_length
        super().__init__(*args, **kwargs)

    def db_type(self, connection):
        return 'char(%s)' % self.max_length

# In the model:
class MyModel(models.Model):
    # ...
    my_field = BetterCharField(25)

# MySQL unsigned integer (range 0 to 4294967295).
class UnsignedAutoField(models.AutoField):
    def db_type(self, connection):
        return 'integer UNSIGNED AUTO_INCREMENT'

    def rel_db_type(self, connection):
        return 'integer UNSIGNED'

import re

from django.core.exceptions import ValidationError
from django.db import models
from django.utils.translation import gettext_lazy as _

def parse_hand(hand_string):
    """Takes a string of cards and splits into a full hand."""
    p1 = re.compile('.{26}')
    p2 = re.compile('..')
    args = [p2.findall(x) for x in p1.findall(hand_string)]
    if len(args) != 4:
        raise ValidationError(_("Invalid input for a Hand instance"))
    return Hand(*args)

class HandField(models.Field):
    # ...

    def from_db_value(self, value, expression, connection):
        if value is None:
            return value
        return parse_hand(value)

    def to_python(self, value):
        if isinstance(value, Hand):
            return value

        if value is None:
            return value

        return parse_hand(value)

class HandField(models.Field):
    # ...

    def get_prep_value(self, value):
        return ''.join([''.join(l) for l in (value.north,
                value.east, value.south, value.west)])

def get_db_prep_value(self, value, connection, prepared=False):
    value = super().get_db_prep_value(value, connection, prepared)
    if value is not None:
        return connection.Database.Binary(value)
    return value

class HandField(models.Field):
    # ...

    def formfield(self, **kwargs):
        # This is a fairly standard way to set up some defaults
        # while letting the caller override them.
        defaults = {'form_class': MyFormField}
        defaults.update(kwargs)
        return super().formfield(**defaults)

class HandField(models.Field):
    # ...

    def get_internal_type(self):
        return 'CharField'

class HandField(models.Field):
    # ...

    def value_to_string(self, obj):
        value = self.value_from_object(obj)
        return self.get_prep_value(value)

一些通用建议

编写自定义字段是个棘手的，尤其是在 Python 类，数据库，序列化格式之间进行复杂转换的时候。下面有几个让事情更顺利的建议：

1. 借鉴已有的 Django 字段（位于 django/db/models/fields/__init__.py）。试着找到一个与你目标类似的字段，而不是从零开始创建。
2. 为字段类添加一个 __str__() 方法。在很多地方，字段代码的默认行为是对值调用 str()。（本页文档中， value 会是一个 Hand 实例，而不是 HandField）。所以 __str()__ 方法会自动将 Python 对象转为字符串格式，帮你剩下不少时间。

一些建议

除了上述细节，下面还有一些准则，有助于极大地提高字段代码的效率和可读性。

1. Django 的 ImageField 的源码（位于 django/db/models/fields/files.py）就是个展示如何继承 FileField 支持特定文件的不错例子，因为它包含了上述所有技巧。
2. 尽可能的缓存文件属性。因为文件可能保存在远端存储系统中，检出它们会消耗额外的时间，甚至是钱，且不总是必要的。一旦检出某个文件，获取其内容，尽可能缓存所有数据，以减少后续调用再次检索文件的次数。