显示侧边栏

Flux Pro 组件

此组件仅在 Flux 的 Pro 版本中提供。

日历

用于日期选择的灵活日历组件。支持单选、多选与日期范围。非常适合排程与预订系统。

<flux:calendar />

基础用法

使用 value 属性并传入 Y-m-d 格式的日期字符串来设置初始选中日期：

<flux:calendar value="2025-10-07" />

你也可以使用 wire:model 将选择结果绑定到 Livewire 属性：

<flux:calendar wire:model="date" />

现在你可以在 Livewire 组件中通过 Carbon 实例或 Y-m-d 格式的字符串来获取选中的日期：

<?phpuse Illuminate\Support\Carbon;use Livewire\Component;class BookAppointment extends Component {    public Carbon $date;    public function mount() {        $this->date = now();    }}

多日期

选择多个非连续日期。

<flux:calendar multiple />

在 value 属性中使用逗号分隔的列表来设置多个选中日期：

<flux:calendar    multiple    value="2025-10-02,2025-10-05,2025-10-15"/>

你也可以使用 wire:model 进行绑定：

<flux:calendar multiple wire:model="dates" />

在 Livewire 组件中，你可以通过由 Y-m-d 格式字符串组成的数组获取选中的日期：

<?phpuse Illuminate\Support\Carbon;use Livewire\Component;class RequestTimeOff extends Component {    public array $dates = [];    public function mount() {        $this->dates = [            now()->format('Y-m-d'),            now()->addDays(1)->format('Y-m-d'),        ];    }}

日期范围

选择一段日期范围。

<flux:calendar mode="range" />

使用 value 属性，并用正斜杠分隔起始与结束日期来设置初始范围：

<flux:calendar mode="range" value="2025-10-02/2025-10-06" />

你也可以使用 wire:model 将选择结果绑定到 Livewire 属性：

<flux:calendar mode="range" wire:model="range" />

现在你可以在 Livewire 组件中通过一个包含 Y-m-d 格式字符串的关联数组（键为 start 与 end）来获取所选范围：

