README

此软件包为 Filament 提供了常见的巴西网络应用程序中使用的自定义表单字段，例如 CPF/CNPJ 验证、电话号码格式化、带有货币符号的金钱以及与 ViaCep 的 CEP 集成。

此软件包使用 LaravelLegends/pt-br-validator 来验证巴西葡萄牙语字段。

安装

您可以通过 Composer 安装此软件包

composer require leandrocfe/filament-ptbr-form-fields:"^3.0"

Filament V2 - 如果您正在使用 Filament v2.x，您可以在此部分使用 找到信息

用法

CPF / CNPJ

要创建一个动态输入，该输入接受 CPF 或 CNPJ，请使用

use Leandrocfe\FilamentPtbrFormFields\Document;
//CPF or CNPJ
Document::make('cpf_or_cnpj')
    ->dynamic()

如果您想创建一个只接受 CPF 或只接受 CNPJ 的输入，请使用

//CPF
Document::make('cpf')
    ->cpf()

//CNPJ
Document::make('cnpj')
    ->cnpj()

如果您想为输入使用自定义掩码，请使用带有表示所需掩码的字符串参数的 cpf() 或 cnpj() 方法

Document::make('cpf')
    ->cpf('999999999-99')

Document::make('cnpj')
    ->cnpj('99999999/9999-99')

验证

Document 默认使用 LaravelLegends/pt-br-validator 来验证巴西葡萄牙语字段 - cpf_ou_cnpj | cpf | cnpj

您可以使用 validation(false) 方法禁用验证

Document::make('cpf_or_cnpj')
    ->validation(false)
    ->dynamic()

Document::make('cpf')
    ->validation(false)
    ->cpf()

电话号码

要创建一个动态输入，该输入带有 DDD 格式化电话号码，请使用

use Leandrocfe\FilamentPtbrFormFields\PhoneNumber;
PhoneNumber::make('phone_number')

如果您想使用自定义的电话号码格式，请使用带有表示所需格式的字符串参数的 `mask()` 方法

PhoneNumber::make('phone_number')
    ->mask('(99) 99999-9999')

PhoneNumber::make('phone_number')
    ->mask('+99 (99) 99999-9999')

金钱

要创建金钱输入字段，请使用以下语法

use Leandrocfe\FilamentPtbrFormFields\Money;
Money::make('price')
    ->default('100,00')

#output: 100.00

这适用于 decimal 或 float 数据类型。

使用整数值

如果您更喜欢使用整数值，您可以使用 intFormat() 方法格式化金钱输入

use Leandrocfe\FilamentPtbrFormFields\Money;
Money::make('price')
    ->default(10000)
    ->intFormat()

#output: 10000

获取原始状态

要检索字段的原始状态，请使用 `dehydratedMask()` 方法

use Leandrocfe\FilamentPtbrFormFields\Money;
Money::make('price')
    ->default('100,00')
    ->dehydrateMask()

#output: 100,00

如果您需要从金钱输入中移除前缀，只需将 null 传递给 prefix() 方法即可

Money::make('price')
    ->prefix(null)

货币格式化

此软件包在底层使用 archtechx/money 软件包。默认情况下，它使用 BRL（巴西雷亚尔）格式来格式化货币值。

如果您想切换到 USD（美国美元）格式，可以使用以下代码

use Leandrocfe\FilamentPtbrFormFields\Currencies\USD;

Money::make('price')
    ->currency(USD::class)
    ->prefix('$')

您还可以定义自定义货币以满足您的特定需求

/*
 * app/Currencies/EUR.php
 */
 
declare(strict_types=1);

namespace App\Currencies;

use ArchTech\Money\Currency;

class EUR extends Currency
{
    /*
     * Code of the currency.
     */
    public string $code = 'EUR';

    /*
     * Name of the currency.
     */
    public string $name = 'Euro';

    /*
     * Rate of this currency relative to the default currency.
     */
    public float $rate = 1.0;

    /*
     * Number of decimals used in money calculations.
     */
    public int $mathDecimals = 2;

    /*
     * Number of decimals used in the formatted value
     */
    public int $displayDecimals = 2;

    /*
     * How many decimals of the currency's values should get rounded
     */
    public int $rounding = 2;

    /*
     * Prefix placed at the beginning of the formatted value.
    */
    public string $prefix = '€';

    /*
     * The language code.
     */
    public string $locale = 'pt';

    /*
     * The character used to separate the decimal values.
     */
    public string $decimalSeparator = '.';

    /*
     * The character used to separate groups of thousands
     */
    public string $thousandsSeparator = ',';
}

use App\Currencies\EUR;

Money::make('price')
->currency(EUR::class)
->prefix('€')

地址

要集成 ViaCep API 以进行 CEP 验证和地址自动完成，请使用

use Leandrocfe\FilamentPtbrFormFields\Cep;
use Filament\Forms\Components\TextInput;
Cep::make('postal_code')
    ->viaCep(
        mode: 'suffix', // Determines whether the action should be appended to (suffix) or prepended to (prefix) the cep field, or not included at all (none).
        errorMessage: 'CEP inválido.', // Error message to display if the CEP is invalid.

        /**
         * Other form fields that can be filled by ViaCep.
         * The key is the name of the Filament input, and the value is the ViaCep attribute that corresponds to it.
         * More information: https://viacep.com.br/
         */
        setFields: [
            'street' => 'logradouro',
            'number' => 'numero',
            'complement' => 'complemento',
            'district' => 'bairro',
            'city' => 'localidade',
            'state' => 'uf'
        ]
    ),

TextInput::make('street'),
TextInput::make('number'),
TextInput::make('complement'),
TextInput::make('district'),
TextInput::make('city'),
TextInput::make('state'),

模式参数指定搜索操作是否附加到或附加到 CEP 字段，使用值 suffix 或 prefix。或者，您可以使用值 none 与 ->live(onBlur: true) 方法来指示其他地址字段仅在 CEP 字段失去焦点时自动填充。

测试

composer test

变更日志

请参阅 CHANGELOG 以获取有关最近更改的更多信息。

贡献

请参阅CONTRIBUTING以获取详细信息。

安全漏洞

如果您在此软件包中发现安全漏洞，请发送电子邮件至leandrocfe@gmail.com。

鸣谢

• Leandro Costa Ferreira
• 所有贡献者

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。