README

注意：此包仅供个人使用，因此一些功能非常具体，仅适用于我的项目（例如，直接导入未编译的.tsx和.scss文件）。

如果有人对使其更容易设置和更易于维护以供更广泛的受众使用感兴趣，请提交PR或开启讨论！

此外，您可以考虑使用以下所述基于此包的包。

Calendax允许您构建一个充满任何类型事件的Livewire日历。事件可以从任何模型或数据集中创建。

它深受Andrés Santibáñez的Livewire Calendar的启发。

预览

安装

您可以通过composer安装此包

composer require brickx/calendax

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="calendax-config"

这是发布配置文件的内容

return [

];

可选地，您可以使用以下命令发布视图

php artisan vendor:publish --tag="calendax-views"

要求

此包在底层使用livewire/livewire（https://laravel-livewire.com）。

它还使用TailwindCSS（https://tailwind.org.cn）进行样式设计。请在使用此组件之前确保包含这两个依赖项。

使用

初始化

首先，创建一个新的扩展Calendax的Livewire组件。

您可以使用make:livewire创建此组件。例如

php artisan make:livewire MyCalendar

然后，在创建的MyCalendar类中，扩展Calendax而不是从基类Component Livewire扩展

class MyCalendar extends \Brickx\Calendax\Calendax
{
    //
}

在这个类中，您必须重写以下方法以实现加载事件的自定义逻辑

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

此外，移除render方法，因为它将为您处理。

在events()方法中，您应该返回一个包含应在日历上显示的事件的集合。

加载事件（使用数组）

事件必须是键数组，至少包含以下键：id、title、description、date（必须是Carbon\Carbon实例）。

public function events() : Collection
{
    return collect([
        [
            'id' => 1,
            'title' => 'Breakfast',
            'description' => 'Pancakes! 🥞',
            'date' => Carbon::today(),
        ],
        [
            'id' => 2,
            'title' => 'Meeting with Camille',
            'description' => 'Random chit-chat.',
            'date' => Carbon::tomorrow(),
        ],
    ]);
}

date值将用于确定事件将显示在哪些天。

加载事件（使用Eloquent查询）

您还可以在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,
            ];
        });
}

渲染日历

现在您可以使用Blade组件将日历包含在任何视图中

<livewire:my-calendar />

这将渲染一个日历网格。

选择起始月份

默认情况下，组件将渲染当前月份。如果想要更改起始月份，可以设置year和month属性。

<livewire:my-calendar year='2016' month='06' />

启用拖放

要启用拖放，在@livewireScripts指令后包含@calendaxScripts。

@livewireScripts
@livewireCalendarScripts

处理导航

该组件有4个公共方法用于在月份之间导航

public function goToPreviousMonth()
public function goToCurrentMonth()
public function goToNextMonth()
public function goToMonth($month, $year = null)

例如，这些方法可以用来构建一个带有额外视图的导航系统。请查看以下部分了解示例用法。

高级使用

Blade自定义

在渲染您的Blade组件时，有一些额外的属性可用于自定义日历的行为

week-start 用于表示一周的开始日。它可以是一个从0到6的数字，根据 Carbon 的一周中的天数（0 = 星期天）。
drag-and-drop-classes 可以是任何用于在日历中拖放事件时渲染悬停效果的CSS类。默认值为 border border-4 border-blue-400。

<livewire:my-calendar week-start=1 drag-and-drop-classes='bg-orange-500' />

自定义视图

您还可以使用自定义的Blade视图来渲染日历的不同部分。

建议发布组件使用的基Blade视图，并根据您的喜好扩展其行为和样式。要这样做，请查看安装部分。

可以使用以下属性指定这些视图

calendar-view 用于渲染整个组件。请查看包的 calendar.blade.php 视图以了解哪些属性可用。
dow-view 用于渲染日历的每一列标题（通常包含星期几）。该视图将接收 $day 属性，它是一个关联星期几的 Carbon 实例。
day-view 用于渲染月份中的每一天。该视图将接收以下属性
- componentId（Livewire组件的id）
- day（月份中的天数，作为 Carbon 实例）
- dayInMonth（布尔值，指示该天是否是当前月的一部分）
- isToday（布尔值，指示该天是否是今天）
- events（与该天对应的事件集合）
event-view 用于渲染事件卡片。该视图将接收包含其数据的 $event 变量。
before-calendar-view 和 after-calendar-view 可以是任何在日历之前或之后渲染的Blade视图。这些可以用于向组件添加额外功能（例如导航系统）。

