日期时间选择器

简介

日期时间选择器提供用于选择日期和/或时间的交互界面。

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 日期格式化标记：

use Filament\Forms\Components\DatePicker;

DatePicker::make('date_of_birth')
    ->format('d/m/Y')

TIP

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

禁用秒输入

使用时间选择器时，可用 seconds(false) 方法禁用秒输入：

use Filament\Forms\Components\DateTimePicker;

DateTimePicker::make('published_at')
    ->seconds(false)

TIP

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

时区

若希望用户按自己的时区管理日期，可使用 timezone() 方法：

use Filament\Forms\Components\DateTimePicker;

DateTimePicker::make('published_at')
    ->timezone('America/New_York')

日期仍会以应用配置的时区存储，但加载时会使用新时区，保存表单时再转换回去。

TIP

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

若未向组件传入 timezone()，将使用 Filament 的默认时区。可在 AppServiceProvider 等服务提供者的 boot() 方法中，用 FilamentTimezone::set() 设置 Filament 默认时区：

use Filament\Support\Facades\FilamentTimezone;

public function boot(): void
{
    FilamentTimezone::set('America/New_York');
}

若要为应用中所有日期时间选择器设置默认时区，此方式很有用。Filament 中其他使用时区的地方也会用到它。

WARNING

Filament 的默认时区仅在字段存储时间时生效。若字段只存储日期（使用 DatePicker 而非 DateTimePicker 或 TimePicker），则不会应用时区。这是为了避免在存储不含时间的日期时发生时区偏移。

启用 JavaScript 日期选择器

默认情况下，Filament 使用原生 HTML5 日期选择器。可用 native(false) 启用更可定制的 JavaScript 日期选择器：

use Filament\Forms\Components\DatePicker;

DatePicker::make('date_of_birth')
    ->native(false)

TIP

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

INFO

JavaScript 日期选择器不像原生日期选择器那样完整支持键盘输入。若需要完整键盘输入，应使用原生日期选择器。

自定义显示格式

可单独自定义字段的显示格式，与保存到数据库时使用的格式无关。使用 displayFormat() 方法，同样接受使用 PHP 日期格式化标记 的字符串日期格式：

use Filament\Forms\Components\DatePicker;

DatePicker::make('date_of_birth')
    ->native(false)
    ->displayFormat('d/m/Y')

TIP

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

若希望使用与应用配置不同的区域设置来渲染显示，也可用 locale() 方法配置：

use Filament\Forms\Components\DatePicker;

DatePicker::make('date_of_birth')
    ->native(false)
    ->displayFormat('d F Y')
    ->locale('fr')

TIP

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

配置时间输入步进

可用 hoursStep()、minutesStep() 或 secondsStep() 方法自定义增减时/分/秒的输入步进：

use Filament\Forms\Components\DateTimePicker;

DateTimePicker::make('published_at')
    ->native(false)
    ->hoursStep(2)
    ->minutesStep(15)
    ->secondsStep(10)

TIP

除静态值外，hoursStep()、minutesStep() 和 secondsStep() 方法也接受函数以动态计算。可将各种工具注入这些函数作为参数。

配置一周的第一天

在某些国家，一周的第一天不是星期一。要用 firstDayOfWeek() 自定义日期选择器中一周的第一天。接受值为 0 到 7，星期一为 1，星期日为 7 或 0：

use Filament\Forms\Components\DateTimePicker;

DateTimePicker::make('published_at')
    ->native(false)
    ->firstDayOfWeek(7)

TIP

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

此外还有更语义化的便捷辅助方法来设置一周的第一天：

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'])

TIP

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

选择日期后关闭选择器

要在选择日期后关闭选择器，可使用 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())

TIP

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

使用 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 会在用户使用选择器时提供自动完成选项。但这些只是建议，用户仍可输入任意值。若要严格限制为预定义选项，请参阅选择字段。

TIP

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

聚焦默认日历日期

默认情况下，若字段没有状态，打开日历面板会定位到当前日期。若希望打开时定位到特定日期，可用 defaultFocusedDate() 设置日历的默认聚焦日期：

use Filament\Forms\Components\DatePicker;

DatePicker::make('custom_starts_at')
    ->native(false)
    ->placeholder(now()->startOfMonth())
    ->defaultFocusedDate(now()->startOfMonth())

TIP

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

在字段旁添加前后缀文本

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

use Filament\Forms\Components\DatePicker;

DatePicker::make('date')
    ->prefix('Starts')
    ->suffix('at midnight')

TIP

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

使用图标作为前后缀

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

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

TimePicker::make('at')
    ->prefixIcon(Heroicon::Play)

TIP

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

设置前后缀图标颜色

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

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

TimePicker::make('at')
    ->prefixIcon(Heroicon::CheckCircle)
    ->prefixIconColor('success')

TIP

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

使字段只读

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

use Filament\Forms\Components\DatePicker;

DatePicker::make('date_of_birth')
    ->readonly()

请注意，此设置仅对原生日期选择器生效。若使用 JavaScript 日期选择器，需使用 disabled()。

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

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

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

use Filament\Forms\Components\DatePicker;

DatePicker::make('date_of_birth')
    ->readOnly(FeatureFlag::active())

TIP

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

日期时间选择器校验

除 校验 页面列出的全部规则外，还有专用于日期时间选择器的额外规则。

最大日期 / 最小日期校验

可限制选择器可选的最小与最大日期。minDate() 和 maxDate() 方法接受 DateTime 实例（如 Carbon）或字符串：

use Filament\Forms\Components\DatePicker;

DatePicker::make('date_of_birth')
    ->native(false)
    ->minDate(now()->subYears(150))
    ->maxDate(now())

TIP

除静态值外，minDate() 和 maxDate() 方法也接受函数以动态计算。若函数返回 null，则不应用该校验规则。可将各种工具注入这些函数作为参数。