Django PhoneNumber Field 使用指南：从模型字段到表单验证

Django PhoneNumber Field 使用指南：从模型字段到表单验证

【免费下载链接】django-phonenumber-field A django model and form field for normalised phone numbers using python-phonenumbers 项目地址: https://gitcode.com/gh_mirrors/dj/django-phonenumber-field

项目概述

Django PhoneNumber Field 是一个专门为 Django 项目设计的电话号码处理扩展，它基于 Google 的 libphonenumber 库，提供了完整的电话号码验证、格式化和存储解决方案。本文将深入解析该库的核心功能和使用方法。

PhoneNumber 包装器

PhoneNumber 类是库的核心，它封装了电话号码的各种操作：

from phonenumber_field.phonenumber import PhoneNumber

# 从字符串创建电话号码对象
number = PhoneNumber.from_string("+16044011234")

# 不同格式输出
print(number.as_national)      # (604) 401-1234
print(number.as_e164)          # +16044011234
print(number.as_international) # +1 604-401-1234
print(number.as_rfc3966)       # tel:+1-604-401-1234

关键方法

• from_string(): 从字符串解析电话号码
• is_valid(): 验证号码有效性
• 多种格式化属性：
  • as_international: 国际格式
  • as_national: 国内格式
  • as_e164: E.164 标准格式
  • as_rfc3966: RFC3966 格式

模型字段 (PhoneNumberField)

在 Django 模型中存储电话号码的最佳实践：

from django.db import models
from phonenumber_field.modelfields import PhoneNumberField

class Customer(models.Model):
    name = models.TextField()
    phone_number = PhoneNumberField(blank=True)  # 可选电话号码

特点

• 基于 CharField 实现
• 数据库存储格式由 PHONENUMBER_DB_FORMAT 设置控制
• 默认表单字段为 PhoneNumberField
• 默认表单部件为 RegionalPhoneNumberWidget

表单字段

PhoneNumberField

基本电话号码表单字段：

from phonenumber_field.formfields import PhoneNumberField

class PhoneForm(forms.Form):
    number = PhoneNumberField(region="CA")  # 指定加拿大地区

特性

• 默认使用 RegionalPhoneNumberWidget
• 空值处理为 ""
• 标准化为 PhoneNumber 对象
• 使用 validate_international_phonenumber 验证器

SplitPhoneNumberField

拆分式电话号码字段，包含国家/地区选择框和号码输入框：

from phonenumber_field.formfields import SplitPhoneNumberField

class PhoneForm(forms.Form):
    number = SplitPhoneNumberField()

自定义选项

1. 限制国家选择:

class DemoSplitPhoneNumberField(SplitPhoneNumberField):
    def prefix_field(self):
        return forms.ChoiceField(choices=[
            ("", "---------"),
            ("CA", "Canada"),
            ("FR", "France"),
        ])

2. 预设国家:

number = DemoSplitPhoneNumberField(region="FR")  # 预设法国

3. 自定义部件属性:

def number_field(self):
    number_field = super().number_field()
    number_field.widget.attrs["class"] = "form-control"
    return number_field

表单部件

RegionalPhoneNumberWidget

默认的电话号码输入部件：

• 输入类型为 tel
• 渲染为 <input type="tel">
• 需要指定地区才能识别国内号码格式

PhoneNumberPrefixWidget

带国家/地区前缀的选择部件，通常与 SplitPhoneNumberField 配合使用。

序列化字段

用于 Django REST framework 的电话号码序列化：

from phonenumber_field.serializerfields import PhoneNumberField

class PhoneNumberSerializer(serializers.Serializer):
    number = PhoneNumberField(region="CA")

序列化格式由 PHONENUMBER_DEFAULT_FORMAT 设置控制。

验证器

核心验证函数 validate_international_phonenumber 可以验证：

• PhoneNumber 实例
• 国际格式的字符串（带前缀）
• 根据 PHONENUMBER_DEFAULT_REGION 的本地电话号码

重要设置

电话号码格式选项

设置值	国际格式	支持分机	说明
E164 (默认)	✓	❌	国际电信编号计划
INTERNATIONAL	✓	✓	E.123 电话编号
RFC3966	✓	✓	RFC 3966 标准
NATIONAL	❌	✓	需要指定默认地区

关键设置项

1. PHONENUMBER_DB_FORMAT

   • 控制数据库存储格式
   • 默认: "E164"
   • 警告：更改可能导致数据丢失

2. PHONENUMBER_DEFAULT_FORMAT

   • 控制电话号码的字符串格式
   • 默认: "E164"

3. PHONENUMBER_DEFAULT_REGION

   • ISO-3166-1 两位国家代码
   • 用于解释地区电话号码
   • 默认: None

最佳实践

1. 始终考虑国际电话号码的多样性
2. 对于需要分机号的应用，避免使用 E164 格式
3. 明确指定地区以避免歧义
4. 在更改数据库格式前备份数据
5. 考虑使用 SplitPhoneNumberField 提升用户体验

通过合理配置和使用 Django PhoneNumber Field，开发者可以轻松处理全球电话号码的各种需求，确保数据的准确性和一致性。

【免费下载链接】django-phonenumber-field A django model and form field for normalised phone numbers using python-phonenumbers 项目地址: https://gitcode.com/gh_mirrors/dj/django-phonenumber-field