laravel-livewire

涵盖 Laravel 13 上的 Livewire 4：基于类的响应式组件与 Blade 视图、wire:model 双向绑定及其修饰符（.blur、.live、.debounce）、操作、组件生命周期钩子、表单/验证、事件（分发/监听）、Alpine.js 集成（$wire、@entangle）、文件上传、组件嵌套、加载状态、SPA 导航、测试、安全性（身份验证/速率限制），以及 Volt（单文件组件）和 Folio（基于文件的路由）子功能，包括 Precognition 实时验证和 Reverb WebSocket 集成。

Laravel Livewire

Agent 工作流（强制）

在进行任何实现之前，并行启动 3 个 Agent，每个使用一个带有 name 的 Agent 调用：

1. fuse-ai-pilot:explore-codebase - 检查现有 Livewire 组件
2. fuse-ai-pilot:research-expert - 通过 Context7 验证 Livewire 4 模式
3. mcp__context7__query-docs - 检查特定 Livewire 功能

实现完成后，运行 fuse-ai-pilot:sniper 进行验证。

---

概述

功能	说明
组件	带有 Blade 视图的响应式 PHP 类
wire:model	双向数据绑定
操作	从前端调用 PHP 方法
事件	组件通信
Volt	单文件组件
Folio	基于文件的路由

---

关键规则

1. 始终在循环中使用 wire:key
2. 实时验证使用 wire:model.live.blur（Livewire 4.1+：单独使用 .blur 只会同步客户端状态），不要到处使用 .live
3. 为搜索输入添加防抖，使用 .debounce.300ms
4. 敏感 ID 使用 #[Locked]
5. 在具有破坏性的操作中调用 authorize()
6. 内部逻辑使用 protected 方法

---

决策指南

组件类型

Component choice?
├── Complex logic → Class-based component
├── Simple page → Volt functional API
├── Medium complexity → Volt class-based
├── Quick embed → @volt inline
└── File-based route → Folio + Volt

数据绑定

Binding type?
├── Form fields (live validation) → wire:model.live.blur
├── Search input → wire:model.live.debounce.300ms
├── Checkbox/toggle → wire:model.live
├── Select → wire:model
└── No sync → Local Alpine x-data

---

参考指南

核心概念（原因与架构）

主题	参考资料	适用场景
组件	components.md	创建组件
Wire 指令	wire-directives.md	数据绑定、事件
生命周期	lifecycle.md	钩子、mount、hydrate
表单	forms-validation.md	验证、表单对象
事件	events.md	分发、监听
Alpine	alpine-integration.md	$wire、@entangle
文件上传	file-uploads.md	上传处理
嵌套	nesting.md	父子组件
加载	loading-states.md	wire:loading、延迟加载
导航	navigation.md	SPA 模式
测试	testing.md	组件测试
安全性	security.md	身份验证、速率限制
Volt	volt.md	单文件组件

高级功能

主题	参考资料	适用场景
Folio	folio.md	基于文件的路由
Precognition	precognition.md	实时验证
Reverb	reverb.md	WebSocket

模板（完整代码）

模板	适用场景
BasicComponent.php.md	标准组件
FormComponent.php.md	带验证的表单
VoltComponent.blade.md	Volt 模式
DataTableComponent.php.md	带搜索/排序的表格
FileUploadComponent.php.md	文件上传
NestedComponents.php.md	父子组件
ComponentTest.php.md	测试模式

---

快速参考

基础组件

class Counter extends Component
{
    public int $count = 0;

    public function increment(): void
    {
        $this->count++;
    }

    public function render()
    {
        return view('livewire.counter');
    }
}

Volt 函数式组件

<?php
use function Livewire\Volt\{state};

state(['count' => 0]);

$increment = fn() => $this->count++;
?>

<button wire:click="increment">{{ $count }}</button>

Wire 指令

<input wire:model.live.blur="email">
<input wire:model.live.debounce.300ms="search">
<button wire:click="save" wire:loading.attr="disabled">Save</button>

---

最佳实践

应该

• 在 @foreach 循环中使用 wire:key
• 对搜索/筛选输入启用防抖
• 使用 Form Objects 编写可复用逻辑
• 使用 Livewire::test() 进行测试
• ID 使用 #[Locked]，派生数据使用 #[Computed]

不应该

• 在每个字段上使用 wire:model.live
• 在 render() 方法中查询
• 忘记在操作中进行授权
• 在循环中省略 wire:key
• 在公共属性中存储敏感数据

---

Laravel 13 说明

Laravel 13 上的 Livewire 4

Livewire 4（当前版本为 4.4）是当前主版本，L13 Livewire 入门套件使用的正是该版本。要点如下：

• Livewire 4 的要求：PHP 8.1+ / Laravel 10+（Laravel 13 无论如何都要求 PHP 8.3）
• 仍支持 #[Locked]、#[Computed]、#[On]
• 原生单文件/多文件组件（默认 make_command.type = sfc）；Volt 仍为 1.x（当前版本为 1.11），Folio 仍为 1.x（当前版本为 1.2）
• 页面：现在推荐使用 Route::livewire('/dashboard', Dashboard::class)（单文件/多文件组件必须使用此方法）
• 哈希端点：使用 /livewire-{hash}/update（由 APP_KEY 派生），而非 /livewire/update——请更新针对 /livewire/ 的防火墙/CDN/中间件规则
• wire:model.live：并行请求；wire:poll 不会阻塞

从 Livewire 3 迁移

• 运行 composer require livewire/livewire:^4.0，然后运行 php artisan optimize:clear
• 重命名的配置项：layout → component_layout（layouts::app），lazy_placeholder → component_placeholder；默认 smart_wire_keys = true
• 4.1+：.blur / .change 也会控制客户端同步 → 如需旧行为（失焦时发送网络请求），请编写 wire:model.live.blur
• wire:model 会忽略来自子组件的事件（如有需要，添加 .deep）；<livewire:x /> 标签必须闭合
• wire:transition 使用 View Transitions API（已移除修饰符）；wire:scroll → wire:navigate:scroll
• $this->stream()：to: 重命名为 el:；$wire.$js('name', fn) 已弃用 → $wire.$js.name = fn
• wire:poll.5s、$this->dispatch('event')、Form Objects（#[\Livewire\Attributes\Validate]）→ 保持不变