README

为 TALL (Tailwind CSS, Alpine.js, Laravel, Livewire) 堆栈创建的有用 UI 组件库。

包含

模态框
确认模态框
通知
表格（搜索、筛选、排序列）
加载指示器
拖放文件上传（Filepond）
Markdown 编辑器（Quill）
日期时间选择器（Flatpickr）

需求

此包需要安装并运行 Laravel、Tailwind CSS、Alpine.js 和 Livewire。

此包是为这些框架创建和测试的

Laravel v10
Tailwind CSS v3
Alpine.js v3
Livewire v3

其他版本可能会有一些差异。

安装

您可以通过 composer 安装此包

composer require vojislavd/tall-components

您需要在您的 resources/js/app.js 文件中包含 tc.js

import './../../vendor/vojislavd/tall-components/resources/js/tc.js'

接下来，您应该编译资源

npm install && npm run build

组件将使用 primary、primary-dark、secondary 和 secondary-dark 颜色。您应该在 tailwind.config.js 文件中配置这些颜色。

如果您想更改颜色或自定义其他内容，您可以使用以下命令发布所有组件视图

php artisan vendor:publish --tag="tall-components-views"

要更改颜色，只需在组件中找到 primary、primary-dark、secondary 或 secondary-dark 并将其替换为您想要使用的颜色。

用法

模态框

要使用模态框，您需要在您的 Livewire 组件中有一个布尔变量。模态框将根据该变量的值打开或关闭。

<?php

namespace App\Livewire;

use Livewire\Component;

class MyComponent extends Component
{
    public bool $openModal = false;
}

在同一个 Livewire 组件的 blade 文件中，您应该添加 <x-tc::modal> 并将 model 属性设置为与您在 Livewire 组件的 PHP 文件中添加的布尔变量匹配。

在 <x-tc::modal> 标签内，您可以添加任何您想要在模态框中显示的内容。

<x-tc-modal model="openModal">
    <h1>This is some title</h1>

    <p>This is some content</p>
</x-tc-modal>

您可以从 blade 文件中打开模态框，如下所示

<button type="button" wire:click="$set('openModal', true)">
    Open my modal
</button>

或者您也可以从 PHP 文件中打开，如下所示

<?php

namespace App\Livewire;

use Livewire\Component;

class MyComponent extends Component
{
    public bool $openModal = false;

    public function someAction()
    {
        // do something

        $this->openModal = true;
    }
}

关闭模态框的方法相同，只需将 openModal 的值设置为 false。

例如，如果您想在模态框内添加一个按钮来关闭模态框，您可以这样做

<x-tc-modal model="openModal">
    ... Some content of modal

    <button type="button" wire:click="$set('openModal', false)">
        Cancel
    </button>
</x-tc-modal>

您可以通过向组件的 width 属性传递 Tailwind CSS 类来配置模态框的宽度。例如

<x-tc-modal model="openModal" width="w-1/2">
    ... Some content of modal
</x-tc-modal>

您可以在模态框底部添加操作按钮，如下所示

<x-tc-modal model="openModal">
    ... Some content of modal

    <x-slot::action>
        <button>Cancel</button>
        <button>Submit</button>
    </x-slot::action>
</x-tc-modal>

确认模态框

要使用确认模态框，您需要将 x-tc-confirmation-modal 组件和 WithTcConfirmation 特性添加到您想要使用它的 Livewire 组件中。

<?php

namespace App\Livewire;

use Livewire\Component;
use TallComponents\Livewire\Traits\WithTcConfirmation;

class MyComponent extends Component
{
    use WithTcConfirmation;
}

<x-tc-confirmation-modal />

然后，为了要求对某些操作进行确认，您应该在触发确认模态框的按钮上添加 x-tc-confirm 并传递 title、message 和 action。

action 应该是您在用户点击模态框中的 "确认" 按钮后想要调用的 Livewire 方法。

<button 
    type="button" 
    x-tc-confirm="{ 
        title: 'Delete user', 
        message: 'Are you sure you want to delete this user?', 
        action: 'deleteUser' 
    }
>
    Delete user
</button>

虽然 title 参数是可选的，但 message 和 action 是必需的，组件没有它们将无法工作。

如果您想在同一个 Livewire 组件上使用多个动作的确认模态框，您只需添加一次即可。或者，如果您想让它出现在所有页面上，您可以在布局文件中包含它。只需确保您的 Livewire 组件中有 WithTcConfirmation 特性即可。

通知

您可以在不重新加载页面的情况下在同一页面上显示通知，或者您可以将用户重定向到其他页面并在该页面上显示通知。

要使用通知，建议的方法是将它们添加到布局文件中，这样通知将在所有页面上可用。

您应该在文件末尾添加此 Livewire 组件，在 @livewireScripts 之前。

