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 borisov/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 Borisov\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.。错误消息通过 validateModel 方法使用 $model 键，因此您只需在输入上添加 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

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

显示模态

要显示模态，只需发出 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'),

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

ivan-borisov / ui

维护者

详情

README

要求

功能

文档

安装

命令

安装 UI

创建模型

创建组件

创建 CRUD

运行自动迁移

自动迁移

自动路由

自动属性哈希

表单数据操作

绑定模型数据

获取模型数据

设置模型数据

重置模型数据

验证模型数据

动态 Bootstrap 模态框

创建模态

显示模态

传递挂载参数

隐藏模态

Blade 组件

输入

文本区域

选择

单选按钮

复选框

下拉菜单

下拉菜单项

操作

分页

图标

Font Awesome 图标

发布资产

使用自定义存根