Laravel 11中LiveWire v3 Dispatch方法无法显示Bootstrap模态框

问题背景 #

使用Laravel 11 + Livewire 3.5，在用户列表页面点击Add New按钮触发addNew方法后，控制台报错，Bootstrap模态框无法正常显示。相关代码如下：

按钮代码 #

<div class="card-header">
   <div class="card-tools">
      <button type="button" wire:click="addNew">Add New</button>
   </div>
</div>

Livewire组件代码 #

class ListUsers extends Component
{
    public $users;
    public $name;
    public $email;

    public function mount()
    {
        $this->users = User::all();
    }

    public function addNew()
    {
        $this->dispatch('showModal');
    }

    public function save()
    {
        User::create([
            'name' => $this->name,
            'email' => $this->email,
        ]);

        $this->reset('name', 'email');
        $this->dispatch('closeModal');
    }

    public function render()
    {
        return view('livewire.admin.users.list-users')->layout('layouts.app');
    }
}

原监听脚本 #

<script>
    document.addEventListener('livewire:load', function () {
        Livewire.on('showModal', () => {
            const modal = document.getElementById('myModal');
            if (modal) {
                modal.style.display = 'block'; // Show the modal
            }
        });

        // Close modal when the close button is clicked
        document.addEventListener('click', function (event) {
            const modal = document.getElementById('myModal');
            if (event.target.classList.contains('close')) {
                modal.style.display = 'none'; // Hide the modal
            }
        });
    });
</script>

错误原因 #

1. Livewire 3事件监听语法变更：旧版Livewire.on()在Livewire 3中已失效，需改为window.Livewire.on()，这是控制台报错的核心原因。
2. 错误控制Bootstrap模态框：直接修改display属性会绕过Bootstrap模态框的内部状态管理，导致弹窗无法正常渲染或行为异常。
3. 脚本加载时机问题：传统script标签可能在Livewire未完全初始化时执行，导致事件监听绑定失败。

解决步骤 #

1. 确保Bootstrap模态框结构符合官方标准 #

替换原有模态框HTML为Bootstrap 5规范结构：

<!-- Bootstrap 5 模态框 -->
<div class="modal fade" id="myModal" tabindex="-1" aria-labelledby="userModalLabel" aria-hidden="true">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="userModalLabel">添加新用户</h5>
        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="关闭"></button>
      </div>
      <div class="modal-body">
        <div class="mb-3">
          <label class="form-label">姓名</label>
          <input type="text" class="form-control" wire:model="name">
        </div>
        <div class="mb-3">
          <label class="form-label">邮箱</label>
          <input type="email" class="form-control" wire:model="email">
        </div>
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">取消</button>
        <button type="button" class="btn btn-primary" wire:click="save">保存</button>
      </div>
    </div>
  </div>
</div>

2. 修改事件监听脚本（使用Livewire 3推荐方式） #

用@script指令包裹脚本，同时修正事件监听语法并使用Bootstrap官方API控制模态框：

@script
<script>
    // 监听显示模态框事件
    window.Livewire.on('showModal', () => {
        const modalEl = document.getElementById('myModal');
        const modal = new bootstrap.Modal(modalEl);
        modal.show();
    });

    // 监听关闭模态框事件
    window.Livewire.on('closeModal', () => {
        const modalEl = document.getElementById('myModal');
        const modal = bootstrap.Modal.getInstance(modalEl);
        if (modal) {
            modal.hide();
        }
    });
</script>
@endscript

3. 确认Bootstrap JS已正确引入 #

确保在应用布局文件（layouts/app.blade.php）中引入Bootstrap 5的JS文件（需在Livewire脚本之后）：

<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>

关键说明 #

• Livewire 3中全局事件必须通过window.Livewire对象监听，不再支持直接使用Livewire全局变量。
• 必须使用Bootstrap提供的Modal实例方法（show()/hide()）来控制模态框，避免手动修改CSS属性引发的兼容性问题。
• @script是Livewire 3新增的指令，能自动处理脚本的加载时机，确保在Livewire组件初始化完成后执行，避免DOM未就绪的问题。

内容的提问来源于stack exchange，提问作者Pouya