README

从https://github.com/asantibanez/livewire-status-board分支

Livewire Status Board

根据当前状态显示记录/数据的Livewire组件

预览

安装

您可以通过composer安装此包

composer require asantibanez/livewire-status-board

要求

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

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

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

使用方法

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

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

php artisan make:livewire SalesOrdersStatusBoard

在SalesOrdersStatusBoard类中，不要从基本的Livewire Component类扩展，而要从LivewireStatusBoard扩展。还要删除render方法。您将有一个类似以下代码段的类。

class SalesOrdersStatusBoard extends LivewireStatusBoard
{
    //
}

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

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。最后一个是最重要的，因为它将用于将record与哪个status匹配。为此，组件通过以下比较匹配status和records：

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

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

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

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

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

排序和拖拽

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

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

sortable启用每个状态内的排序，而sortable-between-statuses允许拖放从一个状态到另一个状态。添加这两个属性，允许您实现拖放功能。

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

npm install sortablejs

安装后，请在全局的window对象中使其可用。这可以在随您的Laravel应用程序一起提供的bootstrap.js文件中完成。

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

行为和交互

当启用排序和拖动时，组件会在以下事件发生时收到通知。由这两个事件触发的回调函数是 onStatusSorted 和 onStatusChanged

在 onStatusSorted 中，您可以得知哪个 record 在其 status 中改变了位置。同时，您还会收到一个 $orderedIds 数组，其中包含排序后 records 的 ID。您必须重写以下方法以接收此更改的通知。

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

在 onStatusChanged 被触发时，表示一个 record 被移动到另一个 status。在这种情况下，您会收到有关更改的 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-status-board 
    :record-click-enabled="true"
/>

样式

要修改组件的外观和感觉，您可以通过重写 styles 方法并将此方法返回的基本样式修改到视图中来实现。 styles() 返回一个键值数组，其中包含用于渲染每个组件的 Tailwind CSS 类。这些基本键和样式如下

return [
    'wrapper' => 'w-full h-full flex space-x-4 overflow-x-auto', // component wrapper
    'statusWrapper' => 'h-full flex-1', // statuses wrapper
    'status' => 'bg-blue-200 rounded px-2 flex flex-col h-full', // status column wrapper 
    'statusHeader' => 'p-2 text-sm text-gray-700', // status header
    'statusFooter' => '', // status footer
    'statusRecords' => 'space-y-2 p-2 flex-1 overflow-y-auto', // status records wrapper 
    'record' => 'shadow bg-white p-2 rounded border', // record wrapper
    'recordContent' => '', // record content
];

以下是一个重写 styles() 方法的示例

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

    $baseStyles['wrapper'] = 'w-full flex space-x-4 overflow-x-auto bg-blue-500 px-4 py-8';

    $baseStyles['statusWrapper'] = 'flex-1';

    $baseStyles['status'] = 'bg-gray-200 rounded px-2 flex flex-col flex-1';

    $baseStyles['statusHeader'] = 'text-sm font-medium py-2 text-gray-700';

    $baseStyles['statusRecords'] = 'space-y-2 px-1 pt-2 pb-2';

    $baseStyles['record'] = 'shadow bg-white p-2 rounded border text-sm text-gray-800';

    return $baseStyles;
}

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

看起来像 Trello，对吧？ 😅

高级样式和行为

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

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

<livewire:sales-orders-status-board 
    status-board-view="path/to/your/status-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-status-board-view 和 after-status-board-view props。

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

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

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

测试

composer test

变更日志

请参阅 CHANGELOG 了解最近更改的详细信息。

贡献

请参阅 CONTRIBUTING 了解详细信息。

安全

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

鸣谢

许可协议

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

nohumans / livewire-status-board

维护者

详细信息