显示侧边栏
隐藏侧边栏
Flux Pro 组件
此组件仅在 Flux 的 Pro 版本中提供。

日期选择器

允许用户通过日历浮层选择日期或日期范围,非常适合用于筛选数据或安排活动。

对于诸如生日等遥远的未来或过去事件,请使用日期输入而非日期选择器。

<flux:date-picker />

基本用法

使用 value 属性并提供一个采用 Y-m-d 格式的日期字符串,即可设置初始选中的日期:
<flux:date-picker value="2025-10-12" />
你也可以使用 wire:model 将选中的日期绑定到 Livewire 属性:
<flux:date-picker wire:model="date" />
现在你可以在 Livewire 组件中,通过 Carbon 实例或 Y-m-d 格式的字符串来获取选中的日期:
<?phpuse Illuminate\Support\Carbon;use Livewire\Component;use App\Models\Post;class CreatePost extends Component {    public ?Carbon $date;    public function save()    {        Post::create([            // ...            'published_at' => $this->date,        ])        // ...    }}

输入触发器

将日期选择器附加到日期输入框,以获得更精确的日期选择控制。

<flux:date-picker wire:model="date">    <x-slot name="trigger">        <flux:date-picker.input />    </x-slot></flux:date-picker>

范围选择器

启用日期范围选择,可用于报表、预订系统或任何需要起止日期的场景。

<flux:date-picker mode="range" />
使用 value 属性,并通过斜杠分隔起始日期和结束日期来设置初始范围:
<flux:date-picker mode="range" value="2025-10-02/2025-10-06" />
你也可以使用 wire:model 将选择结果绑定到 Livewire 属性:
<flux:date-picker mode="range" wire:model="range" />
现在你可以在 Livewire 组件中,使用一个包含 Y-m-d 格式日期字符串的关联数组来访问选定范围:
<?phpuse Illuminate\Support\Carbon;use Livewire\Component;class Dashboard extends Component {    public array $range;    public function mount() {        $this->range = [            'start' => now()->subMonth()->format('Y-m-d'),            'end' => now()->format('Y-m-d'),        ];    }}
或者,你可以使用专门的 DateRange 对象,以获得更强大的功能:
<?phpuse Livewire\Component;use Flux\DateRange;class Dashboard extends Component {    public DateRange $range;    public function mount() {        $this->range = new DateRange(now()->subMonth(), now());    }}
我们强烈推荐在范围选择中使用 DateRange 对象,它提供了许多实用功能。

范围限制

控制可选日期范围的允许值。

<flux:date-picker mode="range" min-range="3" />
<flux:date-picker mode="range" max-range="10" />

带输入的范围选择

为开始和结束日期分别提供输入框,可让日期范围选择界面更加清晰。

Start
End
<flux:date-picker mode="range">    <x-slot name="trigger">        <div class="flex flex-col sm:flex-row gap-6 sm:gap-4">            <flux:date-picker.input label="Start" />            <flux:date-picker.input label="End" />        </div>    </x-slot></flux:date-picker>

预设范围

允许用户选择常用的日期范围,例如“最近 7 天”或“本月”。

Today Yesterday This Week Last 7 Days This Month Year to Date All Time
<flux:date-picker mode="range" with-presets />
你还可以使用 presets 属性来指定需要展示的预设以及它们的排序:
<flux:date-picker    mode="range"    presets="today yesterday thisWeek last7Days thisMonth yearToDate allTime"/>

可用预设

以下列出了所有可用的预设。
键名
显示文本
构造器
日期范围
today
Today
DateRange::today()
当天
yesterday
Yesterday
DateRange::yesterday()
前一天
thisWeek
This Week
DateRange::thisWeek()
本周
lastWeek
Last Week
DateRange::lastWeek()
上一周
last7Days
Last 7 Days
DateRange::last7Days()
前 7 天
thisMonth
This Month
DateRange::thisMonth()
本月
lastMonth
Last Month
DateRange::lastMonth()
上一月
thisQuarter
This Quarter
DateRange::thisQuarter()
本季度
lastQuarter
Last Quarter
DateRange::lastQuarter()
上一季度
thisYear
This Year
DateRange::thisYear()
本年度
lastYear
Last Year
DateRange::lastYear()
上一年度
last14Days
Last 14 Days
DateRange::last14Days()
前 14 天
last30Days
Last 30 Days
DateRange::last30Days()
前 30 天
last3Months
Last 3 Months
DateRange::last3Months()
前 3 个月
last6Months
Last 6 Months
DateRange::last6Months()
前 6 个月
yearToDate
Year to Date
DateRange::yearToDate()
当年 1 月 1 日至今日
allTime
All Time
DateRange::allTime($start)
最早提供日期至今日
custom
Custom Range
DateRange::custom()
用户自定义日期范围

全时段

使用 allTime 预设时,必须通过 min 属性指定一个最小日期。该最小日期将用作“全时段”范围的开始日期,今天的日期将用作结束日期:
<flux:date-picker    mode="range"    presets="... allTime"    :min="auth()->user()->created_at->format('Y-m-d')"/>
如果需要通过 Livewire 的 DateRange 对象来构建该范围,可以按如下方式进行:
use Flux\DateRange;$this->range = DateRange::allTime(start: auth()->user()->created_at);
如果使用该日期范围来过滤数据,当选择 allTime 时,可能需要从查询中移除 "where" 限制:
$orders = Order::when($this->range->isNotAllTime(), function ($query) => {    $query->whereBetween('created_at', $this->range);})->get();

自定义范围预设

当用户选择的自定义日期范围与其他预设都不匹配时,如果在 presets 属性中包含了 custom 预设,选择器会自动切换至该预设。
<flux:date-picker mode="range" presets="... custom" />

不可用日期

禁用特定日期的选择。可用于屏蔽节假日、展示已被预订的日期或标记不可用的时间段。

<flux:date-picker unavailable="2025-10-11,2025-10-13" />

包含“今天”快捷键

添加一个快捷按钮,便于快速跳转到今天的日期。查看其他月份时,它会跳转到当前月份;当已在当前月份时,会直接选中今天。

<flux:date-picker with-today />

可选择的标题栏

让标题栏中的月份和年份可选择,以便快速导航。

<flux:date-picker selectable-header />

固定周数

在每个月中显示相同的周数。可避免在切换周数不同的月份时出现布局变化。

<flux:date-picker fixed-weeks />

起始日

默认情况下,周的第一天会依据用户的地区自动设置。你可以通过将 start-day 属性设为一周中的任意一天来覆盖此设置。

<flux:date-picker start-day="1" />

默认展开日期

设置日历打开时默认显示的日期。否则将默认显示已选日期所在的月份,或当前月份。

<flux:date-picker open-to="2026-11-01" />

周序号

为每一周显示对应的周序号。

<flux:date-picker week-numbers />

本地化

默认情况下,日期选择器会使用浏览器的本地化设置(例如 navigator.language)。

你可以通过将 locale 属性设置为任意有效的本地化字符串来覆盖此行为(例如法语的 fr、英语的 en-US 等):

<flux:date-picker locale="ja-JP" />

DateRange 对象

Flux 提供了一个扩展原生 CarbonPeriod 类的专用 Flux\DateRange 对象。该对象提供了多种便捷方法,便于创建和管理日期范围。
首先值得注意的是,大多数情况下你会希望使用 wire:model.liverange 属性绑定到 DateRange 对象。这会在用户选择日期范围时自动更新 range 属性:
<flux:calendar wire:model.live="range" />
现在,在你的组件中,你可以为 range 属性添加类型提示,将其声明为 DateRange 对象:
<?phpuse Livewire\Component;use Flux\DateRange;class Dashboard extends Component {    public DateRange $range;}

实例化

你可以在诸如 mount 方法中,通过向 DateRange 构造函数传入起始与结束日期来初始化一个 DateRange 对象:
<?phpuse Livewire\Component;use Flux\DateRange;class Dashboard extends Component {    public DateRange $range;    public function mount() {        $this->range = new DateRange(now(), now()->addDays(7));    }}

持久化到会话

你可以通过使用 #[Session] 属性,将 DateRange 对象持久化到用户会话中:
<?phpuse Livewire\Attributes\Session;use Livewire\Component;use Flux\DateRange;class Dashboard extends Component {    #[Session]    public DateRange $range;}

搭配 Eloquent 使用

你可以将 DateRange 对象与 Eloquent 的 whereBetween() 方法结合使用,以日期范围来过滤查询:
<?phpuse Livewire\Attributes\Computed;use Livewire\Component;use App\Models\Order;use Flux\DateRange;class Dashboard extends Component {    public ?DateRange $range;    #[Computed]    public function orders() {        return $this->range            ? Order::whereBetween('created_at', $this->range)->get()            : Order::all();    }}

可用方法

DateRange 对象扩展了原生 CarbonPeriod 类,因此继承了它的所有方法。以下是一些示例:
$range = new Flux\DateRange(    now()->subDays(1),    now()->addDays(1),);// Get the start and end dates as Carbon instances...$start = $range->start();$end = $range->end();// Check if the range contains a date...$range->contains(now());// Get the number of days in the range...$range->length();// Loop over the range by day...foreach ($range as $date) {    // $date is a Carbon instance...}// Get the range as an array of Carbon instances representing each day in the range...$range->toArray();
在任何需要 CarbonPeriod 实例的 Eloquent 工具中,你也可以使用它:
$orders = Order::whereBetween('created_at', $range)->get();

范围预设

使用 presets 属性时,日历会获取或设置一个包含日期的关联数组,以及一个 preset 键:
[    'start' => null,    'end' => null,    'preset' => 'lastMonth',]
你也可以通过简单的数组绑定直接获取或设置预设字符串:
<?phpuse Livewire\Component;class Dashboard extends Component {    public array $range;    public function mount() {        $this->range = [            'start' => null,            'end' => null,            'preset' => 'lastMonth',        ];    }}
然而,DateRange 对象可以在内部管理预设。
例如,你可以通过 lastMonth() 方法创建一个范围:
<?phpuse Livewire\Component;use Flux\DateRange;class Dashboard extends Component {    public DateRange $range;    public function mount() {        $this->range = DateRange::lastMonth();    }}
你可以通过 preset() 方法以枚举值的形式访问预设:
$this->range->preset();// This will return a value like `DateRangePreset::LastMonth`...

参考

flux:date-picker

属性
说明
wire:model
将日期选择器绑定到 Livewire 属性。更多信息请参阅 wire:model 文档
value
选中的日期。格式取决于 mode:单日期(Y-m-d)或范围(Y-m-d/Y-m-d)。
mode
选择模式。可选值:single(默认)、range
min-range
范围模式下可选择的最少天数。
max-range
范围模式下可选择的最多天数。
min
可选择的最早日期。可以是日期字符串或 "today"。
max
可选择的最晚日期。可以是日期字符串或 "today"。
months
要显示的月份数量。默认: 1单选模式为 2,范围模式为 2
label
显示在日期选择器上方的标签文本。提供后,会将组件包裹在 flux:field 中,并在旁侧呈现 flux:label.
description
显示在日期选择器下方的帮助文本。与 label 一同提供时,会在 flux:field 包裹内显示在标签与日期选择器之间。
description:trailing
提供的描述将显示在日期选择器下方,而非上方。
badge
当提供 flux:label 属性时,在 label 组件末尾显示的徽章文本。
placeholder
未选择日期时显示的占位文本。默认值取决于 mode.
size
日历日期单元的大小。可选值: sm, default, lg, xl, 2xl.
start-day
日历的周起始日。可选值: 0(星期日)至 6(星期六)。默认:基于用户的语言地区。
week-numbers
若为 true,则在日历中显示周序号。
selectable-header
若为 true,则显示月份和年份下拉框以便快速导航。
with-today
若为 true,则显示一个按钮用于快速跳转到今天。
with-inputs
若为 true,则在日历顶部显示日期输入框以便手动输入。
with-confirmation
若为 true,则在应用所选日期前需要确认。
with-presets
若为 true,则显示预设日期范围。可与 presets 搭配以自定义可用选项。
presets
以空格分隔的预设日期范围列表。默认值: today yesterday thisWeek last7Days thisMonth yearToDate allTime.
clearable
当选择了日期时显示清除按钮。
disabled
禁止用户与日期选择器交互。
invalid
为日期选择器应用错误样式。
locale
设置日期选择器使用的本地化。示例: fr, en-US, ja-JP.
插槽
描述
trigger
用于打开日期选择器的自定义触发元素。通常是 flux:date-picker.inputflux:date-picker.button
属性
描述
data-flux-date-picker
应用于根元素,用于样式和标识。

flux:date-picker.input

属性
描述
label
显示在输入框上方的标签文本。提供该属性时,会将输入框包裹在 flux:field 组件中,并配套一个相邻的 flux:label 组件。
description
显示在输入框下方的帮助文本。与 label 一起提供时,会出现在 flux:field 包裹内的标签与输入框之间。
placeholder
未选择日期时显示的占位文本。
clearable
选中日期时显示清除按钮。
disabled
禁止用户与输入框交互。
invalid
为输入框应用错误样式。

flux:date-picker.button

属性
描述
placeholder
未选择日期时显示的文本。
size
按钮的尺寸。可选值:smxs
clearable
选中日期时显示清除按钮。
disabled
禁止用户与按钮交互。
invalid
为按钮应用错误样式。

DateRange 对象

在使用 mode="range" 时用于处理日期范围的专用对象。

方法
描述
$range->start()
以 Carbon 实例获取开始日期。
$range->end()
以 Carbon 实例获取结束日期。
$range->days()
获取范围内的天数。
$range->preset()
以 DateRangePreset 枚举值获取当前预设。
$range->toArray()
以包含 startend 键的数组形式获取范围。
静态方法
描述
DateRange::today()
创建一个表示今日的 DateRange。
DateRange::yesterday()
创建一个表示昨日的 DateRange。
DateRange::thisWeek()
创建一个表示本周的 DateRange。
DateRange::lastWeek()
创建一个表示上周的 DateRange。
DateRange::last7Days()
创建一个表示过去 7 天的 DateRange。
DateRange::last30Days()
创建一个表示过去 30 天的 DateRange。
DateRange::thisMonth()
创建一个表示本月的 DateRange。
DateRange::lastMonth()
创建一个表示上月的 DateRange。
DateRange::thisQuarter()
创建一个表示本季度的 DateRange。
DateRange::lastQuarter()
创建一个表示上季度的 DateRange。
DateRange::thisYear()
创建一个表示本年的 DateRange。
DateRange::lastYear()
创建一个表示去年的 DateRange。
DateRange::yearToDate()
创建一个从 1 月 1 日至今日的 DateRange。
DateRange::allTime()
创建一个无限制的 DateRange。
© 2025 FluxProMax™. All Rights Reserved.

备案号:皖ICP备13019729号-11