README

Laravel Livewire 与 Bootstrap 5 UI & CRUD 快速启动套件。本套件是针对偏好使用 Bootstrap 5 和全页 Livewire 组件进行项目开发的开发者而现代化的旧 laravel/ui 套件的版本。它还提供了一些功能，以进一步提升您的开发速度。

要求

Laravel 8
NPM

功能

预配置 Bootstrap 5
包括登录、注册、忘记密码、资料更新等在内的全认证脚手架。
用于创建模型、组件和 CRUD 的命令
PWA 功能
简单的应用版本控制
自动模型迁移
自动全页组件路由
自动属性哈希
自动用户时区
通过单个属性轻松操作表单数据
动态 Livewire Bootstrap 弹出模态框
自定义 Blade 组件
Font Awesome 图标
& 更多

安装

本套件旨在与全新的 Laravel 项目配合使用。

通过 Valet、Docker 或您喜欢的任何方式安装 Laravel

laravel new my-project

配置 .env 应用、数据库和邮件变量

APP_*
DB_*
MAIL_*

通过 composer 安装此套件

composer require bastinald/ui

运行 ui:install 命令

php artisan ui:install

安装完成后，您应该能够访问您的应用 URL，并使用 user@example.com 作为电子邮件，以及 password 作为密码进行登录。这已为您预先设置以供测试。

命令

安装 UI

php artisan ui:install

此命令将创建您的 Livewire 认证组件和视图，更新您的用户模型和工厂，迁移和种默认用户，通过 NPM/Webpack 配置 Bootstrap 5 JavaScript 和 SCSS，创建一个 IDE 辅助文件，并运行必要的 NPM 命令。

创建模型

php artisan ui:model {class} {--force}

这将创建一个包含自动 migration 方法的模型。它还将为该模型创建一个指向模型 definition 方法的工厂。

使用 --force 覆盖现有模型和工厂。

创建组件

php artisan ui:component {class} {--f|--full} {--m|--modal} {--force}

这将根据传递给它的选项创建一个 Livewire 组件和视图。使用 -f 选项创建一个带有 route 方法的全页组件，使用 -m 选项创建一个模态组件，或者两者都不用创建部分组件。

使用 --force 覆盖现有组件和视图。

创建 CRUD

php artisan ui:crud {path}

这将为给定的组件路径/命名空间创建 CRUD 组件和视图。这包括索引、创建、读取、更新和删除。它还包括搜索、排序和筛选，这些功能可以在索引组件类中轻松自定义。

要创建子文件夹中的 CRUD，只需使用斜杠或点表示法即可

# no subfolder
php artisan ui:crud Users 

# in an "Admin" subfolder
php artisan ui:crud Admin/Users

如果在创建 CRUD 时模型（例如上述示例中的 User）不存在，它将询问您是否要创建它。在生成 CRUD 之后，您只需要将模型字段添加到组件视图中。运行 ui:install 时，请查看套件中提供的 Users 组件和视图作为示例。

使用 --force 选项来覆盖现有的 CRUD 组件和视图。

运行自动迁移

php artisan ui:migrate {--f|--fresh} {--s|--seed} {--force}

该命令会遍历您的模型 migration 方法，并将它们的模式与现有数据库表的模式进行比较。如果需要做出任何更改，它将通过 Doctrine 自动应用它们。

该命令与传统的迁移文件配合良好。运行此命令时，它将首先运行您的传统迁移，然后运行自动迁移。这对于不需要将数据库表与模型（交叉等）耦合的情况很有用。

使用 -f 选项来擦除数据库（全新），并使用 -s 选项在迁移完成后运行种子文件。在生产环境中运行迁移需要 --force 选项。

自动迁移

此包推崇自动迁移的使用。

要使用自动迁移，请在模型内指定一个 migration 方法

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Schema\Blueprint;

class User extends Model
{
    public function migration(Blueprint $table)
    {
        $table->id();
        $table->string('name');
        $table->string('email')->unique();
        $table->timestamp('email_verified_at')->nullable();
        $table->string('password');
        $table->rememberToken();
        $table->timestamp('created_at')->nullable();
        $table->timestamp('updated_at')->nullable();
    }
}

或者，通过 ui:model 命令创建一个新的模型，这将为您包括一个 migration 方法

php artisan ui:model Vehicle

migration 方法使用与传统的 Laravel 迁移文件相同的 $table 蓝图变量。如前所述，当您运行 ui:migrate 命令时，它将比较您的现有数据库表模式与模型 migration 方法，并通过 Doctrine 应用必要的更改。这样，您就不再需要管理大量的迁移文件。

自动路由

此包还推崇自动路由的使用。

要使用自动路由，请在全页 Livewire 组件内指定一个 route 方法

use Illuminate\Support\Facades\Route;
use Livewire\Component;