<?phpuse Livewire\Component;class BookFlight extends Component {    public ?array $range;    public function book() {        // ...        $flight->depart_on = $this->range['start'];        $flight->return_on = $this->range['end'];        // ...    }}

或者，你可以使用专用的 DateRange 对象以获得更强的功能：

<?phpuse Livewire\Component;use Flux\DateRange;class BookFlight extends Component {    public ?DateRange $range;    public function book() {        // ...        $flight->depart_on = $this->range->start();        $flight->return_on = $this->range->end();        // ...    }}

我们强烈推荐在范围选择中使用 DateRange 对象，它提供了许多实用功能。

查看你可以用 DateRange 对象完成的所有操作 ->

范围配置

使用以下属性控制范围行为：

<!-- Set minimum and maximum range limits --><flux:calendar mode="range" min-range="3" max-range="10" /><!-- Control number of months shown --><flux:calendar mode="range" months="2" />

尺寸

根据布局调整日历大小。可用尺寸包括 xs、sm、lg、xl 和 2xl。

<flux:calendar size="xl" />

静态

创建用于展示的非交互式日历。

<flux:calendar    static    value="2025-10-07"    size="xs"    :navigation="false"/>

最小/最大日期

通过设置最小值和最大值来限制可选日期范围。

<flux:calendar max="2025-10-07" />

你也可以使用便捷的 “today” 简写：

<!-- Prevent selection before today... --><flux:calendar min="today" /><!-- Prevent selection after today... --><flux:calendar max="today" />

不可用日期

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

<flux:calendar unavailable="2025-10-06,2025-10-08" />

包含“今天”快捷按钮

添加一个快捷按钮以快速定位到今天。当查看其他月份时跳转到当月；若已在当月则直接选中今天。

<flux:calendar with-today />

可选择的标题

使标题中的月份与年份可选择，以便快速导航。

<flux:calendar selectable-header />

固定周数

每个月显示一致的周数。在不同周数的月份之间切换时避免布局抖动。

<flux:calendar fixed-weeks />

起始星期

默认情况下，周的第一天会根据用户的语言环境自动设置。你可以通过设置 start-day 属性为任意星期几来覆盖该行为。

<flux:calendar start-day="1" />

打开到

设置日历初始打开的日期。否则日历会默认打开到已选日期所在的月份，若无已选日期则为当前月份。

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

周序号

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

<flux:calendar week-numbers />

本地化

默认情况下，日历会使用浏览器的语言环境（例如 navigator.language）。

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

<flux:calendar locale="ja-JP" />

DateRange 对象

Flux 提供了一个专用的 Flux\DateRange 对象，它扩展了原生的 CarbonPeriod 类。该对象提供了许多便捷方法，便于创建和管理日期范围。

首先需要说明的是，大多数情况下，你会希望使用 wire:model.live 将 range 属性绑定为一个 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

你可以使用 #[Session] 属性将 DateRange 对象持久化到用户的 Session 中：

<?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();

参考

flux:calendar

属性	说明
wire:model	将日历绑定到一个 Livewire 属性。更多信息请参阅 wire:model 文档。
value	选中的日期。其格式取决于 mode：单选（Y-m-d）、多选（逗号分隔的 Y-m-d），或范围（Y-m-d/Y-m-d）。
mode	选择模式。可选项：single（默认）、multiple、range。
min	可选择的最早日期。可为日期字符串或 “today”。
max	可选择的最晚日期。可为日期字符串或 “today”。
size	日历尺寸。可选项：base（默认）、xs、sm、lg、xl、2xl。
start-day	设定周起始的星期。可选：0（周日）至 6（周六）。默认：基于用户的语言环境。
months	显示的月份数量。默认：单选/多选模式为 1，范围模式为 2。
min-range	范围模式下可选择的最少天数。
max-range	范围模式下可选择的最多天数。
navigation	为 false 时，隐藏月份导航控件。默认：true。
static	为 true 时，日历为非交互（仅展示）。默认：false。
multiple	If true, enables multiple date selection mode. Default: false.
week-numbers	If true, displays week numbers in the calendar. Default: false.
selectable-header	If true, displays month and year dropdowns for quick navigation. Default: false.
with-today	If true, displays a button to quickly navigate to today's date. Default: false.
with-inputs	为 true 时，在日历顶部显示日期输入框以便手动输入。默认：false。
locale	设置日历的本地化。示例：fr、en-US、ja-JP。

属性	说明
data-flux-calendar	应用于根元素，用于样式与标识。

DateRange 对象

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

方法	说明
$range->start()	以 Carbon 实例的形式获取起始日期。
$range->end()	以 Carbon 实例的形式获取结束日期。
$range->days()	获取该范围内的天数。
$range->contains(date)	检查范围内是否包含某个特定日期。
$range->length()	以“天”为单位获取范围长度。
$range->toArray()	以数组形式获取范围，包含 start 和 end 键。
$range->preset()	获取当前预设（若存在）作为 DateRangePreset 枚举值。

静态方法	说明
DateRange::today()	创建一个表示“今天”的 DateRange。
DateRange::yesterday()	创建一个表示“昨天”的 DateRange。
DateRange::thisWeek()	创建一个表示“本周”的 DateRange。
DateRange::lastWeek()	创建一个表示“上周”的 DateRange。
DateRange::last7Days()	创建一个表示“过去 7 天”的 DateRange。
DateRange::thisMonth()	创建一个表示“本月”的 DateRange。
DateRange::lastMonth()	创建一个表示“上月”的 DateRange。
DateRange::thisYear()	创建一个表示“本年”的 DateRange。
DateRange::lastYear()	创建一个表示“去年”的 DateRange。
DateRange::yearToDate()	创建一个从 1 月 1 日到今天的 DateRange。