README

Livewire v3

这是 Livewire v3 的说明文档。 如果您正在寻找 Livewire v2 的说明文档请点击此处。

从 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 模态包的完整文章，或按照以下说明操作。

要开始，请通过 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 在客户端存储所有提供的信息，换句话说，这些数据可以被操纵。如上面示例所示，使用 Gate 门面来授权操作。

鸣谢

许可证

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

livewire-ui / modal

维护者

详细信息