表单
日期时间选择器
简介
日期时间选择器为选择日期/时间提供了互动接口：
use Filament\Forms\Components\DatePicker;
use Filament\Forms\Components\DateTimePicker;
use Filament\Forms\Components\TimePicker;
DateTimePicker::make('published_at')
DatePicker::make('date_of_birth')
TimePicker::make('alarm_at')
自定义存储格式
使用 format() 方法，你可以自定义该字段保存到数据库中时的格式。它接受字符串日期格式，格式参考 PHP 日期格式化 token：
use Filament\Forms\Components\DatePicker;
DatePicker::make('date_of_birth')
->format('d/m/Y')
除了静态值之外，format() 也可以接受函数来动态计算格式。你可以将各种 utility 作为参数注入到该函数中。
Learn more about utility injection.
| Utility | Type | Parameter | Description |
|---|---|---|---|
| Field | Filament\Forms\Components\Field | $component | The current field component instance. |
| Get function | Filament\Schemas\Components\Utilities\Get | $get | A function for retrieving values from the current form data. Validation is not run. |
| Livewire | Livewire\Component | $livewire | The Livewire component instance. |
| Eloquent model FQN | ?string<Illuminate\Database\Eloquent\Model> | $model | The Eloquent model FQN for the current schema. |
| Operation | string | $operation | The current operation being performed by the schema. Usually create, edit, or view. |
| Raw state | mixed | $rawState | The current value of the field, before state casts were applied. Validation is not run. |
| Eloquent record | ?Illuminate\Database\Eloquent\Model | $record | The Eloquent record for the current schema. |
| State | mixed | $state | The current value of the field. Validation is not run. |
禁用输入秒
使用时间选择器时，你可以通过 seconds(false) 方法禁用秒输入：
use Filament\Forms\Components\DateTimePicker;
DateTimePicker::make('published_at')
->seconds(false)
除了允许静态值之外，seconds() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。
Learn more about utility injection.
| Utility | Type | Parameter | Description |
|---|---|---|---|
| Field | Filament\Forms\Components\Field | $component | The current field component instance. |
| Get function | Filament\Schemas\Components\Utilities\Get | $get | A function for retrieving values from the current form data. Validation is not run. |
| Livewire | Livewire\Component | $livewire | The Livewire component instance. |
| Eloquent model FQN | ?string<Illuminate\Database\Eloquent\Model> | $model | The Eloquent model FQN for the current schema. |
| Operation | string | $operation | The current operation being performed by the schema. Usually create, edit, or view. |
| Raw state | mixed | $rawState | The current value of the field, before state casts were applied. Validation is not run. |
| Eloquent record | ?Illuminate\Database\Eloquent\Model | $record | The Eloquent record for the current schema. |
| State | mixed | $state | The current value of the field. Validation is not run. |
时区
通过 timezone() 方法，你可以让用户在他们所处的时区中管理日期：
use Filament\Forms\Components\DateTimePicker;
DateTimePicker::make('published_at')
->timezone('America/New_York')
虽然日期仍然会使用应用配置的时区保存，但是日期将会使用新的时区加载，在保存时又将转换回原来的时区。
除了允许静态值之外，timezone() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。
Learn more about utility injection.
| Utility | Type | Parameter | Description |
|---|---|---|---|
| Field | Filament\Forms\Components\Field | $component | The current field component instance. |
| Get function | Filament\Schemas\Components\Utilities\Get | $get | A function for retrieving values from the current form data. Validation is not run. |
| Livewire | Livewire\Component | $livewire | The Livewire component instance. |
| Eloquent model FQN | ?string<Illuminate\Database\Eloquent\Model> | $model | The Eloquent model FQN for the current schema. |
| Operation | string | $operation | The current operation being performed by the schema. Usually create, edit, or view. |
| Raw state | mixed | $rawState | The current value of the field, before state casts were applied. Validation is not run. |
| Eloquent record | ?Illuminate\Database\Eloquent\Model | $record | The Eloquent record for the current schema. |
| State | mixed | $state | The current value of the field. Validation is not run. |
如果你没有传递 timezone() 给组件，它将使用 Filament 默认的时区。你可以在服务提供者(如 AppServiceProvider)的 boot() 方法中使用 FilamentTimezone::set() 方法设置默认时区：
use Filament\Support\Facades\FilamentTimezone;
public function boot(): void
{
FilamentTimezone::set('America/New_York');
}
如果你想为应用中的所有日期时间选择器设置默认时区，这很有用。它同时也用在其他 Filament 中使用到时区的地方。
NOTE
Filament 的默认时区只有在字段保存的是时间时适用。如果字段只保存日期(比如 DatePicker 而非 DateTimePicker 或者 TimePicker)，该时区将不会应用。这是为了防止当只保存日期而未保存时间时出现时区偏移。
启用 JavaScript 日期选择器
默认情况下，Filament 使用使用原生的 HTML5 日期选择器。使用 native(false) 方法，你可以启用更多自定义功能的 JavaScript 日期选择器：
use Filament\Forms\Components\DatePicker;
DatePicker::make('date_of_birth')
->native(false)
除了允许静态值之外，native() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。
Learn more about utility injection.
| Utility | Type | Parameter | Description |
|---|---|---|---|
| Field | Filament\Forms\Components\Field | $component | The current field component instance. |
| Get function | Filament\Schemas\Components\Utilities\Get | $get | A function for retrieving values from the current form data. Validation is not run. |
| Livewire | Livewire\Component | $livewire | The Livewire component instance. |
| Eloquent model FQN | ?string<Illuminate\Database\Eloquent\Model> | $model | The Eloquent model FQN for the current schema. |
| Operation | string | $operation | The current operation being performed by the schema. Usually create, edit, or view. |
| Raw state | mixed | $rawState | The current value of the field, before state casts were applied. Validation is not run. |
| Eloquent record | ?Illuminate\Database\Eloquent\Model | $record | The Eloquent record for the current schema. |
| State | mixed | $state | The current value of the field. Validation is not run. |
NOTE
JavaScript 日期选择器不支持原生日期选择器所支持的全键盘输入。如果你需要全键盘输入，请使用原生选择器。
自定义展示格式
你可以自定义该字段的显示格式，使之不同于其存入到数据库的格式。为此，请使用 displayFormat() 方法，该方法接收一个字符串日期格式(PHP 日期格式化 token)：
use Filament\Forms\Components\DatePicker;
DatePicker::make('date_of_birth')
->native(false)
->displayFormat('d/m/Y')
除了允许静态值之外，displayFormat() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。
Learn more about utility injection.
| Utility | Type | Parameter | Description |
|---|---|---|---|
| Field | Filament\Forms\Components\Field | $component | The current field component instance. |
| Get function | Filament\Schemas\Components\Utilities\Get | $get | A function for retrieving values from the current form data. Validation is not run. |
| Livewire | Livewire\Component | $livewire | The Livewire component instance. |
| Eloquent model FQN | ?string<Illuminate\Database\Eloquent\Model> | $model | The Eloquent model FQN for the current schema. |
| Operation | string | $operation | The current operation being performed by the schema. Usually create, edit, or view. |
| Raw state | mixed | $rawState | The current value of the field, before state casts were applied. Validation is not run. |
| Eloquent record | ?Illuminate\Database\Eloquent\Model | $record | The Eloquent record for the current schema. |
| State | mixed | $state | The current value of the field. Validation is not run. |
如果希望使用与应用配置不同的区域(locale)设置，你也可以配置渲染显示时使用的区域设置。为此，可以使用 locale() 方法：
use Filament\Forms\Components\DatePicker;
DatePicker::make('date_of_birth')
->native(false)
->displayFormat('d F Y')
->locale('fr')
除了允许静态值之外，locale() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。
Learn more about utility injection.
| Utility | Type | Parameter | Description |
|---|---|---|---|
| Field | Filament\Forms\Components\Field | $component | The current field component instance. |
| Get function | Filament\Schemas\Components\Utilities\Get | $get | A function for retrieving values from the current form data. Validation is not run. |
| Livewire | Livewire\Component | $livewire | The Livewire component instance. |
| Eloquent model FQN | ?string<Illuminate\Database\Eloquent\Model> | $model | The Eloquent model FQN for the current schema. |
| Operation | string | $operation | The current operation being performed by the schema. Usually create, edit, or view. |
| Raw state | mixed | $rawState | The current value of the field, before state casts were applied. Validation is not run. |
| Eloquent record | ?Illuminate\Database\Eloquent\Model | $record | The Eloquent record for the current schema. |
| State | mixed | $state | The current value of the field. Validation is not run. |
配置时间输入间隔
使用 hoursStep()、minutesStep() 或者 secondsStep() 方法，你可以自定义小时、分钟、秒的增减的输入间隔：
use Filament\Forms\Components\DateTimePicker;
DateTimePicker::make('published_at')
->native(false)
->hoursStep(2)
->minutesStep(15)
->secondsStep(10)
除了允许静态值之外，hoursStep()、minutesStep() 和 secondsStep() 方法也接受函数来动态计算它们的值。你可以将各种 utility 作为参数注入到函数中。
Learn more about utility injection.
| Utility | Type | Parameter | Description |
|---|---|---|---|
| Field | Filament\Forms\Components\Field | $component | The current field component instance. |
| Get function | Filament\Schemas\Components\Utilities\Get | $get | A function for retrieving values from the current form data. Validation is not run. |
| Livewire | Livewire\Component | $livewire | The Livewire component instance. |
| Eloquent model FQN | ?string<Illuminate\Database\Eloquent\Model> | $model | The Eloquent model FQN for the current schema. |
| Operation | string | $operation | The current operation being performed by the schema. Usually create, edit, or view. |
| Raw state | mixed | $rawState | The current value of the field, before state casts were applied. Validation is not run. |
| Eloquent record | ?Illuminate\Database\Eloquent\Model | $record | The Eloquent record for the current schema. |
| State | mixed | $state | The current value of the field. Validation is not run. |
配置一周的第一天
在某些国家，一周的第一天不是周一。要在日期选择器中自定义一周的第一天，请在组件中使用 firstDayOfWeek() 方法，可接收的参数值从 0 到 7，周一是 1，周日为 7 或 0：
use Filament\Forms\Components\DateTimePicker;
DateTimePicker::make('published_at')
->native(false)
->firstDayOfWeek(7)
除了允许静态值之外，firstDayOfWeek() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。
Learn more about utility injection.
| Utility | Type | Parameter | Description |
|---|---|---|---|
| Field | Filament\Forms\Components\Field | $component | The current field component instance. |
| Get function | Filament\Schemas\Components\Utilities\Get | $get | A function for retrieving values from the current form data. Validation is not run. |
| Livewire | Livewire\Component | $livewire | The Livewire component instance. |
| Eloquent model FQN | ?string<Illuminate\Database\Eloquent\Model> | $model | The Eloquent model FQN for the current schema. |
| Operation | string | $operation | The current operation being performed by the schema. Usually create, edit, or view. |
| Raw state | mixed | $rawState | The current value of the field, before state casts were applied. Validation is not run. |
| Eloquent record | ?Illuminate\Database\Eloquent\Model | $record | The Eloquent record for the current schema. |
| State | mixed | $state | The current value of the field. Validation is not run. |
还有一些更方便的助手方法可以更语义化地设置一周的第一天：
use Filament\Forms\Components\DateTimePicker;
DateTimePicker::make('published_at')
->native(false)
->weekStartsOnMonday()
DateTimePicker::make('published_at')
->native(false)
->weekStartsOnSunday()
禁用特定日期
要阻止特定日期被选中：
use Filament\Forms\Components\DateTimePicker;
DateTimePicker::make('date')
->native(false)
->disabledDates(['2000-01-03', '2000-01-15', '2000-01-20'])
除了允许静态值之外，disabledDates() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。
Learn more about utility injection.
| Utility | Type | Parameter | Description |
|---|---|---|---|
| Field | Filament\Forms\Components\Field | $component | The current field component instance. |
| Get function | Filament\Schemas\Components\Utilities\Get | $get | A function for retrieving values from the current form data. Validation is not run. |
| Livewire | Livewire\Component | $livewire | The Livewire component instance. |
| Eloquent model FQN | ?string<Illuminate\Database\Eloquent\Model> | $model | The Eloquent model FQN for the current schema. |
| Operation | string | $operation | The current operation being performed by the schema. Usually create, edit, or view. |
| Raw state | mixed | $rawState | The current value of the field, before state casts were applied. Validation is not run. |
| Eloquent record | ?Illuminate\Database\Eloquent\Model | $record | The Eloquent record for the current schema. |
| State | mixed | $state | The current value of the field. Validation is not run. |
选择日期后关闭选择器
使用 closeOnDateSelection() 方法，可以在日期选中后关闭选择器：
use Filament\Forms\Components\DateTimePicker;
DateTimePicker::make('date')
->native(false)
->closeOnDateSelection()
此外，你也可以传入一个布尔值以控制选择完日期后是否关闭输入框：
use Filament\Forms\Components\DateTimePicker;
DateTimePicker::make('date')
->native(false)
->closeOnDateSelection(FeatureFlag::active())
除了允许静态值之外，closeOnDateSelection() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。
Learn more about utility injection.
| Utility | Type | Parameter | Description |
|---|---|---|---|
| Field | Filament\Forms\Components\Field | $component | The current field component instance. |
| Get function | Filament\Schemas\Components\Utilities\Get | $get | A function for retrieving values from the current form data. Validation is not run. |
| Livewire | Livewire\Component | $livewire | The Livewire component instance. |
| Eloquent model FQN | ?string<Illuminate\Database\Eloquent\Model> | $model | The Eloquent model FQN for the current schema. |
| Operation | string | $operation | The current operation being performed by the schema. Usually create, edit, or view. |
| Raw state | mixed | $rawState | The current value of the field, before state casts were applied. Validation is not run. |
| Eloquent record | ?Illuminate\Database\Eloquent\Model | $record | The Eloquent record for the current schema. |
| State | mixed | $state | The current value of the field. Validation is not run. |
通过 datalist 自动补全日期
除非你使用了 JavaScript 日期选择器，你可以使用 datalist() 方法，为日期选择器指定 datalist 选项：
use Filament\Forms\Components\TimePicker;
TimePicker::make('appointment_at')
->datalist([
'09:00',
'09:30',
'10:00',
'10:30',
'11:00',
'11:30',
'12:00',
])
当用户使用选择器时，Datalist 会为用户提供自动补全选项。不过，这些选项是纯推荐，用户仍然可以输入任何的值。如果你希望使用一套预定义的选项对用户进行严格的限制，请查阅 Select 字段。
除了允许静态值之外，datalist() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。
Learn more about utility injection.
| Utility | Type | Parameter | Description |
|---|---|---|---|
| Field | Filament\Forms\Components\Field | $component | The current field component instance. |
| Get function | Filament\Schemas\Components\Utilities\Get | $get | A function for retrieving values from the current form data. Validation is not run. |
| Livewire | Livewire\Component | $livewire | The Livewire component instance. |
| Eloquent model FQN | ?string<Illuminate\Database\Eloquent\Model> | $model | The Eloquent model FQN for the current schema. |
| Operation | string | $operation | The current operation being performed by the schema. Usually create, edit, or view. |
| Raw state | mixed | $rawState | The current value of the field, before state casts were applied. Validation is not run. |
| Eloquent record | ?Illuminate\Database\Eloquent\Model | $record | The Eloquent record for the current schema. |
| State | mixed | $state | The current value of the field. Validation is not run. |
在字段旁添加前后缀
使用 prefix() 和 suffix() 方法，你可以在输入框前后放置文本：
use Filament\Forms\Components\DatePicker;
DatePicker::make('date')
->prefix('Starts')
->suffix('at midnight')
除了允许静态值之外，prefix() 和 suffix() 方法也接受函数来动态计算它们的值。你可以将各种 utility 作为参数注入到函数中。
Learn more about utility injection.
| Utility | Type | Parameter | Description |
|---|---|---|---|
| Field | Filament\Forms\Components\Field | $component | The current field component instance. |
| Get function | Filament\Schemas\Components\Utilities\Get | $get | A function for retrieving values from the current form data. Validation is not run. |
| Livewire | Livewire\Component | $livewire | The Livewire component instance. |
| Eloquent model FQN | ?string<Illuminate\Database\Eloquent\Model> | $model | The Eloquent model FQN for the current schema. |
| Operation | string | $operation | The current operation being performed by the schema. Usually create, edit, or view. |
| Raw state | mixed | $rawState | The current value of the field, before state casts were applied. Validation is not run. |
| Eloquent record | ?Illuminate\Database\Eloquent\Model | $record | The Eloquent record for the current schema. |
| State | mixed | $state | The current value of the field. Validation is not run. |
使用图标作为前后缀
使用 prefixIcon() 和 suffixIcon() 方法，你可以在输入框前后放置图标：
use Filament\Forms\Components\TimePicker;
use Filament\Support\Icons\Heroicon;
TimePicker::make('at')
->prefixIcon(Heroicon::Play)
除了允许静态值之外，prefixIcon() 和 suffixIcon() 方法也接受函数来动态计算它们的值。你可以将各种 utility 作为参数注入到函数中。
Learn more about utility injection.
| Utility | Type | Parameter | Description |
|---|---|---|---|
| Field | Filament\Forms\Components\Field | $component | The current field component instance. |
| Get function | Filament\Schemas\Components\Utilities\Get | $get | A function for retrieving values from the current form data. Validation is not run. |
| Livewire | Livewire\Component | $livewire | The Livewire component instance. |
| Eloquent model FQN | ?string<Illuminate\Database\Eloquent\Model> | $model | The Eloquent model FQN for the current schema. |
| Operation | string | $operation | The current operation being performed by the schema. Usually create, edit, or view. |
| Raw state | mixed | $rawState | The current value of the field, before state casts were applied. Validation is not run. |
| Eloquent record | ?Illuminate\Database\Eloquent\Model | $record | The Eloquent record for the current schema. |
| State | mixed | $state | The current value of the field. Validation is not run. |
设置前后缀图标颜色
前后缀图标默认是灰色，不过你可以使用 prefixIconColor() 和 suffixIconColor() 方法将其设为不同颜色：
use Filament\Forms\Components\TimePicker;
use Filament\Support\Icons\Heroicon;
TimePicker::make('at')
->prefixIcon(Heroicon::CheckCircle)
->prefixIconColor('success')
除了允许静态值之外，prefixIconColor() 和 suffixIconColor() 方法也接受函数来动态计算它们的值。你可以将各种 utility 作为参数注入到函数中。
Learn more about utility injection.
| Utility | Type | Parameter | Description |
|---|---|---|---|
| Field | Filament\Forms\Components\Field | $component | The current field component instance. |
| Get function | Filament\Schemas\Components\Utilities\Get | $get | A function for retrieving values from the current form data. Validation is not run. |
| Livewire | Livewire\Component | $livewire | The Livewire component instance. |
| Eloquent model FQN | ?string<Illuminate\Database\Eloquent\Model> | $model | The Eloquent model FQN for the current schema. |
| Operation | string | $operation | The current operation being performed by the schema. Usually create, edit, or view. |
| Raw state | mixed | $rawState | The current value of the field, before state casts were applied. Validation is not run. |
| Eloquent record | ?Illuminate\Database\Eloquent\Model | $record | The Eloquent record for the current schema. |
| State | mixed | $state | The current value of the field. Validation is not run. |
字段设为只读
不要与禁用该字段混为一谈，你可以使用 readOnly() 方法使该字段只读：
use Filament\Forms\Components\DatePicker;
DatePicker::make('date_of_birth')
->readonly()
请注意，此设置仅在原生日期选择器上强制执行。如果你使用 JavaScript 日期选择器，则需要使用 disabled()。
与 disabled() 相比，它有一些不同之处：
- 使用
readOnly()时，该字段仍然会在表单提交时发送到服务器。它可以通过浏览器控制台或者 JavaScript 操作改变。你可以使用dehydrated(false)来阻止该行为。 - 当使用
readOnly()时，它的样式没有任何改变，比如不会降低透明度。 - 当使用
readOnly()时，该字段仍然是可聚焦的。
此外，你也可以传入一个布尔值以控制该字段是否为只读：
use Filament\Forms\Components\DatePicker;
DatePicker::make('date_of_birth')
->readOnly(FeatureFlag::active())
除了允许静态值之外，readOnly() 方法也可以接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。
Learn more about utility injection.
| Utility | Type | Parameter | Description |
|---|---|---|---|
| Field | Filament\Forms\Components\Field | $component | The current field component instance. |
| Get function | Filament\Schemas\Components\Utilities\Get | $get | A function for retrieving values from the current form data. Validation is not run. |
| Livewire | Livewire\Component | $livewire | The Livewire component instance. |
| Eloquent model FQN | ?string<Illuminate\Database\Eloquent\Model> | $model | The Eloquent model FQN for the current schema. |
| Operation | string | $operation | The current operation being performed by the schema. Usually create, edit, or view. |
| Raw state | mixed | $rawState | The current value of the field, before state casts were applied. Validation is not run. |
| Eloquent record | ?Illuminate\Database\Eloquent\Model | $record | The Eloquent record for the current schema. |
| State | mixed | $state | The current value of the field. Validation is not run. |
日期时间选择器验证
除了验证页面中列出的所有规则，还有一些专门用于日期时间选择器的规则。
最大/最小日期验证
你可以限制选择器所能够选择的最小和最大日期。minDate 和 maxDate 接收一个 DateTime 实例(比如 Carbon)或者字符串：
use Filament\Forms\Components\DatePicker;
DatePicker::make('date_of_birth')
->native(false)
->minDate(now()->subYears(150))
->maxDate(now())
除了允许静态值之外，minDate() and maxDate() 方法也接受函数来动态计算它们的值。如果该函数返回 null，该验证规则将不适用。你可以将各种 utility 作为参数注入到函数中。
Learn more about utility injection.
| Utility | Type | Parameter | Description |
|---|---|---|---|
| Field | Filament\Forms\Components\Field | $component | The current field component instance. |
| Get function | Filament\Schemas\Components\Utilities\Get | $get | A function for retrieving values from the current form data. Validation is not run. |
| Livewire | Livewire\Component | $livewire | The Livewire component instance. |
| Eloquent model FQN | ?string<Illuminate\Database\Eloquent\Model> | $model | The Eloquent model FQN for the current schema. |
| Operation | string | $operation | The current operation being performed by the schema. Usually create, edit, or view. |
| Raw state | mixed | $rawState | The current value of the field, before state casts were applied. Validation is not run. |
| Eloquent record | ?Illuminate\Database\Eloquent\Model | $record | The Eloquent record for the current schema. |
| State | mixed | $state | The current value of the field. Validation is not run. |
Still need help? Join our Discord community or open a GitHub discussion