README

Livewire v3

这是Livewire v3的readme。如果您在寻找Livewire v2的readme，请点击此处。

从v2升级

您可以使用以下命令来自动化升级过程

php artisan livewire:upgrade --run-only wire-elements-modal-upgrade

请检查更改并确保它们遵循Livewire v3设置的新约定

<-- Before -->
<button wire:click="$emit('openModal', 'users')">Show Users</button>
<!-- After -->
<button wire:click="$dispatch('openModal', {component: 'users'})">Show Users</button>

<-- Before -->
<button wire:click="$emit('openModal', 'edit-user', {user: 5})">Edit User</button>
<!-- After -->
<button wire:click="$dispatch('openModal', {component: 'edit-user', arguments: {user: 5}})">Edit User</button>

旧组件名称已被弃用。将@livewire('livewire-ui-modal')替换为@livewire('wire-elements-modal')。

配置文件也已重命名。如果您以前已发布配置，您将需要重新发布并做出必要的更改

php artisan vendor:publish --tag=wire-elements-modal-config

升级后，请确保清除您的视图缓存

php artisan view:clear

关于Wire Elements Modal

Wire Elements Modal是一个Livewire组件，它提供支持多个子模态并保持状态的模式。

安装

点击上面的图片阅读关于使用Wire Elements modal包的完整文章，或按照以下说明操作。

要开始使用，请通过Composer要求该包

composer require wire-elements/modal:^2.0

Livewire指令

将Livewire指令@livewire('wire-elements-modal')添加到您的模板中。

<html>
<body>
    <!-- content -->

    @livewire('wire-elements-modal')
</body>
</html>

TailwindCSS

基本模式是用TailwindCSS制作的。如果您使用不同的CSS框架，我建议您发布模式模板并更改标记以包含您CSS框架所需的类。

php artisan vendor:publish --tag=wire-elements-modal-views

创建模式

您可以通过运行php artisan make:livewire EditUser来创建初始Livewire组件。打开您的组件类并确保它扩展了ModalComponent类

<?php

namespace App\Http\Livewire;

use LivewireUI\Modal\ModalComponent;

class EditUser extends ModalComponent
{
    public function render()
    {
        return view('livewire.edit-user');
    }
}

打开模式

要打开模式，您需要触发一个事件。例如，要打开EditUser模式

<!-- Outside of any Livewire component -->
<button onclick="Livewire.dispatch('openModal', { component: 'edit-user' })">Edit User</button>

<!-- Inside existing Livewire component -->
<button wire:click="$dispatch('openModal', { component: 'edit-user' })">Edit User</button>

<!-- Taking namespace into account for component Admin/Actions/EditUser -->
<button wire:click="$dispatch('openModal', { component: 'admin.actions.edit-user' })">Edit User</button>

传递参数

要打开特定用户的EditUser模式，我们可以传递用户ID

<!-- Outside of any Livewire component -->
<button onclick="Livewire.dispatch('openModal', { component: 'edit-user', arguments: { user: {{ $user->id }} }})">Edit User</button>

<!-- Inside existing Livewire component -->
<button wire:click="$dispatch('openModal', { component: 'edit-user', arguments: { user: {{ $user->id }} }})">Edit User</button>

<!-- If you use a different primaryKey (e.g. email), adjust accordingly -->
<button wire:click="$dispatch('openModal', { component: 'edit-user', arguments: { user: {{ $user->email }} }})">Edit User</button>

<!-- Example of passing multiple arguments -->
<button wire:click="$dispatch('openModal', { component: 'edit-user', arguments: { user: {{ $user->id }}, advancedMode: true }})">Edit User</button>

参数注入到模式组件中，如果定义了类型，模型将自动从数据库中获取

<?php

namespace App\Http\Livewire;

use App\Models\User;
use LivewireUI\Modal\ModalComponent;

class EditUser extends ModalComponent
{
    // This will inject just the ID
    // public int $user;

    public User $user;

    public function mount()
    {
        Gate::authorize('update', $this->user);
    }

