README

一个基于TALL的Laravel Livewire组件，用于用漂亮的卡片替换（多选）HTML输入表单。

1. 功能

易于使用的select multiple HTML输入元素的替代品。
显示最多3个模型属性的卡片
可选：搜索
可选：“加载更多...”（Eloquent分页）

2. 使用

2.1 Livewire组件

该包提供了一个Livewire组件，您可以在Laravel项目的任何地方使用它 - 例如，在模态框、表单或着陆页中。

2.1.1 示例

像往常一样将组件添加到blade视图中。

<div class="bg-gray-100">
  @livewire('tall-multiselect-cards', ['identifier' => 'User'])
</div>

请注意，您需要通过添加必要的标识符参数来确定组件应使用哪种配置。

2.2 触发的事件

当用户点击保存按钮时，组件会触发一个事件，允许您与组件交互。

触发的事件名称将以所选的标识符后缀（见配置值 - [1]）使用组件多次（可能在同一页上）。它包含一个数组，该数组包含通过勾选卡片而选定的模型ID（配置为用作uniqueId属性的模型属性值）。

2.2.1 示例事件/实现

事件名称：tall-multiselect-cards-User
事件数据：[2, 4, 42]

注意：如果没有选择卡片，事件将触发并包含一个空数组。

其他组件需要监听此事件并调用一个方法来进一步处理它。如果您不熟悉Livewire中的事件监听，请参阅官方Livewire文档。

示例：重构一个之前使用 wire:model="state.users" 接受和处理表单输入的Livewire组件。

class AwesomeForm extends Component
{
    public $state = [];
 
    protected $listeners = ['tall-multiselect-cards-User' => 'addSelectedUsers'];
 
    public function addSelectedUsers($value)
    {
        // Do whatever you want... validation, processing, etc...
        $this->state['users'] = $value;
    }
}

3. 安装

此包需要PHP 8.0、Laravel 8.0和Livewire 2.5或更高版本。

通过composer安装

composer require codeadminde/tall-multiselect-cards

3.1 视图

该包提供了预设计的视图，这些视图已准备好使用TailwindCSS（v2）。要使用这些视图，请确保您已经安装了Tailwind CSS。您可以在 https://tailwind.org.cn/docs/guides/laravel 找到官方安装指南。

如果您想更改/覆盖提供的视图，请通过以下方式发布它们：

php artisan vendor:publish --tag=tall-multiselect-cards-views

发布后，您将在 resources/views/vendor/tall-multiselect-cards/ 中找到视图。

3.2 语言

以下语言提供了翻译文件：

英语（en）
德语（de）

如果您想更改/覆盖提供的语言文件，请通过以下方式发布它们：

php artisan vendor:publish --tag=tall-multiselect-cards-lang

发布后，您将在 resources/lang/vendor/tall-multiselect-cards/ 中找到语言文件。

4. 配置

默认配置已准备好使用Laravel的默认用户模型。如果您想更改默认配置，请通过以下方式发布配置文件：

php artisan vendor:publish --tag=tall-multiselect-cards-config

发布后，您将在 config/tall-multiselect-cards.php 中找到配置文件。

4.1 配置值

