README

演示

安装

您可以通过 composer 安装此软件包

composer require asantibanez/laravel-blade-sortable

在安装完软件包后，请确保将 laravel-blade-sortable::scripts 组件添加到您其他脚本旁边。

<x-laravel-blade-sortable::scripts/>
<script src="/js/app.js"></script>

需求

软件包需要安装 SortableJs 和 AlpineJs 以启用排序功能。请参考它们各自的文档以进行设置。

注意： SortableJs 必须在 JavaScript 的 window 对象级别可用。为此，可以使用以下方式导入库：

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

或使用任何其他类似方法

使用方法

该软件包提供了 2 个自定义 Blade 组件，用于启用 DOM 元素的排序

laravel-blade-sortable::sortable
laravel-blade-sortable::sortable-item

可排序组件

laravel-blade-sortable::sortable 用于作为可排序/拖放项的包装元素。它必须用于包围它将启用排序的子元素。

<x-laravel-blade-sortable::sortable>
    {{-- Items here --}}
</x-laravel-blade-sortable::sortable>

默认情况下，该组件渲染一个 "div" 作为包装节点。您可以通过传递一个 as 属性来自定义此行为，以渲染所需的节点类型。

<x-laravel-blade-sortable::sortable
    as="ul" {{-- Will render an unordered list wrapper node --}}
>
    {{-- Items here --}}
</x-laravel-blade-sortable::sortable>

注意：您传递的任何其他属性（例如 class、id、alt 等）都将添加到元素中

如果您想使用自定义 Blade 组件作为包装节点，也可以通过传递一个 component 属性来实现。

<x-laravel-blade-sortable::sortable
    component="custom-blade-component" {{-- Will render "x-custom-blade-component" --}}
>
    {{-- Items here --}}
</x-laravel-blade-sortable::sortable>

可排序项

laravel-blade-sortable::sortable-item 用于作为每个您想启用排序的项的包装元素。

<x-laravel-blade-sortable::sortable>
    <x-laravel-blade-sortable::sortable-item sort-key="jason">
        Jason
    </x-laravel-blade-sortable::sortable-item>
    <x-laravel-blade-sortable::sortable-item sort-key="andres">
        Andres
    </x-laravel-blade-sortable::sortable-item>
    <x-laravel-blade-sortable::sortable-item sort-key="matt">
        Matt
    </x-laravel-blade-sortable::sortable-item>
    <x-laravel-blade-sortable::sortable-item sort-key="james">
        James
    </x-laravel-blade-sortable::sortable-item>
</x-laravel-blade-sortable::sortable>

注意：与 laravel-blade-sortable::sortable 类似，您可以通过传递一个 as 或 component 属性来渲染所需的节点或自定义组件。

注意：可以将额外的属性（例如 class、id、alt 等）传递给并添加到项节点。

如您所注意到的，每个 laravel-blade-sortable::sortable-item 都需要一个 sort-key 属性。此属性将用于跟踪元素的排序顺序。它也应该是唯一的。

就是这样。现在您已经使用 Laravel Blade 渲染了一个可排序列表，无需任何自定义 JavaScript。🔥

虽然这个例子看起来很糟糕 😅。但是，您可以直接传递任何自定义组件或样式，因此可以根据需要自定义包装器和项节点。以下是一个使用 TailwindCSS ❤️ 和自定义组件的另一个示例

看起来很酷，对吧？ 👌

高级使用方法

作为表单输入

元素的排序顺序可以与表单提交上的其他输入字段一起使用。要启用此行为，只需将 name 属性传递给 laravel-blade-sortable::sortable 组件。该 name 应该是表单中输入的名称。

<form>
    <x-laravel-blade-sortable::sortable
        name="sort_order"
    >
        {{-- Items here --}}
    </x-laravel-blade-sortable::sortable>
</form>

通过添加 name 属性，组件内部为每个项的 sort-key 添加了隐藏输入。

非常棒！ 👌

与 Livewire 一起使用

进入了 Livewire？它很棒。我们知道。

您可以在 Livewire 视图中使用此软件包，并在组件中使用排序信息。

要获取 "sort change" 更新，只需在 x-laravel-blade-sortable::sortable 组件中添加 wire:onSortOrderChange 属性。添加此属性将在排序事件发生时触发 Livewire 组件，并调用指定的方法/回调。

<x-laravel-blade-sortable::sortable
    name="dropzone"
    wire:onSortOrderChange="handleSortOrderChange"
>
    {{-- Items here --}}
</x-laravel-blade-sortable::sortable>

在上面的示例中，每次对项目进行排序时，都会调用 handleSortOrderChange 方法，并将包含当前排序顺序中项目 sort-key 的数组作为参数传递。

还会传递额外的信息，以便在处理排序顺序时检查额外数据。

public function handleOnSortOrderChanged($sortOrder, $previousSortOrder, $name, $from, $to)
{
    // $sortOrder = new keys order
    // $previousSortOrder = keys previous order
    // $name = drop target name
    // $from = name of drop target from where the dragged/sorted item came from
    // $to = name of drop target to where the dragged/sorted item was placed
}

自定义

为了支持 SortableJs 的一些高级功能，可以将以下属性传递给 laravel-blade-sortable::sortable 组件

animation：排序动画运行所需的时间（毫秒）。默认值为 150。
ghost-class：在排序期间添加到被拖动对象的类。默认值为 null。只能使用 1 个类。
drag-handle：用作拖动句柄的类名。只有具有该类的 DOM 元素才能启用排序。

<x-laravel-blade-sortable::sortable
    animation="1000"
    ghost-class="opacity-25"
    drag-handle="drag-handle"
>
    {{-- Items here --}}
</x-laravel-blade-sortable::sortable>

多个拖放区域

想要有不同拖放区域来拖放/排序元素吗？我们为您提供了解决方案。😎

只需向 laravel-blade-sortable::sortable 组件添加一个 group 字符串属性。在相同页面上将相同属性添加到另一个 laravel-blade-sortable::sortable 组件中，然后！完成！

<x-laravel-blade-sortable::sortable
    group="people"
>
    {{-- Items here --}}
</x-laravel-blade-sortable::sortable>

<x-laravel-blade-sortable::sortable
    group="people"
>
    {{-- Items here --}}
</x-laravel-blade-sortable::sortable>

启用/禁用排序和/或拖放

使用 :allow-sort=true|false 和 :allow-drop=true|false 来启用/禁用 x-laravel-blade-sortable::sortable 组件中的元素排序和/或拖放。

两者都默认为 true。

<x-laravel-blade-sortable::sortable
    group="people"
    :allow-sort="false"
    :allow-drop="false"
>
    {{-- Items here --}}
</x-laravel-blade-sortable::sortable>

测试

composer test

变更日志

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

贡献

请参阅 CONTRIBUTING 了解详细信息。

安全

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

鸣谢

许可

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

akramzerarka / laravel-blade-sortable

维护者

详细信息