class Home extends Component
{
    public function route()
    {
        return Route::get('/home', static::class)
            ->name('home')
            ->middleware('auth');
    }
}

或者，只需使用带有 -f 选项的 ui:component 命令，快速创建一个包含 route 方法的全页组件

php artisan ui:component ContactUs -f

route 方法返回 Laravel 的 Route 门面，就像您会在路由文件中使用一样。这意味着您的组件路由可以执行任何正常 Laravel 路由可以执行的操作。这些路由将通过包服务提供程序自动注册，因此您不再需要管理混乱的路由文件。

自动属性哈希

HasHashes 特性允许您指定在保存到数据库时要自动哈希的模型属性。

要使用自动哈希，请使用 HashHashes 特性，并指定一个带有应自动哈希的属性的 hashes 属性

use Bastinald\Ui\Traits\HasHashes;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasHashes;

    protected $hashes = ['password'];
}

此特性将只自动哈希尚未哈希的属性值，因此它不会减慢种子文件。

表单数据操作

WithModel 特性使得在 Livewire 组件中管理表单数据变得容易。通常，您需要为每个表单输入指定一个属性。使用此特性，所有表单数据都将存在于一个 $model 属性数组中。此特性还提供了一些方便的方法来获取、设置和验证数据。

绑定模型数据

请注意，所有 x-ui Blade 组件都将正确地将输入映射到组件的 $model 属性并显示相关错误。如果您使用自己的 HTML 输入，只需确保在 wire:model 属性前加上 model.。

例如，如果您使用包组件，只需通过 model 属性直接指定 $model 键

<x-ui::input :label="__('First Name')" type="text" model="first_name"/>

如果您使用自己的 HTML 输入，请确保在 wire:model.* 属性前加上 model.

<label>First Name</label>
<input type="text" wire:model.defer="model.first_name"/>
@error('first_name') <p class="text-danger">{{ $message }}</p> @enderror

请注意，您不需要在 @error 前加上 model.。错误消息使用 $model 键通过 validateModel 方法，所以您只需要在输入前加上 model.。

获取模型数据

以数组形式获取所有模型数据

$this->getModel();

获取数据数组

$this->getModel(['email', 'password']);

如果您将数组传递给getModel属性，它将始终返回一个数组，即使您只使用一个键。这在通过create或update快速更新单个模型列时非常有用。

获取单个值

$this->getModel('first_name', 'Joe');

您可以通过第二个参数指定默认值，或者完全省略。

设置模型数据

设置值数组

$this->setModel([
    'name' => 'Joe',
    'email' => 'joe@example.com',
]);

设置单个值

$this->setModel('name', 'Joe');

重置模型数据

您可以轻松重置所有模型数据

$this->resetModel();

验证模型数据

validateModel方法与Livewire的validate方法工作方式相同，但将使用$model数据进行验证。

您可以使用它与rules方法一起使用

public function rules()
{
    return [
        'email' => ['required', 'email'],
        'password' => ['required'],
    ];
}

public function login()
{
    $this->validateModel();
    
    // log the user in
}

或者单独使用，直接传递规则

public function login()
{
    $this->validateModel([
        'email' => ['required', 'email'],
        'password' => ['required'],
    ]);
    
    // log the user in
}

动态 Bootstrap 模态框

此包允许您通过发射一个简单的事件动态地将Livewire组件显示为模态框。不再需要在您的视图中到处管理模态组件。

创建模态框

只需使用带有-m选项的ui:component命令来创建新的模态组件

php artisan ui:component TermsOfService -m

这将创建一个包含Bootstrap模态类别的部分Livewire组件和视图。

显示模态框

要显示模态框，只需发射showModal事件。

您可以从组件视图发射此事件

<button type="button" wire:click="$emit('showModal', 'auth.password-change')">
    {{ __('Change Password') }}
</button>

或从组件类本身发射

$this->emit('showModal', 'auth.password-change');

注意第二个参数正在使用Livewire组件类别名。因此，在这个例子中，auth.password-change实际上指向了Auth\PasswordChange组件。

传递挂载参数

您可以通过在showModal事件中指定它们来将任何参数传递给模态组件的mount方法

通过组件视图传递参数

<button type="button" wire:click="$emit('showModal', 'users.update', {{ $user->id }})">
    {{ __('Update User') }}
</button>

或从组件类

$this->emit('showModal', 'users.update', $user->id);

现在，在我们的组件mount方法中，我们可以使用此参数

public $user;

public function mount(User $user)
{
    $this->user = $user;
}

注意即使在这里模型绑定也起作用。如果您需要传递多个参数，只需将它们添加到showModal发射中，用逗号分隔即可。

隐藏模态框

通过hideModal事件隐藏当前打开的模态框

