文本输入

简介

文本输入允许你与字符串交互：

php

use Filament\Forms\Components\TextInput;

TextInput::make('name')

设置 HTML 输入类型

可用一组方法设置字符串类型。其中如 email() 还会提供校验：

php

use Filament\Forms\Components\TextInput;

TextInput::make('text')
    ->email() // or
    ->numeric() // or
    ->integer() // or
    ->password() // or
    ->tel() // or
    ->url()

也可改用 type() 方法传入其他 HTML 输入类型：

php

use Filament\Forms\Components\TextInput;

TextInput::make('backgroundColor')
    ->type('color')

各类型方法也允许传入布尔值，控制字段是否采用该类型：

php

use Filament\Forms\Components\TextInput;

TextInput::make('text')
    ->email(FeatureFlag::active()) // or
    ->numeric(FeatureFlag::active()) // or
    ->integer(FeatureFlag::active()) // or
    ->password(FeatureFlag::active()) // or
    ->tel(FeatureFlag::active()) // or
    ->url(FeatureFlag::active())

TIP

除静态值外，这些方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

设置 HTML 输入模式

可用 inputMode() 方法设置输入框的 inputmode 属性：

php

use Filament\Forms\Components\TextInput;

TextInput::make('text')
    ->numeric()
    ->inputMode('decimal')

TIP

除静态值外，inputMode() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

设置数值步进

可用 step() 方法设置输入框的 step 属性：

php

use Filament\Forms\Components\TextInput;

TextInput::make('number')
    ->numeric()
    ->step(100)

TIP

除静态值外，step() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

自动完成文本

可用 autocomplete() 方法允许浏览器自动完成文本：

php

use Filament\Forms\Components\TextInput;

TextInput::make('password')
    ->password()
    ->autocomplete('new-password')

作为 autocomplete="off" 的快捷方式，可使用 autocomplete(false)：

php

use Filament\Forms\Components\TextInput;

TextInput::make('password')
    ->password()
    ->autocomplete(false)

TIP

除静态值外，autocomplete() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

对于更复杂的自动完成选项，文本输入还支持 datalist。

使用 datalist 自动完成文本

可用 datalist() 方法为文本输入指定 datalist 选项：

php

TextInput::make('manufacturer')
    ->datalist([
        'BMW',
        'Ford',
        'Mercedes-Benz',
        'Porsche',
        'Toyota',
        'Volkswagen',
    ])

Datalist 会在用户使用文本输入时提供自动完成选项。但这些只是建议，用户仍可输入任意值。若要严格限制为预定义选项，请参阅选择字段。

TIP

除静态值外，datalist() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

自动大写文本

可用 autocapitalize() 方法允许浏览器自动大写文本：

php

use Filament\Forms\Components\TextInput;

TextInput::make('name')
    ->autocapitalize('words')

TIP

除静态值外，autocapitalize() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

在字段旁添加前后缀文本

可用 prefix() 和 suffix() 方法在输入框前后放置文本：

php

use Filament\Forms\Components\TextInput;

TextInput::make('domain')
    ->prefix('https://')
    ->suffix('.com')

TIP

除静态值外，prefix() 和 suffix() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

使用图标作为前后缀

可用 prefixIcon() 和 suffixIcon() 方法在输入框前后放置图标：

php

use Filament\Forms\Components\TextInput;
use Filament\Support\Icons\Heroicon;

TextInput::make('domain')
    ->url()
    ->suffixIcon(Heroicon::GlobeAlt)

TIP

除静态值外，prefixIcon() 和 suffixIcon() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

设置前后缀图标颜色

前后缀图标默认为灰色，可用 prefixIconColor() 和 suffixIconColor() 方法设置其他颜色：

php

use Filament\Forms\Components\TextInput;
use Filament\Support\Icons\Heroicon;

TextInput::make('domain')
    ->url()
    ->suffixIcon(Heroicon::CheckCircle)
    ->suffixIconColor('success')

TIP

除静态值外，prefixIconColor() 和 suffixIconColor() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

使用操作作为前后缀

可用 prefixAction() 和 suffixAction() 方法在输入框前后放置操作：

php

use Filament\Actions\Action;
use Filament\Forms\Components\TextInput;
use Filament\Support\Icons\Heroicon;

TextInput::make('cost')
    ->prefix('€')
    ->suffixAction(
        Action::make('copyCostToPrice')
            ->icon(Heroicon::Clipboard),
    )

可显示的密码输入

使用 password() 时，还可将输入设为 revealable()，用户点击按钮即可查看正在输入的明文密码：

php

use Filament\Forms\Components\TextInput;

TextInput::make('password')
    ->password()
    ->revealable()

也可传入布尔值，控制输入是否可显示：

php

use Filament\Forms\Components\TextInput;

TextInput::make('password')
    ->password()
    ->revealable(FeatureFlag::active())

TIP

除静态值外，revealable() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

允许将文本复制到剪贴板

可将文本设为可复制：点击输入框旁的按钮会将文本复制到剪贴板，并可选择指定自定义确认消息及显示时长（毫秒）：

php

use Filament\Forms\Components\TextInput;

TextInput::make('apiKey')
    ->label('API key')
    ->copyable(copyMessage: 'Copied!', copyMessageDuration: 1500)

