nepada/phone-number-input

Nette表单的号码输入表单。

v1.3.1 2023-12-02 02:40 UTC

README

Build Status Coverage Status Downloads this Month Latest stable

安装

通过Composer

$ composer require nepada/phone-number-input

选项A:通过DI扩展安装表单容器扩展方法

extensions:
    - Nepada\Bridges\PhoneNumberInputDI\PhoneNumberInputExtension

它将注册扩展方法 addPhoneNumber($name, $label = null, ?string $defaultRegionCode = null): PhoneNumberInputNette\Forms\Container

选项B:在基础表单/容器类中使用特性

您还可以在基础表单/容器类中使用 PhoneNumberInputMixin 特性来添加方法 addPhoneNumber($name, $label = null, ?string $defaultRegionCode = null): PhoneNumberInput

示例

trait FormControls
{

    use Nepada\Bridges\PhoneNumberInputForms\PhoneNumberInputMixin;

    public function addContainer($name)
    {
        $control = new Container;
        $control->setCurrentGroup($this->getCurrentGroup());
        if ($this->currentGroup !== null) {
            $this->currentGroup->add($control);
        }
        return $this[$name] = $control;
    }

}

class Container extends Nette\Forms\Container
{

    use FormControls;

}

class Form extends Nette\Forms\Form
{

    use FormControls;

}

用法

PhoneNumberInput 是一个表单控件,它使用电话号码值对象来表示其值(有关详细信息,请参阅 brick/phonenumber)。它自动验证用户输入,并且 getValue() 方法始终返回 PhoneNumber 实例,或者如果输入未填写,则返回 null

$PhoneNumberInput = $form->addPhoneNumber('phone');
$PhoneNumberInput->setValue('invalid'); // \InvalidArgumentException is thrown
$PhoneNumberInput->setValue('+420 212 345 678'); // the value is internally converted to PhoneNumber value object
$PhoneNumberInput->getValue(); // PhoneNumber instance for +420212345678 

验证

默认验证相对宽松 - 它仅基于解析的区域和号码长度执行基本检查。

严格验证

您可以添加一个更严格的验证规则 PhoneNumberInput::VALID_STRICT。此规则将内容与元数据数据库中的正则表达式进行验证。

警告:您必须确保您已经安装了最新的元数据库,否则您在验证过程中可能会遇到误报和漏报。元数据由 giggsey/libphonenumber-for-php 提供,用于后端验证,以及 libphonenumber-js 用于客户端验证。

区域验证

您可以限制输入只接受来自特定区域(s)的号码。

// Specify one or more ISO 3166-1 alpha-2 country codes
$input->addRule(PhoneNumberInput::REGION, 'Only US phone numbers are allowed', 'US');
$input->addRule(PhoneNumberInput::REGION, 'Only Czech and Slovak phone numbers are allowed', ['CZ', 'SK']);

默认区域代码

在创建输入时,您可以指定默认区域代码(ISO 3166-1 alpha-2国家代码),例如 $form->addPhoneNumber('phone', 'Phone', 'CZ')。这有两个效果

  1. 用户可以在输入字段中省略该区域的区号前缀,例如 212 345 678 被解释为 +420 212 345 678
  2. 当渲染输入时,该区域的电话号码将显示为国家格式,而不是国际格式,即省略国家代码。

客户端验证

此软件包包含基于 libphonenumber-js 的客户端验证。它作为npm软件包 @nepada/phone-number-input 发布。

libphonenumber-js 提供了几个 不同的元数据集。您应根据自己的验证需求选择一个(例如,如果您不需要严格验证,请选择 min),或构建自己的自定义元数据集。

使用预编译包

使用预编译包是快速地将客户端验证投入使用的简便方法。

<script src="https://unpkg.com/libphonenumber-js@%5E1.7/bundle/libphonenumber-max.js"></script>
<!--
OR
<script src="https://unpkg.com/libphonenumber-js@%5E1.7/bundle/libphonenumber-min.js"></script>
OR
<script src="https://unpkg.com/libphonenumber-js@%5E1.7/bundle/libphonenumber-mobile.js"></script>
-->
<script src="https://unpkg.com/nette-forms@%5E3.0/src/assets/netteForms.min.js"></script>
<script src="https://unpkg.com/@nepada/phone-number-input@%5E1.0/dist/phone-number-input.min.js"></script>

构建自己的包

强烈建议您通过nmp安装客户端包并编译自己的包。这样,您可以使用前面提到的自定义元数据集。

以下是一个用于初始化电话号码输入和Nette表单的示例脚本。

import Nette from 'nette-forms';
import initializePhoneNumberInput from '@nepada/phone-number-input';
import metadata from 'libphonenumber-js/metadata.full';
// OR
// import metadata from 'libphonenumber-js/metadata.min';
// OR
// import metadata from 'libphonenumber-js/metadata.mobile';
// OR
// import metadata from './metadata.custom.js';

initializePhoneNumberInput(Nette, metadata);
Nette.initOnLoad();