README

轻松将看板页面添加到您的 Filament 面板。

安装

您可以通过 composer 安装此包

composer require mokhosh/filament-kanban

发布资产以确保样式正确

php artisan filament-kanban:install

开始之前

重要

您应该有一些具有 status 列的 Model。此列可以在数据库中称为 status 或其他任何名称。

我还假设您的模型中有一个 title 列，但您可以使用 name 或其他任何列来表示标题。

我建议您创建一个基于字符串的 Enum 来定义您的状态。

您可以使用我们的 IsKanbanStatus 特性，这样您就可以通过在您的枚举上使用 statuses 方法轻松地将枚举情况转换为看板。

use Mokhosh\FilamentKanban\Concerns\IsKanbanStatus;

enum UserStatus: string
{
    use IsKanbanStatus;

    case User = 'User';
    case Admin = 'Admin';
}

我建议您将您的 Model 上的 status 属性转换为您已创建的枚举。

技巧

我还建议您在您的 Model 上使用 Spatie Eloquent Sortable 包，我们将神奇地将排序能力添加到您的看板。

用法

您可以使用以下 artisan 命令创建一个名为 UsersKanbanBoard 的新看板

php artisan make:kanban UsersKanbanBoard

这为您提供了看板的良好起点。您可以根据需要自定义看板。

您应该重写 model 属性，以便我们可以加载您的记录。

protected static string $model = User::class;

您还应该重写 statusEnum 属性，该属性定义了您的状态。

protected static string $statusEnum = UserStatus::class;

升级指南

如果您在应用程序中拥有 1.x 版本，并希望升级到 2.x 版本，以下是一份清单

• 您需要重写如 最后部分 中所述的 $model 和 $statusEnum
• 如果您已发布 kanban-record.blade.php 视图，您可以使用 $record 作为 Model 实例而不是数组。
• 如果您只是覆盖 KanbanBoard 方法以执行默认行为，现在可以安全地删除它们。如果您没有特殊要求，您应该能够通过覆盖 0 个方法来解决问题 🥳

高级用法

您可以通过覆盖 records 方法来自定义您希望在板上显示的记录或项目。

protected function records(): Collection
{
    return User::where('role', 'admin')->get();
}

如果您不想为您的状态定义一个 Enum，或者您有检索状态的特定逻辑，您可以覆盖 statuses 方法

protected function statuses(): Collection
{
     return [
         ['id' => 'user', 'title' => 'User'],
         ['id' => 'admin', 'title' => 'Admin'],
     ];
}

您还可以覆盖这些方法以更改记录拖放时的板行为

• onStatusChanged 定义了记录在状态之间移动时会发生什么。
• onSortChanged 定义了记录在相同状态内移动时会发生什么。

public function onStatusChanged(int $recordId, string $status, array $fromOrderedIds, array $toOrderedIds): void
{
    User::find($recordId)->update(['status' => $status]);
    User::setNewOrder($toOrderedIds);
}

public function onSortChanged(int $recordId, string $status, array $orderedIds): void
{
    User::setNewOrder($orderedIds);
}

自定义状态枚举

如果您将 IsKanbanStatus 添加到您的状态 Enum 中，此特性将为您的枚举添加一个静态 statuses 方法，该方法将返回枚举中定义的状态，格式适当。

如果您不希望在板上显示枚举的所有情况，您可以覆盖此方法并返回情况子集

public static function kanbanCases(): array
{
    return [
        static::CaseOne,
        static::CaseThree,
    ];
}

IsKanbanStatus 使用您的案例的 value 作为状态标题。您还可以自定义标题的检索方式

public function getTitle(): string
{
    return __($this->label());
}

编辑模态框

禁用模态框

默认情况下，编辑模态已启用，您可以通过点击记录来显示它。

如果您需要禁用编辑模态，则覆盖此属性。

public bool $disableEditModal = false;

编辑模态表单模式

您可以通过覆盖此方法来定义编辑模态表单模式。

protected function getEditModalFormSchema(null|int $recordId): array
{
    return [
        TextInput::make('title'),
    ];
}

如您所见，您可以访问正在编辑的记录的 id，这在构建您的模式时可能很有帮助。

自定义编辑表单提交操作

您可以通过覆盖此方法来定义编辑表单提交时会发生什么。

protected function editRecord($recordId, array $data, array $state): void
{
    Model::find($recordId)->update([
        'phone' => $data['phone']
    ]);
}

data 数组包含表单数据，而 state 数组包含完整的记录数据。

自定义模态的外观

您可以自定义模态的标题、大小以及保存和取消按钮的标签。

protected string $editModalTitle = 'Edit Record';

protected string $editModalWidth = '2xl';

protected string $editModalSaveButtonLabel = 'Save';

protected string $editModalCancelButtonLabel = 'Cancel';

自定义

更改导航图标

protected static ?string $navigationIcon = 'heroicon-o-document-text';

更改用作标题的模型属性

protected static string $recordTitleAttribute = 'title';

更改用作状态的模型属性

protected static string $recordStatusAttribute = 'status';

自定义视图

您可以使用此 artisan 命令发布视图。

php artisan vendor:publish --tag="filament-kanban-views"

我建议您删除不打算自定义的文件，保留要更改的文件。这样，您将获得原始视图的任何可能的未来更新。

上述方法将替换应用程序中所有看板的所有视图。

或者，您可能想要更改某个看板的视图。您可以通过覆盖这些属性来覆盖每个视图。

protected static string $view = 'filament-kanban::kanban-board';

protected static string $headerView = 'filament-kanban::kanban-header';

protected static string $recordView = 'filament-kanban::kanban-record';

protected static string $statusView = 'filament-kanban::kanban-status';

protected static string $scriptsView = 'filament-kanban::kanban-scripts';

闪烁最近更新的记录

当记录刚刚更新时，您会得到一些视觉反馈。

如果您还使用 Spatie Eloquent Sortable，您可能会同时看到所有记录闪烁。这是因为 Eloquent Sortable 在排序更改时更新所有模型的 order_column。为了解决这个问题，发布它们的配置并将 ignore_timestamps 设置为 true。

视频教程

您是视觉学习者吗？我创建了一些 YouTube 视频来帮助您开始使用此软件包。

警告

这些视频是用软件包的 1.x 版本录制的。现在使用软件包要简单得多，您需要编写的代码也少得多。

希望 2.x 版本足够简单，不需要视频，但您仍然可以从这些视频中学习到一两点。

演示和示例

• 看板示例

• 看板待办事项

测试

composer test

变更日志

有关最近更改的更多信息，请参阅 CHANGELOG。

贡献

有关详细信息，请参阅 CONTRIBUTING。

安全漏洞

有关报告安全漏洞的详细信息，请参阅 我们的安全策略。

TODO

• 删除已弃用的最近更新特性
• 停止为记录点击传递记录
• 使用 filament 动作进行编辑模态

致谢

• Mo Khosh
• 所有贡献者
• 此软件包的原始想法和结构大量借鉴自 David Vincent 的 filament-kanban-board。

许可证

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