也可传入布尔值，控制文本是否可复制：

php

use Filament\Forms\Components\TextInput;

TextInput::make('apiKey')
    ->label('API key')
    ->copyable(FeatureFlag::active())

TIP

除静态值外，copyable() 方法的参数也接受函数以动态计算。可将各种工具注入该函数作为参数。

WARNING

此功能仅在应用启用 SSL 时可用。

输入掩码

输入掩码是定义输入值必须符合的格式的做法。

在 Filament 中，可用 mask() 方法配置 Alpine.js 掩码：

php

use Filament\Forms\Components\TextInput;

TextInput::make('birthday')
    ->mask('99/99/9999')
    ->placeholder('MM/DD/YYYY')

要使用动态掩码，请将 JavaScript 包裹在 RawJs 对象中：

php

use Filament\Forms\Components\TextInput;
use Filament\Support\RawJs;

TextInput::make('cardNumber')
    ->mask(RawJs::make(<<<'JS'
        $input.startsWith('34') || $input.startsWith('37') ? '9999 999999 99999' : '9999 9999 9999 9999'
    JS))

TIP

除静态值外，mask() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

Alpine.js 会将完整掩码值发送到服务器，因此在校验并保存字段前，可能需要从状态中剥离某些字符。可用 stripCharacters() 方法，传入要从掩码值中移除的字符或字符数组：

php

use Filament\Forms\Components\TextInput;
use Filament\Support\RawJs;

TextInput::make('amount')
    ->mask(RawJs::make('$money($input)'))
    ->stripCharacters(',')
    ->numeric()

TIP

除静态值外，stripCharacters() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

修剪空白

可用 trim() 方法自动修剪输入值首尾的空白：

php

use Filament\Forms\Components\TextInput;

TextInput::make('name')
    ->trim()

若希望对所有文本输入全局启用修剪（类似 Laravel 的 TrimStrings 中间件），可在服务提供者中使用 configureUsing() 方法：

php

use Filament\Forms\Components\TextInput;

TextInput::configureUsing(function (TextInput $component): void {
    $component->trim();
});

使字段只读

请勿与禁用字段混淆，可用 readOnly() 方法将字段设为「只读」：

php

use Filament\Forms\Components\TextInput;

TextInput::make('name')
    ->readOnly()

与 disabled() 相比有几点不同：

使用 `readOnly()` 时，提交表单仍会将该字段发送到服务器。可通过浏览器控制台或 JavaScript 修改。可用 [`saved(false)`](/5.x/forms/overview#preventing-a-field-from-being-saved) 阻止保存。
使用 `readOnly()` 时没有样式变化（如降低透明度）。
使用 `readOnly()` 时字段仍可聚焦。

也可传入布尔值，控制字段是否只读：

php

use Filament\Forms\Components\TextInput;

TextInput::make('name')
    ->readOnly(FeatureFlag::active())

TIP

除静态值外，readOnly() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

文本输入校验

除校验页面列出的全部规则外，还有专用于文本输入的额外规则。

长度校验

可用 minLength() 和 maxLength() 限制输入长度。这些方法会同时添加前端与后端校验：

php

use Filament\Forms\Components\TextInput;

TextInput::make('name')
    ->minLength(2)
    ->maxLength(255)

也可用 length() 指定输入的确切长度。该方法会同时添加前端与后端校验：

php

use Filament\Forms\Components\TextInput;

TextInput::make('code')
    ->length(8)

TIP

除静态值外，minLength()、maxLength() 和 length() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

数值大小校验

可用 minValue() 和 maxValue() 校验数值输入的最小与最大值：

php

use Filament\Forms\Components\TextInput;

TextInput::make('number')
    ->numeric()
    ->minValue(1)
    ->maxValue(100)

TIP

除静态值外，minValue() 和 maxValue() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

电话号码校验

使用 tel() 字段时，会用以下规则校验值：/^[+]*[(]{0,1}[0-9]{1,4}[)]{0,1}[-\s\.\/0-9]*$/。

若要更改该规则，可使用 telRegex() 方法：

php

use Filament\Forms\Components\TextInput;

TextInput::make('phone')
    ->tel()
    ->telRegex('/^[+]*[(]{0,1}[0-9]{1,4}[)]{0,1}[-\s\.\/0-9]*$/')

或者，要在所有字段上自定义 telRegex()，可使用服务提供者：

php

use Filament\Forms\Components\TextInput;

TextInput::configureUsing(function (TextInput $component): void {
    $component->telRegex('/^[+]*[(]{0,1}[0-9]{1,4}[)]{0,1}[-\s\.\/0-9]*$/');
});

TIP

除静态值外，telRegex() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

文本输入 ​

简介 ​

设置 HTML 输入类型 ​

设置 HTML 输入模式 ​

设置数值步进 ​

自动完成文本 ​

使用 datalist 自动完成文本 ​

自动大写文本 ​

在字段旁添加前后缀文本 ​

使用图标作为前后缀 ​

设置前后缀图标颜色 ​

使用操作作为前后缀 ​

可显示的密码输入 ​

允许将文本复制到剪贴板 ​

输入掩码 ​

修剪空白 ​

使字段只读 ​

文本输入校验 ​

长度校验 ​

数值大小校验 ​

电话号码校验 ​