<livewire:my-calendar
	calendar-view='path/to/view/calendar.blade.php'
	dow-view='path/to/view/dow.blade.php'
	day-view='path/to/view/day.blade.php'
	event-view='path/to/view/event.blade.php'
	before-calendar-view='path/to/view/before-calendar.blade.php'
	after-calendar-view='path/to/view/after-calendar.blade.php'
/>

所有自定义视图路径都必须相对于 resources/views 目录。

交互性

提供了一些方法来与日历交互

public function onDayClick($year, $month, $day)
{
	// This event is triggered when a day is clicked
}

public function onEventClick($eventId)
{
	// This event is triggered when an event card is clicked
}

public function onEventDropped($eventId, $year, $month, $day)
{
	// This event is triggered when an event is dragged & dropped onto another calendar day
}

您可以通过重写它们来实现自定义逻辑。

默认情况下，启用了点击和拖放事件。要禁用它们，您可以在渲染组件时使用以下属性

<livewire:my-calendar
	:day-click-enabled='false'
	:event-click-enabled='false'
	:drag-and-drop-enabled='false'
/>

自动轮询

如果需要，您可以定义Livewire组件中的 $pollMillis 属性来添加自动轮询。

您还可以将其与 $pollAction 结合使用，以便在所需的轮询间隔内调用组件中的特定操作。

有关轮询的更多信息，请查看https://laravel-livewire.com/docs/2.x/polling。

Flatpickr

为了处理月份间的导航，此包使用了 Flatpickr 库。它显示了一个日历选择器，比简单的 <select> 要强大得多。

导入

首先，将Flatpickr库添加到您的 package.json 的依赖项中。

{
	"dependencies": {
		"flatpickr": "^4.6.13"
	}
}

然后，将此包的 flatpickr.scss 和 flatpickr.tsx 文件导入到您的主样式表和脚本中。

app.scss:

@use '../vendor/brickx/calendax/resources/sass/flatpickr';

app.js:

import calendax from '../../../vendor/brickx/calendax/resources/scripts/flatpickr';

calendax();

自定义

您可以根据主题定制日历选择器的颜色。要这样做，只需在导入 flatpickr.scss 时覆盖Sass变量即可。

@use '../vendor/brickx/calendax/resources/sass/flatpickr' with (
	$color-primary: saddlebrown,			// Basic color
	$color-accent: #FDBA74,				// Standard CSS color
	$color-contrast: rgb(118, 89, 71, 0.8),		// RGB color
	$color-range: theme('colors.orange.100')	// Tailwind theme color
);

测试

您可以使用以下命令使用 Pest 测试组件，具体取决于您的需求。

标准测试

composer test

带有覆盖率

composer test:coverage

并行测试

composer test:parallel

并行测试带有覆盖率

composer test:parallel-coverage

待办事项

理想情况下，用户不应需要手动操作他们的 sass & script 文件来导入正确的依赖项。所有操作都应在 Blade 内完成（至少应直接在 Blade 布局中导入样式和脚本）。参见：https://github.com/Laratipsofficial/laravel-flatpickr。
找到一种方法在 Flatpickr 组件中突出显示事件（这样用户可以立即看到哪些天有事件）。
在 README.md 中正确处理 Shields。查看：https://shieldsio.npmjs.net.cn/。
~~为 Flatpickr 组件创建测试~~
~~更新 README.md，说明如何正确设置 Flatpickr 组件~~
~~添加默认导航，理想情况下使用动态日历选择器（而不是基本的 <select>）。~~

更新日志

有关最近更改的更多信息，请参阅更新日志。

贡献

有关详细信息，请参阅贡献指南。

安全漏洞

请查阅我们的安全策略，了解如何报告安全漏洞。

致谢

许可证

MIT 许可证 (MIT)。有关更多信息，请参阅许可证文件。

brickx / calendax

维护者

详细信息