livewire-development

Livewire 开发

适用场景

在以下情况下启用此技能：

• 创建或修改 Livewire 组件
• 使用 wire: 指令（model、click、loading、sort、intersect）
• 实现 islands 或异步操作
• 编写 Livewire 组件测试

文档

使用 search-docs 查阅 Livewire 4 的详细模式和文档。

基本用法

创建组件

Single-file component (default in v4)

{{ $assist->artisanCommand('make:livewire create-post') }}

Multi-file component

{{ $assist->artisanCommand('make:livewire create-post --mfc') }}

Class-based component (v3 style)

{{ $assist->artisanCommand('make:livewire create-post --class') }}

With namespace

{{ $assist->artisanCommand('make:livewire Posts/CreatePost') }}

在不同格式之间转换

使用 php artisan livewire:convert create-post 在单文件、多文件和基于类的格式之间转换。

组件格式参考

格式	标志	结构
单文件（SFC）	默认	PHP + Blade 位于同一文件
多文件（MFC）	--mfc	分离的 PHP 类、Blade、JS、测试
基于类	--class	传统的 v3 风格类
基于视图	⚡ 前缀	仅 Blade，带函数式状态

单文件组件示例

count++; } } ?>

Livewire 4 特性

与 Livewire 3 相比的主要变化

以下内容在 Livewire 4 中有所变化，但此应用可能尚未更新。请检查此应用的设置，确保遵循现有约定。

• 全页组件使用 Route::livewire()；配置键已重命名：layout → component_layout，lazy_placeholder → component_placeholder。
• wire:model 现在默认忽略子事件（旧行为请使用 wire:model.deep）；wire:scroll 已重命名为 wire:navigate:scroll。
• 组件标签必须正确闭合；wire:transition 现在使用 View Transitions API（已移除修饰符）。
• JavaScript：$wire.$js('name', fn) → $wire.$js.name = fn；commit/request 钩子 → interceptMessage()/interceptRequest()。

新功能

• 组件格式：单文件（SFC）、多文件（MFC）、基于视图的组件。
• Islands（@island）用于隔离更新；异步操作（wire:click.async、#[Async]）用于并行执行。
• 延迟/捆绑加载：使用 defer、lazy.bundle 优化组件加载。

功能	用法	目的
Islands	@island(name: 'stats')	隔离更新区域
异步	wire:click.async 或 #[Async]	非阻塞操作
延迟	defer 属性	在页面渲染后加载
捆绑	lazy.bundle	一起加载多个组件

新指令

• 可使用 wire:sort、wire:intersect、wire:ref、.renderless、.preserve-scroll。
• 会自动为触发网络请求的元素添加 data-loading 属性。

指令	目的
wire:sort	拖放排序
wire:intersect	检测视口交叉
wire:ref	用于 JS 的元素引用
.renderless	不渲染的组件
.preserve-scroll	保留滚动位置

最佳实践

• 在循环中始终使用 wire:key
• 使用 wire:loading 显示加载状态
• 使用 wire:model.live 实现即时更新（默认会进行防抖）
• 在操作中进行验证和授权（将其视为 HTTP 请求）

配置

• smart_wire_keys 默认为 true；新增配置：component_locations、component_namespaces、make_command、csp_safe。

Alpine 与 JavaScript

• wire:transition 使用浏览器的 View Transitions API；可使用 $errors 和 $intercept 魔法属性。
• 非阻塞式 wire:poll 和并行 wire:model.live 更新可提升性能。

有关拦截器和钩子，请参阅 reference/javascript-hooks.md。

测试

Livewire::test(Counter::class) ->assertSet('count', 0) ->call('increment') ->assertSet('count', 1);

验证

1. 浏览器控制台：检查是否有 JS 错误
2. 网络面板：确认 Livewire 请求返回 200
3. 确保所有 @foreach 循环都使用 wire:key

常见问题

• 循环中缺少 wire:key → 导致意外重新渲染
• 期望 wire:model 实时更新 → 使用 wire:model.live
• 组件标签未闭合 → 在 v4 中会导致语法错误
• 使用已弃用的配置键或 JS 钩子
• 单独引入 Alpine.js（Livewire 4 已内置 Alpine.js）