README

Livewire Combobox: 为 Laravel Livewire 提供动态选择

Laravel Livewire 多个选择相互依赖，具有无限级别的依赖关系，并且完全可配置。

要求

此包至少需要

PHP ^8.0
Laravel ^8.0
Laravel Livewire ^2.0
TailwindCSS ^2.0

安装

您可以通过 composer 安装此包

composer require daguilarm/livewire-combobox

使用助手 @LivewireComboboxCss 在 <head> 中添加包样式

<html>
    <head>
        @LivewireComboboxCss
    </head>
    <body>
        ...
    </body>
</html>

文档

通用方法

首先，您需要在您的 Livewire 文件夹中创建一个组件。以下是一个使用三个选择的示例

<?php

declare(strict_types=1);

namespace App\Http\Livewire;

use App\Models\Car;
use App\Models\Extra;
use App\Models\Option;
use Daguilarm\LivewireCombobox\Components\ComboboxLivewireComponent;
use Daguilarm\LivewireCombobox\Components\Fields\Select;
use Daguilarm\LivewireCombobox\Contracts\Combobox;

class ComboboxCars extends ComboboxLivewireComponent implements Combobox
{
    public function elements(): array
    {
        return [
            Select::make('Cars', Car::class)
                ->uriKey('key-for-car')
                ->options(function($model) {
                    return $model
                        ->pluck('name', 'id')
                        ->toArray();
                }),
            Select::make('Options for cars', Option::class)
                ->uriKey('key-for-options')
                ->dependOn('key-for-car')
                ->foreignKey('car_id')
                ->selectRows('id', 'option'),
            Select::make('Extras for cars')
                ->model(Extra::class)
                ->firstRemoved()
                ->hideOnEmpty()
                ->uriKey('key-for-extras')
                ->dependOn('key-for-options')
                ->foreignKey('option_id')
                ->selectRows('id', 'extra')
                ->withoutResponse(),
        ];
    }
}

包支持无限依赖元素。方法 elements() 应返回一个包含所有元素的数组。

让我们看看类的工作方式 Select::class 及其方法

make()

方法 make() 有以下结构

Select::make(string $label, ?string $model = null);

model()

如我们所见，属性 $model 在 make() 方法中是可选的，并且可以使用 model() 方法添加

Select::make('My label')->model(User::class);

⚠️ 定义模型是强制性的，但可以通过两种方式实现。

uriKey()

此方法强制使用，用于定义元素的唯一键。

hideOnEmpty()

如果子元素为空，则删除依赖子元素，而不是显示空字段。

withoutResponse()

当我们想让元素不向组件发送响应并仅作为表单字段工作时，即从其中删除所有 Laravel Livewire 代码。当它涉及到最后一个可选择的元素并且我们不希望向服务器发送请求时非常有用。

子元素

这些元素有其自己的方法，除了上面描述的。这些子元素不需要 options() 方法，尽管如果需要可以添加。以下是对特定于子元素的方法的描述

dependOn()

使用此方法，我们定义了我们的子元素所依赖的父元素。我们必须使用父元素的 uriKey。该方法的基结构如下

dependOn(?string $parentUriKey = null, ?string $foreignKey = null)

如我们所见，它接受第二个值，即连接两个模型（父模型 和 子模型）的外键。

foreignKey()

此第二个字段也可以以两种方式添加

// Option 1
Select::make(...)
    ->dependOn('key-for-options', 'option_id');

// Option 2
Select::make(...)
    ->dependOn('key-for-options')
    ->foreignKey('option_id');

selectRows()

它用于选择要加载到子元素中的表字段。

disabledOnEmpty()

如果您想在字段为空时禁用它...

字段类型

目前，此包支持以下字段类型

选择字段

这些字段具有以下方法

options()

它用于向元素 select 添加值。我们可以直接添加一个包含值的 array，或者定义一个 callback。由 array 返回的两个值：键和值，如下所示在 Blade 模板中显示

// The array
[
    1 => 'Car',
    2 => 'Bike',
    3 => 'Plane'
]

//Will be render as 
<option value="1">Car</option>
<option value="2">Bike</option>
<option value="3">Plane</option>

因此，在组件示例（将反向）中

// The array
Select::make(...)
    ->options(function($model) {
        return $model
            ->pluck('name', 'id')
            ->toArray();
    })

//Will be render as 
<option value="id">name</option>

firstRemoved()

默认情况下，每个项都将显示一个带有空 option 元素的 select 字段

// Element
<select>
    <option value=""></option>
    ...
</select>

如果您想删除它，可以添加 firstRemoved() 方法。

搜索字段

即将推出...

正在加载...

您可以通过修改组件中的属性 $loading 来激活或禁用加载状态

<?php

declare(strict_types=1);

namespace App\Http\Livewire;

use App\Models\Car;
use App\Models\Extra;
use App\Models\Option;
use Daguilarm\LivewireCombobox\Components\ComboboxLivewireComponent;
use Daguilarm\LivewireCombobox\Components\Fields\Select;
use Daguilarm\LivewireCombobox\Contracts\Combobox;

class ComboboxCars extends ComboboxLivewireComponent implements Combobox
{
    protected bool $loading = false;

    public function elements(): array
    {
        return [];
    }
}

默认情况下它是激活的（true）。模板文件位于：resources/views/vendor/livewire-combobox/loading.blade.php。

自定义元素显示

该包使用 TailwindCSS，因此样式必须基于它。元素的布局如下

<!-- Main container -->
<div id="container">

    <!-- Element 1 -->
    <div id="element-container-1">
        <label id="label-1"></label>
        <select id="select-1"></select>
    </div>

    <!-- Element 2 -->
    <div id="element-container-2">
        <label id="label-2"></label>
        <select id="select-2"></select>
    </div>

</div>

我们可以通过使用 $comboboxContainerClass 来修改从文档开始创建的组件中 主容器 的样式

<?php

declare(strict_types=1);

namespace App\Http\Livewire;

use App\Models\Car;
use App\Models\Extra;
use App\Models\Option;
use Daguilarm\LivewireCombobox\Components\ComboboxLivewireComponent;
use Daguilarm\LivewireCombobox\Components\Fields\Select;
use Daguilarm\LivewireCombobox\Contracts\Combobox;

class ComboboxCars extends ComboboxLivewireComponent implements Combobox
{
    protected string $containerClass = 'flex p-2 m-2 bg-gray-100';

    public function elements(): array
    {
        return [];
    }
}

要修改元素，我们需要直接对每个元素进行操作，使用方法 class()

Select::make('Cars', Car::class)
    ->uriKey('key-for-car')
    ->options(function($model) {
        return $model
            ->pluck('id', 'name')
            ->toArray();
    })
    ->class('p-4', 'text-green-600', 'text-lg'),

我们可以使用 PHP 8 的新功能来修改我们感兴趣的部分，或者我们可以直接使用该方法

// Method 1
Select::make(...)
    ->class(
        container: 'p-4',
        field: 'text-lg',
    ),

// Method 2
Select::make(...)
    ->class('p-4', null, 'text-lg'),

参数的顺序是

class(?string $container = null, ?string $label = null, ?string $field = null)

更新日志

有关最近更改的详细信息，请参阅更新日志

贡献

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

安全

如果您发现任何安全相关的问题，请通过电子邮件 damian.aguilarm@gmail.com 联系，而不是使用问题跟踪器。

致谢

许可证

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

daguilarm / livewire-combobox

维护者

详细信息