rabol/livewire-calendar

Laravel Livewire 日历组件

2.1.3 2023-08-22 07:19 UTC

This package is auto-updated.

Last update: 2024-09-22 09:38:58 UTC


README

此包基于asantibanez/livewire-calendar的优秀作品

此包允许您构建一个Livewire月历网格,以显示每一天的事件。事件可以从组件内部加载,并将根据事件的日期在每一天显示。

预览

preview

安装

您可以通过Composer安装此包

composer require asantibanez/livewire-calendar

要求

此包底层使用 livewire/livewire (https://laravel-livewire.com/)。

它还使用TailwindCSS (https://tailwind.org.cn/) 进行基本样式设置。

请在使用此组件之前确保包含这两个依赖项。

用法

为了使用此组件,您必须创建一个新的Livewire组件,该组件扩展自 LivewireCalendar

您可以使用 make:livewire 命令创建一个新的组件。例如。

php artisan make:livewire AppointmentsCalendar

AppointmentsCalendar 类中,而不是从基本的 Component Livewire 类扩展,从 LivewireCalendar 扩展。同时,删除 render 方法。您将拥有类似以下代码段的类。

class AppointmentsCalendar extends LivewireCalendar
{
    //
}

在这个类中,您必须重写以下方法

public function events() : Collection
{
    // must return a Laravel collection
}

events() 方法中,返回一个包含将在日历上显示的事件的集合。事件必须是至少包含以下键的键值对:idtitledescriptiondatedate 必须是 Carbon\Carbon 实例)。

示例

public function events() : Collection
{
    return collect([
        [
            'id' => 1,
            'title' => 'Breakfast',
            'description' => 'Pancakes! 🥞',
            'date' => Carbon::today(),
        ],
        [
            'id' => 2,
            'title' => 'Meeting with Pamela',
            'description' => 'Work stuff',
            'date' => Carbon::tomorrow(),
        ],
    ]);
}

date 值将用于确定事件属于哪一天。要在 events() 方法中加载值,您可以使用以下组件属性来过滤事件。

  • startsAt:月份的开始日期
  • endsAt:月份的结束日期
  • gridStartsAt:日历网格的开始日期。可以是上个月的一个日期。
  • endingStartsAt:日历网格的结束日期。可以是下个月的一个日期。

示例

public function events(): Collection
{
    return Model::query()
        ->whereDate('scheduled_at', '>=', $this->gridStartsAt)
        ->whereDate('scheduled_at', '<=', $this->gridEndsAt)
        ->get()
        ->map(function (Model $model) {
            return [
                'id' => $model->id,
                'title' => $model->title,
                'description' => $model->notes,
                'date' => $model->scheduled_at,
            ];
        });
}

现在,我们可以在任何视图中包含我们的组件。

示例

<livewire:appointments-calendar/>

这将渲染一个日历网格。

example

默认情况下,组件将渲染当前月份。如果您想更改起始月份,可以设置 yearmonth props。

示例

<livewire:appointments-calendar
   year="2019"
   month="12"
/>

带地区设置的周视图

 <livewire:appointments-calendar
    initial-calendar-mode="1"
    week-starts-at="1"
    week-ends-at="0"
    initialLocale="da"
/>

您应包括带有 @livewireCalendarScripts 的脚本以启用默认启用的拖放。您必须在 @livewireScripts 之后包括它们。

@livewireScripts
@livewireCalendarScripts

组件有 3 个公共方法,可以帮助您在月份间导航

  • goToPreviousMonth
  • goToNextMonth
  • goToCurrentMonth

您可以使用这些方法在额外视图中使用 before-calendar-viewafter-calendar-view,如下所述。

高级用法

UI 自定义

当在视图中渲染时,您可以使用以下属性来自定义组件的行为

  • week-starts-at 可以是一个从 0 到 6 的数字,根据 Carbon 的工作日来表示日历应该从星期几开始渲染。

  • event-view 可以是任何 blade.php 视图,它将被用来渲染事件卡片。此视图将注入一个 $event 变量,其中包含其数据。

  • before-calendar-viewafter-calendar-view 可以是任何 blade.php 视图,可以在日历之前或之后渲染。这些可以用于通过 Livewire 向组件添加额外功能。

  • drag-and-drop-classes 可以是用于在日历的每一天上拖动事件时渲染悬停效果的任何 CSS 类。默认情况下,此值为 border border-blue-400 border-4

  • day-of-week-view 可以是任何用于渲染每个日历日标题的 blade.php 视图。此视图将注入 day 属性,它是一周中某天的 Carbon 实例。

<livewire:appointments-grid
    week-starts-at="0, 1, 2, 3, 4, 5 or 6. 0 stands for Sunday"
    event-view="path/to/view/starting/from/views/folder"
    day-of-week-view="path/to/view/starting/from/views/folder"
    before-calendar-view="path/to/view/starting/from/views/folder"
    after-calendar-view="path/to/view/starting/from/views/folder"
    drag-and-drop-classes="css classes"
/>

高级 UI 定制

(应使用基于组件默认视图的 blade 视图来使用这些选项)

要使用这些选项,建议发布组件使用的基 blade 视图,并按您的喜好扩展其行为和样式。为此,请运行 php artisan vendor:publish 并导出 livewire-calendar 标签。

  • calendar-view 可以是任何渲染整个组件的 blade.php 视图。建议用修改后的基 calendar-view 覆盖此视图,例如在组件旁边添加一个视图。

  • day-view 可以是任何用于渲染每月每一天的 blade.php 视图。此视图将注入以下属性:componentId(Livewire 组件的 id) , day(作为 Carbon 实例的月份中的某一天) , dayInMonth(该天是否属于月份) , isToday(该天是否是今天的日期) , events(与该天对应的事件集合)

示例

<livewire:appointments-grid
    calendar-view="path/to/view/starting/from/views/folder"
    day-view="path/to/view/starting/from/views/folder"
/>

交互定制

您可以通过覆盖以下方法来为您的组件添加交互性

public function onDayClick($year, $month, $day)
{
    // This event is triggered when a day is clicked
    // You will be given the $year, $month and $day for that day
}

public function onEventClick($eventId)
{
    // This event is triggered when an event card is clicked
    // You will be given the event id that was clicked 
}

public function onEventDropped($eventId, $year, $month, $day)
{
    // This event will fire when an event is dragged and dropped into another calendar day
    // You will get the event id, year, month and day where it was dragged to
}

自动轮询

如果需要,您也可以使用 pollMillis 参数添加自动轮询。您可以使用 pollAction 组合,以便在期望的轮询间隔内调用组件中的特定操作。

禁用交互

默认情况下,点击和拖/放下事件是启用的。要禁用它们,您可以在渲染组件时使用以下参数

<livewire:appointments-grid
    :day-click-enabled="false"
    :event-click-enabled="false"
    :drag-and-drop-enabled="false"
/>

测试

composer test

变更日志

请参阅 变更日志 了解最近更改的详细信息。

贡献

请参阅 贡献指南 了解详细信息。

安全

如果您发现任何安全相关的问题,请通过电子邮件 santibanez.andres@gmail.com 而不是使用问题跟踪器。

鸣谢

许可证

MIT 许可证(MIT)。请参阅 许可证文件 了解更多信息。