README

电话号码

此插件为Craft添加了一个新字段类型，用于输入和验证国际电话号码，并获取有关这些号码的信息。还提供了一个Twig扩展，用于从文本中提取号码。

它是基于优秀的 libphonenumber-for-php，这是Google的 libphonenumber 库的端口。

特性

用于输入和验证国际电话号码的字段类型。
支持查询和突变电话号码字段GraphQL。
支持字段和元素条件规则。
用于从文本中提取号码的Twig过滤器。

要求

此插件需要Craft CMS 5.0.0或更高版本。

安装

您可以从插件商店或使用Composer安装此插件。

从插件商店

转到您项目控制面板中的插件商店，搜索“电话号码”。然后在模态窗口中点击“安装”按钮。

使用Composer

打开您的终端并运行以下命令

# Go to the project directory
cd /path/to/project

# Tell Composer to load the plugin
composer require rynpsc/craft-phone-number

# Tell Craft to install the plugin
./craft install/plugin phone-number

字段类型

电话号码字段提供了一个轻松解析、格式化、存储和验证国际电话号码的方法。

处理电话号码字段数据

电话号码字段返回一个PhoneNumberModel。

调用以下任何一项之前，请确保字段值不为null。为了简洁，示例中省略了此检查。

{% if entry.fieldHandle %}
  {{ entry.fieldHandle.region }}
{% endif %}

region

字段中输入的原始区域代码。

{{ entry.fieldHandle.region }}

number

字段中输入的原始号码。

{{ entry.fieldHandle.number }}

getCountryCode()

数值国家代码。

{{ entry.fieldHandle.getCountryCode() }}

getRegionCode()

字母区域代码。

{{ entry.fieldHandle.getRegionCode() }}

getLink()

返回电话号码链接，请参阅链接。

{{ entry.fieldHandle.getLink() }}

getType()

返回号码类型。

{{ entry.fieldHandle.getType() }}

号码类型以整数形式返回。

getDescription(locale, region)

返回在提供的区域中号码的描述。

返回的描述可能包括国家的名称，或电话号码来自的地理区域的名称。

如果提供了region，它也将被考虑。如果电话号码来自同一区域，则只返回较低级别的描述。

{# Manchester #}
{{ entry.fieldHandle.getDescription('en-GB') }}

{# Manchester #}
{{ entry.fieldHandle.getDescription('en-GB', 'GB') }}

{# United Kingdom #}
{{ entry.fieldHandle.getDescription('en-GB', 'US') }}

getTimeZones()

返回一个电话号码所属时区的数组。

{{ entry.fieldHandle.getTimeZones() }}

format(format)

格式化电话号码。

{{ entry.fieldHandle.format('international') }}

号码可以按以下格式进行格式化

rfc3966格式也通过tel别名提供。

formatForCountry(region)

根据region格式化电话号码。

{{ entry.fieldHandle.formatForCountry('GB') }}

formatForMobileDialing(region, withFormatting)

以可以从提供的region拨打的方式格式化电话号码。withFormatting参数确定是否对号码应用了格式。

{{ entry.fieldHandle.formatForMobileDialing() }}

查询具有电话号码字段的元素

当查询具有电话号码字段的元素时，您可以使用以您的字段处理程序命名的查询参数根据电话号码字段数据过滤结果。

可能的值包括

{% set entries = craft.entries()
  .phone({ region: ['GB'] })
  .all() %}

保存电话号码字段

如果您有一个需要包含电话号码字段的表单元素，例如一个表单，您需要提交包含区域和号码输入的字段。

<select name="fields[fieldHandle][region]">
  {% for region in craft.phoneNumber.getAllSupportedRegions() %}
      <option value="{{ region.countryCode }}">{{ region.countryName }}</option>
  {% endfor %} 
</select>

<input name="fields[fieldHandle][number]">

Twig 过滤器

tel 过滤器可以从字符串中提取电话号码，并将它们转换为链接，使用号码作为链接文本。

{{ entry.text|tel }}

默认情况下，只有带有区域代码的数字，例如+44，会被转换。要转换没有区域代码的数字，可以在解析时传递一个默认国家代码。

{{ entry.text|tel('GB') }}

链接

两者getLink()方法以及tel过滤器都支持设置生成的链接内容和HTML属性。

属性设置遵循yii\helpers\BaseHtml::renderTagAttributes()。

{{ entry.phoneFieldHandle.getLink({
  class: 'my-class'
}) }}

{{ entry.textFieldHandle|tel(null, {
  class: 'my-class'
}) }}

如果text包含在属性参数中，其值将被HTML编码并设置为链接的文本内容。

{{ entry.phoneFieldHandle.getLink({
  text: 'Content'
}) }}

{{ entry.textField|tel(null, {
  text: 'Content'
}) }}

如果html包含在属性参数中，其值将被设置为链接的内部HTML（不进行HTML编码）。

{{ entry.phoneFieldHandle.getLink({
  html: '<div>Content</div>'
}) }}

{{ entry.textField|tel(null, {
  html: '<div>Content</div>'
}) }}

rynpsc / craft-phone-number

维护者

详情