<button type="button" wire:click="$emit('hideModal')">
    {{ __('Close') }}
</button>

或者，通过组件类

$this->emit('hideModal');

您还可以通过常规Bootstrap data-bs-toggle按钮隐藏模态框

<button type="button" class="btn btn-secondary" data-bs-dismiss="modal">
    {{ __('Cancel') }}
</button>

Blade 组件

此包附带一些实用的Blade组件，确保您保持DRY，同时保持您的标记既简洁又整洁。

输入

表单输入

<x-ui::input :label="__('Email')" type="email" model="email"/>

可用属性

label：输入标签
type：输入类型，例如text、email、file
model：组件$model属性的键
lazy：在更改时绑定模型值
debounce="x"：在x毫秒后（默认为150）去抖动模型值

如果未使用lazy和debounce，则defer是默认值。

文本区域

文本区域输入

<x-ui::textarea :label="__('Biography')" rows="5" model="biography"/>

可用属性

label：文本区域标签
model：组件$model属性的键
lazy：在更改时绑定模型值
debounce="x"：在x毫秒后（默认为150）去抖动模型值

lazy和debounce属性与input组件相同。

选择

选择输入

<x-ui::select :label="__('Color')" :options="['Red', 'Blue']" model="color"/>

可用属性

label：选择标签
options：选择选项数组
model：组件$model属性的键
lazy：在更改时绑定模型值

options数组可以是索引数组或关联数组。如果数组是关联的，则数组键将用作选项值，而数组值将用作选项标签。如果数组是索引的，则其值将用作选项值和标签。

单选按钮

单选按钮输入

<x-ui::radio :label="__('Color')" :options="['Red', 'Blue']" model="color"/>

可用属性

label：单选按钮标签
options：单选按钮选项数组
model：组件$model属性的键
lazy：在更改时绑定模型值

options数组与select组件相同。

复选框

复选框输入

<x-ui::checkbox :label="__('Agree to TOS')" model="agree"/>

可用属性

label：复选框标签
model：组件$model属性的键
lazy：在更改时绑定模型值

下拉菜单

下拉按钮

<x-ui::dropdown icon="filter" :label="__($filter)">
    @foreach($filters as $filter)
        <x-ui::dropdown-item :label="__($filter)" click="$set('filter', '{{ $filter }}')"/>
    @endforeach
</x-ui::dropdown>

可用属性

icon：下拉按钮图标（Font Awesome）
label：下拉按钮标签
position：下拉菜单位置（默认为end）
slot：下拉菜单项

下拉菜单项

下拉菜单项按钮

<x-ui::dropdown-item :label="__('Logout')" click="logout"/>

可用属性

label：下拉菜单项按钮标签
route：链接到的路由
url：链接到的URL
href：链接的href
click：Livewire的点击动作

操作

一个CRUD操作按钮

<x-ui::action icon="eye" :title="__('Read')"
    click="$emit('showModal', 'users.read', {{ $user->id }})"/>

可用属性

icon：操作按钮的图标（Font Awesome）
title：操作按钮的标题
route：链接到的路由
url：链接到的URL
href：链接的href
click：Livewire的点击动作

分页

响应式分页链接

<x-ui::pagination :links="$users"/>

可用属性

links：分页链接结果
count：在左侧显示计数（true 或 false）
justify：链接的对齐方式

图标

一个Font Awesome图标

<x-ui::icon name="laravel" style="brands"/>

可用属性

name：图标名称
style：图标样式，例如 solid，regular（默认在配置中设置）

Font Awesome 图标

运行ui:install命令时，您可以选择安装Font Awesome免费版或专业版。如果您选择专业版，您需要配置全局NPM令牌。

有关如何配置此令牌的信息，请参阅Font Awesome文档。

发布资源

通过vendor:publish命令发布包配置、存根和视图

php artisan vendor:publish

选择ui:config、ui:stubs、ui:views或ui以发布所有资产。

使用自定义存根

一旦发布包配置和存根文件，存根将位于resources/stubs/vendor/ui文件夹中。

更新config/ui.php文件并将stub_path指向此路径

'stub_path' => resource_path('stubs/vendor/ui'),

现在命令将使用此路径作为存根。根据您的需求进行自定义。

bastinald / ui

维护者

详细信息

README

要求

功能

文档

安装

命令

安装 UI

创建模型

创建组件

创建 CRUD

运行自动迁移

自动迁移

自动路由

自动属性哈希

表单数据操作

绑定模型数据

获取模型数据

设置模型数据

重置模型数据

验证模型数据

动态 Bootstrap 模态框

创建模态框

显示模态框

传递挂载参数

隐藏模态框

Blade 组件

输入

文本区域

选择

单选按钮

复选框

下拉菜单

下拉菜单项

操作

分页

图标

Font Awesome 图标

发布资源

使用自定义存根