    public function render()
    {
        return view('livewire.edit-user');
    }
}

参数还传递到模式组件上的mount方法。

打开子模式

从现有的模式中，您可以使用完全相同的事件创建一个子模式

<!-- Edit User Modal -->

<!-- Edit Form -->
<button wire:click="$dispatch('openModal', { component: 'delete-user', arguments: { user: {{ $user->id }} }})">Delete User</button>

关闭（子）模式

例如，如果用户点击'删除'按钮，这将打开一个确认对话框，您可以通过触发closeModal事件取消删除并返回到编辑用户模式。这将打开之前的模式。如果没有之前模式，则关闭整个模式组件并重置状态。

<button wire:click="$dispatch('closeModal')">No, do not delete</button>

您也可以在模式组件类内部关闭模式

<?php

namespace App\Http\Livewire;

use App\Models\User;
use LivewireUI\Modal\ModalComponent;

class EditUser extends ModalComponent
{
    public User $user;

    public function mount()
    {
        Gate::authorize('update', $this->user);
    }

    public function update()
    {
        Gate::authorize('update', $this->user);

        $this->user->update($data);

        $this->closeModal();
    }

    public function render()
    {
        return view('livewire.edit-user');
    }
}

如果您不想回到上一个模式但关闭整个模式组件，您可以使用forceClose方法

public function update()
{
    Gate::authorize('update', $this->user);

    $this->user->update($data);

    $this->forceClose()->closeModal();
}

通常，当发生变化时，您会想要更新其他Livewire组件。例如，当用户更新时，您可以使用closeModalWithEvents方法来实现此目的。

public function update()
{
    Gate::authorize('update', $this->user);

    $this->user->update($data);

    $this->closeModalWithEvents([
        UserOverview::class => 'userModified',
    ]);
}

也可以向事件添加参数

public function update()
{
    $this->user->update($data);

    $this->closeModalWithEvents([
        UserOverview::class => ['userModified', [$this->user->id]],
    ]);
}

更改模式属性

您可以通过覆盖模态组件类中的静态方法 modalMaxWidth 来更改模态的宽度（默认值为 '2xl'）

/**
 * Supported: 'sm', 'md', 'lg', 'xl', '2xl', '3xl', '4xl', '5xl', '6xl', '7xl'
 */
public static function modalMaxWidth(): string
{
    return 'xl';
}

默认情况下，按 escape 键将关闭模态。如果您想禁用此行为，例如防止意外关闭模态，可以覆盖静态方法 closeModalOnEscape 并使其返回 false。

public static function closeModalOnEscape(): bool
{
    return false;
}

默认情况下，当您点击模态外部时，模态将关闭。如果您想禁用此行为，例如防止意外关闭模态，可以覆盖静态方法 closeModalOnClickAway 并使其返回 false。

public static function closeModalOnClickAway(): bool
{
    return false;
}

默认情况下，按 escape 键关闭模态将强制关闭所有模态。如果您想禁用此行为，例如允许按 escape 显示上一个模态，可以覆盖静态方法 closeModalOnEscapeIsForceful 并使其返回 false。

public static function closeModalOnEscapeIsForceful(): bool
{
    return false;
}

当模态关闭时，您可以选择启用 modalClosed 事件。此事件将在调用 closeModal、按下 escape 按钮或点击模态外部时触发。关闭组件的名称将作为参数提供；

public static function dispatchCloseEvent(): bool
{
    return true;
}

默认情况下，当关闭子模态时，如果再次打开相同的模态组件，关闭组件的状态仍然可用。如果您希望在关闭时销毁组件，可以覆盖静态方法 destroyOnClose 并使其返回 true。当再次打开已销毁的模态时，其状态将重置。

public static function destroyOnClose(): bool
{
    return true;
}

跳过上一个模态

在某些情况下，您可能想跳过上一个模态。例如

团队概览模态
-> 编辑团队
-> 删除团队

在这种情况下，当删除团队时，您不想返回到步骤 2，而是返回到概览。您可以使用 skipPreviousModal 方法来实现这一点。默认情况下，它将跳过上一个模态。如果您想跳过更多，可以传递要跳过的模态数量 skipPreviousModals(2)。