以下默认配置将随软件包一起提供。您可以直接使用Laravel默认的User模型。

    'User' => [ // [1]
        'model' => 'App\Models\User', // [2]
        'modelAttributes' => [  // [3]
            'uniqueId' => 'id', // unique model id (string)
            'primary' => 'name', // string OR NULL
            'secondary' => 'email',  // string OR NULL
            'optional' => NULL,  // string OR NULL
        ],
        'settings' => [ // [4]
            'paginate_data' => true, // [4.1] (boolean)
            'paginate_data_per_page' => 15, // [4.2] (integer)
            'enable_optional_brackets' => false, // [4.3] (boolean)
            'hide_search' => false, // [4.4] (boolean)
            'search_color_focus' => 'blue-400', // [4.5]
            'search_color_bg_focus' => 'blue-100', // [4.5]
            'card_color_bg' => 'white', // [4.5]
            'card_color_bg_hover' => 'blue-100', // [4.5]
            'card_color_bg_focus' => 'blue-100', // [4.5]
            'card_color' => 'gray-500', // [4.5]
            'card_color_selected' => 'blue-600', // [4.5]
            'card_color_hover' => 'blue-400', // [4.5]
            'card_color_focus' => 'blue-400', // [4.5]
            'primary_button_color_bg' => 'gray-800', // [4.5]
            'primary_button_color_bg_hover' => 'gray-700', // [4.5]
            'primary_button_color_bg_focus' => 'gray-700', // [4.5]
            'primary_button_color_text' => 'white', // [4.5]
            'primary_button_color_text_hover' => 'white', // [4.5]
            'primary_button_color_text_focus' => 'white', // [4.5]
            'secondary_button_color_border' => 'gray-600', // [4.5]
            'secondary_button_color_border_hover' => 'gray-400', // [4.5]
            'secondary_button_color_border_focus' => 'gray-400', // [4.5]
            'secondary_button_color_text' => 'gray-900', // [4.5]
            'secondary_button_color_text_hover' => 'gray-400', // [4.5]
            'secondary_button_color_text_focus' => 'gray-400', // [4.5]
        ]
    ],

[1] 标识符：提供一个字符串来标识特定的配置/组件。请注意，此值应仅包含alpha_dash字符。
[2] model：您想与组件一起使用的模型类的FQCN（完全限定类名）。
[3] modelAttributes：您想作为卡片内容显示的模型属性。
- 重要：uniqueId不会作为卡片内容显示，需要将其设置为包含模型ID（或UUID）的属性。这通常是数据库中的id列。
[4] settings：组件的设置数组。
- [4.1] paginate_data：启用或禁用分页。
  - 启用：组件仅从数据库中加载配置的模型数量（[4.2]）。将显示“加载更多...”链接以添加配置的数量（[4.2]）的模型，直到所有模型都加载完毕。
  - 禁用：组件一次从数据库中加载所有模型。
- [4.2] paginate_data_per_page：初始加载并将添加的卡片数量。
  - 当加载更多模型时。
  - 。
- [4.3] enable_optional_brackets：启用或禁用optional卡片位置的括号。当您将attributes.optional设置为NULL时，应禁用此选项。
  - 启用：optional属性值将在括号内显示。
  - 禁用：optional属性值将无括号显示。
- [4.4] hide_search：启用或禁用搜索输入。
- [4.5] *_color_*：您可以自由编辑组件的颜色方案。配置项目已被选择为具有自解释性，以确保易于样式化。您可以使用TailwindCSS颜色调色板中提供的任何颜色。

所有配置值都是必需的，除非另有说明，否则需要返回一个字符串。

5. 宏

可用的宏允许您操作检索到的数据。只需将它们添加到您应用程序的ServiceProvider的boot方法中。（例如，'AppServiceProvider'）。

5.1 查询

要扩展/覆盖加载初始数据的数据库查询，实现query宏。

示例

TallMultiselectCards::macro('query', function ($model, $selectedAttributes)
{
    return $model::select($selectedAttributes)->where('is_suspended', false);
});

5.2 过滤器

如果您想操作由数据库查询返回的集合，请实现filter宏。

TallMultiselectCards::macro('filter', function ($collection)
{
    $filtered = $collection->filter(function ($item) {
        if (!$item->is_expired) {
            return $item;
        }
    });

    return $filtered;
});

注意：您不应该操作项目本身的结构，因为集合将被进一步处理。如果在此处添加/删除集合中的项目，请使用不带分页的包，以避免意外的分页结果。

6. 测试

请先安装开发依赖项。然后您可以通过composer运行测试。

使用testbench二进制文件进行测试：composer test
使用PHPUnit二进制文件进行测试：composer test-p

7. 反馈/支持/安全

如果您需要反馈或支持，请通过gh-security@it-habich.de联系我。

如果您发现与安全相关的问题，请勿使用问题跟踪器，而是通过电子邮件联系我。

8. 许可证

本存储库的内容在MIT许可下发布。

check-circle SVG在MIT许可下授权，并由tailwindlabs/heroicons提供。

codeadminde / tall-multiselect-cards

维护者

详情