@livewire('tc-notification)

// or

<livewire:tc-notification>

如果您想在页面上显示来自 Livewire 组件的通知而不重新加载页面，只需发送带有要显示的消息的 notification 事件即可，例如

<?php

namespace App\Livewire;

use Livewire\Component;

class MyComponent extends Component
{
    public function someAction()
    {
        // do something

        $this->dispatch('notification', 'Message to display in notification');
    }
}

如果您想跳转到其他页面并在那里显示通知，可以这样操作

<?php

namespace App\Livewire;

use Livewire\Component;

class MyComponent extends Component
{
    public function someAction()
    {
        // do something

        return to_route('some-route-name')
            ->with('notification', 'Message to display in notification');
    }
}

默认情况下，通知将在 5 秒（5000 毫秒）后消失。要更改此设置，需要将持续时间参数传递给组件。持续时间以毫秒表示。

例如，要将通知的消失时间更改为 3 秒，可以这样操作

@livewire('tc-notification, ['duration' => 3000])

// or

<livewire:tc-notification :duration="3000">

表格

您可以在 Livewire 组件的 blade 文件中使用表格，如下所示

<x-tc-table>
    <x-slot:search></x-slot:search>

    <x-slot:filters>
        <x-tc-switcher wire:model.live="onlyActive" label="Only active" />
    </x-slot:filters>

    <x-slot:per-page>
        <x-tc-per-page :options="[5, 15, 30]" />
    </x-slot:per-page>

    <x-slot:heading>
        <x-tc-th sortable="name">
            Name
        </x-tc-th>
        <x-tc-th sortable="email">
            Email
        </x-tc-th>
        <x-tc-th>
            Status
        </x-tc-th>
        <x-tc-th>
            Created at
        </x-tc-th>
    </x-slot:heading>

    @forelse($this->users as $user)
        <x-tc-tr href="{{ route('users.show', $user) }}" :index="$loop->index">
            <x-tc-td>
                {{ $user->name }}
            </x-tc-td>
            <x-tc-td>
                {{ $user->email }}
            </x-tc-td>
            <x-tc-td>
                {{ $user->status }}
            </x-tc-td>
            <x-tc-td>
                {{ $user->created_at->format('d.m.Y H:i') }}
            </x-tc-td>
        </x-tc-tr>
    @empty
        <x-tc-tr>
            <x-tc-td colspan="4">
                There is no results
            </x-tc-td>
        </x-tc-tr>
    @endforelse 

    <x-slot:pagination>
        {{ $this->users->links() }}
    </x-slot:pagination>
</x-tc-table>

在 Livewire 组件中，您需要添加 WithTcTable 特性。当您获取表格的行时（例如此示例中的 $this->users），可以使用以下过滤器

<?php

namespace App\Livewire;

use App\Models\User;
use Livewire\Attributes\Computed;
use Livewire\Component;
use TallComponents\Livewire\Traits\WithTcTable;

class MyComponent extends Component
{
    use WithTcTable;

    public bool $onlyActive = false;

    #[Computed]
    public function users(): LengthAwarePaginator|Model
    {
        return User::query()
            ->when($this->tcSearch, function ($query) {
                $query->where('name', 'LIKE', '%' . $this->tcSearch . '%');
            })
            ->when($this->onlyActive, function ($query) {
                $query->where('is_active', true);
            })
            ->when($this->tcSortable === 'name', function ($query) {
                $query->orderBy('name', $this->tcSortDirection);
            })
            ->when($this->tcSortable === 'email', function ($query) {
                $query->orderBy('email', $this->tcSortDirection);
            })
            ->paginate($this->tcPerPage);
    }
}

可点击行

可以通过向 x-tc-tr 组件添加 href 属性并传递要重定向的值来允许行可点击。

例如，要将用户个人资料页面重定向到路由名称 users.show，可以这样操作

<x-tc-tr :href="route('users.show', $user)" :index="$loop->index">

搜索过滤器

搜索过滤器是可选的；如果您不需要，可以省略 <x-slot:search></x-slot:search>。在这种情况下，将没有用于搜索表格的输入。

搜索输入的值存储在 tcSearch 变量中。因此，要基于该字段的值过滤表格，需要使用 $this->tcSearch。

自定义过滤器

您可以添加任何想要的自定义过滤器（在上述情况中是 Only active 过滤器）。您可以将任何切换、复选框或选择输入传递到 <x-slot:filters> 插槽中。

每页过滤器

每页过滤器是可选的；如果您不需要，可以省略 <x-slot:per-page>。

每页的值存储在 tcPerPage 变量中，默认为 15。要使用它，需要将 $this->tcPerPage 传递给您的 paginate 方法，如下所示

...
->paginate($this->tcPerPage);

您可以通过将值作为 options 属性传递给 x-tc-per-page 组件来自定义用户可以选择的行数。例如，如果您想允许用户在 15、30 和 50 之间选择，可以这样操作

<x-slot:per-page>
    <x-tc-per-page :options="[15, 30, 50]" />
</x-slot:per-page>

按列排序

您可以通过向 <x-tc-th> 组件添加 sortable 并传递用于排序的键来允许对表格中的任何列进行排序。

例如，如果您想允许按用户名排序，可以这样操作

<x-tc-th sortable="name">
    Name
</x-tc-th>

然后您可以根据名称对结果进行排序，如下所示

...
->when($this->tcSortable === 'name', function ($query) {
    $query->orderBy('name', $this->tcSortDirection);
})

可排序列的名称存储在 tcSortable 中，方向存储在 tcSortDirection 变量中。默认情况下，方向将是 asc，并在每次点击时在 asc 和 desc 之间切换。

分页

分页是可选的；如果您不需要，可以省略 <x-slot:pagination></x-slot:pagination>。

加载指示器

将 <x-tc-loading-spinner /> 添加到您的 blade 中，并添加一个应与您想要使用旋转器进行的 Livewire 操作匹配的 target 属性。

<x-tc-loading-spinner target="someAction" />

<?php

namespace App\Livewire;

use Livewire\Component;

class MyComponent extends Component
{
    public function someAction()
    {
        // Display spinner while this method executing
    }
}

如果您想更改旋转器的样式，可以添加一个包含您想要实施的更改的 class。

例如，您可以更改旋转器的大小，如下所示

<x-tc-loading-spinner target="someAction" class="!w-10 !h-10" />

或者如果您想进行其他更改，可以发布视图文件并在那里进行。

拖放文件上传（Filepond）

要使用字段进行文件上传，您需要在 blade 中添加 <x-tc-filepond> 并设置 wire:model。

<x-tc-filepond wire:model="state.file" />

文件上传时，它将是标准的 Livewire 临时上传文件（《Livewire\Features\SupportFileUploads\TemporaryUploadedFile》），您可以将它保存为任何其他文件上传。

如果您想在文件上传后立即调用 Livewire 操作，您可以在组件中添加 callOnUpload 并传递要调用的 Livewire 方法的名称。例如，在文件上传后调用 saveFile 方法

<x-tc-filepond 
    wire:model="state.file" 
    callOnUpload="saveFile" 
/>

您可以通过派发与组件的 resetKey 匹配的事件从 Livewire 重置 Filepond 字段。例如

<x-tc-filepond 
    wire:model="state.file" 
    callOnUpload="saveFile" 
    resetKey="resetFileField" 
/>

<?php

namespace App\Livewire;

use Livewire\Component;

class MyComponent extends Component
{
    public function saveFile()
    {
        // Save file

        $this->dispatch('resetFileField');
    }
}

组件允许不同的配置，以下是可以用的属性

如果您想进行其他更改，可以发布视图并编辑 filepond.blade.php 文件。

Markdown 编辑器（Quill）

要使用 Quill 文本编辑器，您需要在 blade 中添加 <x-tc-quill-editor> 并设置 wire:model（不能使用 live 或 blur）。

<x-tc-quill-editor wire:model="state.text" />

您可以通过向组件传递 placeholder 属性来添加占位文本。

<x-tc-quill-editor 
    wire:model="state.text" 
    placeholder="Write some text here..."
/>

可以使编辑器只读；只需传递 readOnly 属性并将其设置为 true。

<x-tc-quill-editor 
    wire:model="state.text" 
    readOnly="true"
/>

编辑器默认包含所有编辑选项的工具栏。您可以通过将 toolbar 属性传递给组件并指定要使用的编辑选项来配置它。例如，如果您只想有 bold、italic 和 underline 选项

<x-tc-quill-editor 
    wire:model="state.text" 
    toolbar="['bold', 'italic', 'underline']"
/>

编辑器的默认工具栏

['bold', 'italic', 'underline', 'strike'],
['blockquote', 'code-block'],
['link', 'formula'],

[{ 'header': 1 }, { 'header': 2 }], 
[{ 'list': 'ordered'}, { 'list': 'bullet' }, { 'list': 'check' }],
[{ 'script': 'sub'}, { 'script': 'super' }],
[{ 'indent': '-1'}, { 'indent': '+1' }],
[{ 'direction': 'rtl' }],

[{ 'size': ['small', false, 'large', 'huge'] }],
[{ 'header': [1, 2, 3, 4, 5, 6, false] }],

[{ 'color': [] }, { 'background': [] }],
[{ 'font': [] }],
[{ 'align': [] }],

['clean']

如果您想更改编辑器的主题或进行任何其他修改，可以发布视图并编辑 quill-editor.blade.php 文件。

日期时间选择器（Flatpickr）

要使用日期时间选择器，您需要在 blade 中添加 <x-tc-datetime-picker> 并设置 wire:model。

<x-tc-datetime-picker wire:model="state.datetime" />

要添加占位符，只需将 placeholder 属性传递给组件

<x-tc-datetime-picker 
    wire:model="state.datetime" 
    placeholder="Select datetime..." 
/>

组件允许不同的配置；您可以通过向组件传递属性来更改其配置。

可用属性

如果您想进行其他更改，可以发布视图并编辑 datetime-picker.blade.php 文件。

测试

使用以下命令运行测试

composer test

致谢

沃伊斯拉夫·德拉吉塞维奇

许可证

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

vojislavd / tall-components

维护者

详细信息