<?php

namespace App\Http\Livewire;

use App\Models\Team;
use LivewireUI\Modal\ModalComponent;

class DeleteTeam extends ModalComponent
{
    public Team $team;

    public function mount(Team $team)
    {
        $this->team = $team;
    }

    public function delete()
    {
        Gate::authorize('delete', $this->team);

        $this->team->delete();

        $this->skipPreviousModal()->closeModalWithEvents([
            TeamOverview::class => 'teamDeleted'
        ]);
    }

    public function render()
    {
        return view('livewire.delete-team');
    }
}

您还可以选择调用 destroySkippedModals() 方法来销毁跳过的模态，这样如果再次打开它们，其状态将被重置

构建用于生产的 Tailwind CSS

要清除包中使用的类，请将以下行添加到 tailwind.config.js 中的 purge 数组

'./vendor/wire-elements/modal/resources/views/*.blade.php',
'./storage/framework/views/*.php',

由于一些类是动态构建的，您应该将一些类添加到 purge 白名单中，因此您的 tailwind.config.js 应该看起来像这样

module.exports = {
  purge: {
    content: [
      './vendor/wire-elements/modal/resources/views/*.blade.php',
      './storage/framework/views/*.php',
      './resources/views/**/*.blade.php',
    ],
    options: {
      safelist: {
            pattern: /max-w-(sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl)/,
            variants: ['sm', 'md', 'lg', 'xl', '2xl']
        } 
    }
  },
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
}

对于 TailwindCSS 3x

export default {
  content: [
    './vendor/wire-elements/modal/resources/views/*.blade.php',
    './storage/framework/views/*.php',
    './resources/views/**/*.blade.php',
  ],
  safelist: [
    {
      pattern: /max-w-(sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl)/,
      variants: ['sm', 'md', 'lg', 'xl', '2xl']
    }
  ],
  // other options
}

配置

您可以通过 wire-elements-modal.php 配置文件来自定义模态。这包括一些附加选项，例如，如果您在应用程序中不使用 TailwindCSS，则包括 CSS，以及默认模态属性。

要发布配置，请运行 vendor:publish 命令

php artisan vendor:publish --tag=wire-elements-modal-config

<?php

return [

    /*
    |--------------------------------------------------------------------------
    | Include CSS
    |--------------------------------------------------------------------------
    |
    | The modal uses TailwindCSS, if you don't use TailwindCSS you will need
    | to set this parameter to true. This includes the modern-normalize css.
    |
    */
    'include_css' => false,


    /*
    |--------------------------------------------------------------------------
    | Include JS
    |--------------------------------------------------------------------------
    |
    | Livewire UI will inject the required Javascript in your blade template.
    | If you want to bundle the required Javascript you can set this to false
    | and add `require('vendor/wire-elements/modal/resources/js/modal');`
    | to your script bundler like webpack.
    |
    */
    'include_js' => true,


    /*
    |--------------------------------------------------------------------------
    | Modal Component Defaults
    |--------------------------------------------------------------------------
    |
    | Configure the default properties for a modal component.
    |
    | Supported modal_max_width
    | 'sm', 'md', 'lg', 'xl', '2xl', '3xl', '4xl', '5xl', '6xl', '7xl'
    */
    'component_defaults' => [
        'modal_max_width' => '2xl',

        'close_modal_on_click_away' => true,

        'close_modal_on_escape' => true,

        'close_modal_on_escape_is_forceful' => true,

        'dispatch_close_event' => false,

        'destroy_on_close' => false,
    ],
];

安全

如果您是 Livewire 新手，我建议您查看安全细节。简而言之，非常重要 要验证所有提供给 Livewire 的信息，因为 Livewire 在客户端存储此信息，换句话说，这些数据可以被操纵。如上述示例所示，使用 Gate 门面授权操作。

鸣谢

许可证

WireElements 是开源软件，根据 MIT 许可证许可。

wire-elements / modal

维护者

详细信息