README

关于Wire Elements Modal

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

安装

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

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

composer require wire-elements/modal

Livewire 指令

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

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

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

Alpine

Wire Elements Modal 需要 Alpine 和插件Focus。您可以使用官方CDN快速包含Alpine

<!-- Alpine v3 -->
<script defer src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js"></script>

<!-- Focus plugin -->
<script defer src="https://unpkg.com/@alpinejs/focus@3.x.x/dist/cdn.min.js"></script>

TailwindCSS

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

php artisan vendor:publish --tag=livewire-ui-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.emit('openModal', 'edit-user')">Edit User</button>

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

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

传递参数

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

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

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

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

<!-- Example of passing multiple parameters -->
<button wire:click="$emit('openModal', 'edit-user', {{ json_encode([$user->id, $isAdmin]) }})">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='$emit("openModal", "delete-user", {{ json_encode(["user" => $user->id]) }})'>Delete User</button>

关闭（子）模态框

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

<button wire:click="$emit('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::getName() => 'userModified',
    ]);
}

您还可以向事件添加参数

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

    $this->closeModalWithEvents([
        UserOverview::getName() => ['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;
}

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

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

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

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::getName() => '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: [
        'sm:max-w-2xl'
      ]
    }
  },
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
}

配置

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

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

php artisan vendor:publish --tag=livewire-ui-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 许可证许可。

viwo-software / livewire-modal

维护者

详细信息