README

Livewire Filters 是一系列 Livewire 组件，为您提供工具，在您自己的 Livewire 组件中实时过滤数据。

需求

此包需要 Laravel 9.0+ 和 Livewire 2.10+。

安装

要开始使用，请通过 Composer 需求此包

composer require kirschbaum-development/livewire-filters

发布视图

包含的过滤器是用 Tailwind CSS 和 Tailwind CSS 表单插件 制作的。我们建议发布视图并更改标记以匹配您的项目使用的任何样式或 CSS 框架。

php artisan vendor:publish --tag=livewire-filters-views

发布配置

发布配置文件仅用于启用查询字符串使用。

php artisan vendor:publish --tag=livewire-filters-config

用法

定义您的过滤器

您可以通过包含包提供的 HasFilters 特性在 Livewire 组件中使用过滤器。

包含特性后，定义一个返回您想在组件中使用的 Filter 对象数组的 filters 方法。包含的 Filter 类具有一系列流畅的方法来构建每个过滤器的具体细节。

use HasFilters;

public function filters(): array
{
    return [
        Filter::make('title'),
        Filter::make('type')->options(['text', 'link', 'audio', 'video'])->default(['audio']),
        Filter::make('status')->options(['published', 'draft'])->default('published'),
    ];
}

使用您的过滤器

设置组件后，您可以在 Livewire 组件的视图文件中包含过滤器。为了设置过滤器，只需使用其中一个过滤器组件并传递通过其键指定的特定过滤器。组件将负责设置自身。

<livewire:livewire-filters-checkbox :filter="$filters['type']" />

下面有更多关于包中包含的过滤器信息。

确定过滤状态/计数

HasFilters 特性包含两个计算属性，您可以使用它们来确定是否有活动过滤器以及当前有多少过滤器处于活动状态。您可以直接在 Livewire 组件中使用 $this->isFiltered 或 $this->activeFilterCount 访问这些属性。您还可以选择将其中一个或两个属性传递给 Livewire 组件的 render 方法。

这些计算属性如果您想更改按钮的颜色、显示/隐藏 UI 的特定部分、显示活动过滤器的徽章或简单地显示有活动过滤器正在应用的视觉指示器，会很有用。

获取过滤值

因为 $filters 数组包含 Filter 对象，所以您需要访问 value 属性、使用 value() 方法或使用包含的 getFilterValue($key) 辅助方法。

// Helper included in the HasFilters trait
$this->getFilteredValue('type');

// Using the accessor
$this->filters['type']->value();

// Using the property directly
$this->filters['type']->value;

示例父组件

use App\Models\Post;
use Kirschbaum\LivewireFilters\Filter;
use Kirschbaum\LivewireFilters\HasFilters;
use Livewire\Component;

class PostsList extends Component
{
    use HasFilters;

    public function filters(): array
    {
        return [
            Filter::make('type')->options(['text', 'link', 'audio', 'video'])->default(['text', 'link']),
        ];
    }

    public function getPostsProperty()
    {
        return Post::query()
            ->when($this->getFilterValue('type'), fn ($query, $values) => $query->whereIn('type', $values))
            ->paginate();
    }

    public function render()
    {
        return view('livewire.posts-list', [
            'filterCount' => $this->filterCount,
            'isFiltered' => $this->isFiltered,
            'posts' => $this->posts,
        ]);
    }
}

包含的过滤器

此包包含 4 个基本过滤器，可用于您的 Livewire 组件。

复选框过滤器

复选框过滤器允许您选择任意数量的选项。每次更改时，过滤器都会发出包含当前选中值的数组的事件。

<livewire:livewire-filters-checkbox :filter="$filters['type']" />

单选按钮过滤器

单选按钮过滤器允许您从选项列表中选择单个选项。每次更改时，过滤器都会发出包含当前选中值的事件。

<livewire:livewire-filters-radio :filter="$filters['type']" />

选择菜单过滤器

与单选按钮过滤器类似，选择菜单过滤器允许您从选择菜单中的选项列表中选择单个选项。每次更改时，过滤器都会发出包含当前选中值的事件。

<livewire:livewire-filters-select :filter="$filters['type']" />

文本框过滤器

文本框过滤器允许您输入自由文本，您可以使用该文本进行过滤。每次更改都会触发一个事件，事件中包含文本字段的值。

<livewire:livewire-filters-text :filter="$filters['type']" />

Filter 类

Filter 类提供了一个流畅的接口，用于在 Livewire 组件中定义过滤器以及检索有关过滤器的信息。

make($key)

您必须首先调用 make 方法，并传递一个唯一键。在调用此方法后，您可以按任何顺序调用其他任何方法。

options($values)

如果您使用的是需要选项的过滤器，可以将这些值的数组传递给 options 方法。不传递任何参数调用 options 方法将返回过滤器的定义选项。

value($values)

如果您想设置过滤器的值，可以将值或值的数组传递给 value 方法。不传递任何参数调用 value 方法将返回过滤器的当前值。

default($values)

在定义过滤器时，应使用 default 方法设置过滤器的初始值。这将把初始值存储在对象中，有助于确定活动过滤器的状态以及将过滤器重置为其原始状态。不传递任何参数调用 default 方法将返回在定义过滤器时指定的初始值。

meta(array $values)

如果您想在视图中使用有关过滤器的额外信息，可以将值的数组传递给 meta 方法。不传递任何参数调用 meta 方法将返回当前的元信息数组。

事件

livewire-filters-reset

livewire-filters-updated

当过滤器更新时，将触发此事件，并带有两个参数：key 和 payload。应使用 key 来识别应更新的过滤器。 payload 是过滤器的新的值。

此事件由 HasFilters 特性自动处理。如果您想自定义更新处理方式，可以监听此事件并使用您自己的方法或覆盖 handleUpdateEvent 方法。

创建自己的过滤器

除了内置的过滤器外，您还可以根据需要创建额外的过滤器。

use Kirschbaum\LivewireFilters\FilterComponent;

class DateFilter extends FilterComponent
{
    public function render()
    {
        return view('livewire.filters.date-filter');
    }
}

<div
    x-data
    x-init="window.flatpickr($refs.flatpickr)"
>
    <input
        type="text"
        name="{{ $key }}"
        id="{{ $key }}"
        class="focus:ring-indigo-500 focus:border-indigo-500 block w-full pr-8 sm:text-sm border-gray-300 rounded-md"
        placeholder="Select a date..."
        readonly="readonly"
        x-ref="flatpickr"
        wire:model="value"
    >

    @if ($value !== $initialValue)
        <div class="absolute inset-y-0 right-2 flex items-center">
            <button type="button" class="text-gray-400 hover:text-gray-500" wire:click="resetValue">
                <svg xmlns="http://www.w3.org/2000/svg" class="h-5 w-5" viewBox="0 0 20 20" fill="currentColor"><path fill-rule="evenodd" d="M4.293 4.293a1 1 0 011.414 0L10 8.586l4.293-4.293a1 1 0 111.414 1.414L11.414 10l4.293 4.293a1 1 0 01-1.414 1.414L10 11.414l-4.293 4.293a1 1 0 01-1.414-1.414L8.586 10 4.293 5.707a1 1 0 010-1.414z" clip-rule="evenodd" /></svg>
                <span class="sr-only">Reset</span>
            </button>
        </div>
    @endif
</div>

变更日志

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

贡献

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

安全性

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

鸣谢

• David VanScott

赞助

本包的开发由 Kirschbaum 赞助，Kirschbaum 是一家以解决问题、团队建设和社区为中心的开发者驱动型公司。了解更多 关于我们 或 加入我们！

许可证

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