README

根据其当前状态在看板板上显示记录/数据的生活组件。

预览

安装

您可以通过 composer 安装此包

composer require mantix/livewire-kanban-board

需求

此包在内部使用 laravel/laravel (https://laravel.net.cn/) 和 livewire/livewire (https://livewire.laravel.net.cn/)。

它还使用 Bootstrap CSS (https://bootstrap.ac.cn/) 进行基本样式设置。

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

使用方法

为了使用此组件，您必须创建一个新的从 LivewireKanbanBoard 扩展的生活组件

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

php artisan make:livewire SalesOrdersKanbanBoard

在 SalesOrdersKanbanBoard 类中，不要从基本的 Livewire Component 类扩展，而是从 LivewireKanbanBoard 扩展。另外，删除 render 方法。您将有一个类似以下片段的类。

class SalesOrdersKanbanBoard extends LivewireKanbanBoard
{
    //
}

在这个类中，您必须重写以下方法以显示数据

public function statuses() : Collection 
{
    //
}

public function records() : Collection 
{
    //
}

如您所见，这两个方法都返回一个集合。statuses() 指的是数据可能在不同的时间点具有的不同状态值。records() 则代表您想要显示的数据，这些数据可能位于之前定义的 statuses() 集合中的任何一个。

让我们通过讨论销售订单及其在销售过程中的不同状态（注册、待确认、已确认、已交付）的例子来展示这两个方法如何一起工作：每个销售订单可能在特定时间点处于不同的状态。对于此示例，我们可能为 statuses() 定义以下集合

public function statuses() : Collection
{
    return collect([
        [
            'id' => 'registered',
            'title' => 'Registered',
        ],
        [
            'id' => 'awaiting_confirmation',
            'title' => 'Awaiting Confirmation',
        ],
        [
            'id' => 'confirmed',
            'title' => 'Confirmed',
        ],
        [
            'id' => 'delivered',
            'title' => 'Delivered',
        ],
    ]);
}

对于每个我们定义的 status，我们必须返回一个至少包含 2 个键的数组：id 和 title。

现在，对于 records()，我们可能定义来自我们项目中 Eloquent 模型的一组销售订单

public function records() : Collection
{
    return SalesOrder::query()
        ->map(function (SalesOrder $salesOrder) {
            return [
                'id' => $salesOrder->id,
                'title' => $salesOrder->client,
                'status' => $salesOrder->status,
            ];
        });
}

如您在上面的片段中看到的，我们必须返回一个包含数组项的集合，其中每个项至少包含 3 个键：id、title 和 status。最后一个是最重要的，因为它将被用于匹配记录属于哪个 status。为此，组件通过以下比较将 status 和 records 匹配

$status['id'] == $record['status'];

要在一个视图中渲染组件，只需使用 Livewire 标签或包含语法即可

<livewire:sales-orders-kanban-board />

填充销售订单模型，您应该得到以下截图类似的结果

您可以使用这种方法渲染项目中的任何渲染和状态 👍

排序和拖动

默认情况下，排序和在不同状态之间的拖动是禁用的。要启用它，您必须在使用视图时包含以下属性：sortable 和 sortable-between-statuses

<livewire:sales-orders-kanban-board 
    :sortable="true"
    :sortable-between-statuses="true"
/>

sortable 允许在每个状态内进行排序，而 sortable-between-statuses 允许从状态拖放到另一个状态。添加这两个属性，您就可以实现拖放功能。

您还必须在项目中安装以下 JS 依赖项以启用排序和拖动。

npm install sortablejs

安装后，在窗口对象中全局可用。这可以通过与您的Laravel应用程序一起提供的bootstrap.js文件来完成。

window.Sortable = require('sortablejs').default;

行为和交互

当启用排序和拖动时，您的组件可以在这些事件发生时被通知。这两个事件触发的回调是onStatusSorted和onStatusChanged

在onStatusSorted中，您将被告知哪个record在其status中改变了位置。您还将获得一个包含排序后records的id的$orderedIds数组。您必须覆盖以下方法来接收此更改的通知。

public function onStatusSorted($recordId, $statusId, $orderedIds)
{
    //   
}

当record被移动到另一个status时，将触发onStatusChanged。在这种情况下，您将收到有关更改的record、新的status、从上一个状态到排序的id以及记录进入的新状态的排序id的通知。要接收此事件的通知，您必须覆盖以下方法

public function onStatusChanged($recordId, $statusId, $fromOrderedIds, $toOrderedIds)
{
    //
}

onStatusSorted和onStatusChanged不会同时触发。在交互发生时，您将收到其中之一的通知。

您还可以通过onRecordClick事件在状态板上点击记录时收到通知

public function onRecordClick($recordId)
{
    //
}

要启用onRecordClick，您必须在通过record-click-enabled参数渲染组件时指定此行为

<livewire:sales-orders-kanban-board 
    :record-click-enabled="true"
/>

样式

要修改组件的外观和感觉，您可以覆盖styles方法，并修改此方法返回给视图的基本样式。 styles()返回一个键值数组，其中包含用于渲染组件的Tailwind CSS类。这些基本键和样式是

return [
    'wrapper' => 'd-flex flex-nowrap overflow-x-auto rounded', // component wrapper
    'statusWrapper' => 'flex-shrink-0', // statuses wrapper
    'statusWidth' => 272, // statuses column width
    'status' => 'flex-column rounded bg-primary fw-bold mx-1 px-2', // status column wrapper 
    'statusHeader' => 'py-2 fs-5', // status header
    'statusFooter' => '', // status footer
    'statusRecords' => '', // status records wrapper 
    'record' => 'bg-white shadow rounded border fw-normal p-2 my-2', // record wrapper
    'recordContent' => '', // record content
];

以下是一个覆盖styles()方法的示例

public function styles()
{
    $baseStyles = parent::styles();

    $baseStyles['wrapper'] = 'd-flex flex-nowrap overflow-x-auto rounded';

    $baseStyles['statusWrapper'] = 'flex-shrink-0';

    $baseStyles['statusWidth'] = 300;

    $baseStyles['status'] = 'flex-column rounded bg-primary fw-bold mx-1 px-2';

    $baseStyles['statusHeader'] = 'py-2 fs-5';

    $baseStyles['statusRecords'] = 'overflow-y-auto';

    $baseStyles['record'] = 'bg-white shadow rounded border fw-normal p-2 my-2';

    return $baseStyles;
}

有了这些新样式，您的组件应该看起来像下面的截图

看起来像Trello，对吧？ 😅

高级样式和行为

组件的基本视图可以根据需要导出到您的项目中。为此，运行php artisan vendor:publish命令并导出livewire-kanban-board-views标签。该命令将在/resources/views/vendor/livewire-kanban-board下发布基本视图。您可以按需修改这些基本组件，同时注意维护沿途的data属性和ids。

另一种方法是复制基本视图文件到您自己的视图文件中，并将其直接传递给组件

<livewire:sales-orders-kanban-board 
    kanban-board-view="path/to/your/kanban-board-view"
    status-view="path/to/your/status-view"
    status-header-view="path/to/your/status-header-view"
    status-footer-view="path/to/your/status-footer-view"
    record-view="path/to/your/record-view"
    record-content-view="path/to/your/record-content-view"
/>

注意：使用这种方法还可以让您向组件添加额外的行为，例如在标题、页脚等处添加点击事件，例如过滤器或其他任何操作

添加额外视图

组件允许您在状态板渲染前后添加视图。这两个占位符可以用于向组件添加额外功能，如搜索输入或操作工具栏。要使用它们，只需在显示组件时传递您想要使用的视图到before-kanban-board-view和after-kanban-board-view属性。

<livewire:sales-orders-kanban-board 
    before-kanban-board-view="path/to/your/before-kanban-board-view"
    after-kanban-board-view="path/to/your/after-kanban-board-view"  
/>

注意：这些视图是可选的。

在以下示例中，已指定before-kanban-board-view以添加搜索文本框和按钮

测试

composer test

变更日志

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

贡献

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

安全

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

致谢

• Pieter Naber
• Mantix BV
• Andrés Santibáñez
• 所有贡献者

许可

MIT许可（MIT）。有关更多信息，请参阅许可文件