livewire-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Livewire Development

Livewire开发

When to Apply

适用场景

Activate this skill when:

Creating or modifying Livewire components
Using wire: directives (model, click, loading, sort, intersect)
Implementing islands or async actions
Writing Livewire component tests

在以下场景中使用本技能：

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

Documentation

文档参考

Use

search-docs

for detailed Livewire 4 patterns and documentation.

使用

search-docs

获取Livewire 4的详细模式和文档。

Basic Usage

基础用法

Creating Components

创建组件

<code-snippet name="Component Creation Commands" lang="bash">

Single-file component (default in v4)

Multi-file component

Class-based component (v3 style)

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

With namespace

</code-snippet>

Converting Between Formats

格式转换

Use

php artisan livewire:convert create-post

to convert between single-file, multi-file, and class-based formats.

使用

php artisan livewire:convert create-post

在单文件、多文件和基于类的格式之间转换。

Component Format Reference

组件格式参考

Format	Flag	Structure
Single-file (SFC)	default	PHP + Blade in one file
Multi-file (MFC)	`--mfc`	Separate PHP class, Blade, JS, tests
Class-based	`--class`	Traditional v3 style class
View-based	⚡ prefix	Blade-only with functional state

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

Single-File Component Example

单文件组件示例

<code-snippet name="Single-File Component Example" lang="php"> <?php use Livewire\Component; new class extends Component { public int $count = 0; public function increment(): void { $this->count++; } } ?> <div> <button wire:click="increment">Count: @{{ $count }}</button> </div> </code-snippet>

Livewire 4 Specifics

Livewire 4特性

Key Changes From Livewire 3

与Livewire 3的主要差异

These things changed in Livewire 4, but may not have been updated in this application. Verify this application's setup to ensure you follow existing conventions.

Use

Route::livewire()

for full-page components; config keys renamed:

layout

→

component_layout

lazy_placeholder

→

component_placeholder

```
wire:model
```
now ignores child events by default (use
```
wire:model.deep
```
for old behavior);
```
wire:scroll
```
renamed to
```
wire:navigate:scroll
```
.
Component tags must be properly closed;
```
wire:transition
```
now uses View Transitions API (modifiers removed).

JavaScript:

$wire.$js('name', fn)

→

$wire.$js.name = fn

;

commit

request

hooks →

interceptMessage()

interceptRequest()

这些是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()

。

New Features

新特性

Component formats: single-file (SFC), multi-file (MFC), view-based components.
Islands (
```
@island
```
) for isolated updates; async actions (
```
wire:click.async
```
,
```
#[Async]
```
) for parallel execution.
Deferred/bundled loading:
```
defer
```
,
```
lazy.bundle
```
for optimized component loading.

Feature	Usage	Purpose
Islands	`@island(name: 'stats')`	Isolated update regions
Async	`wire:click.async` or `#[Async]`	Non-blocking actions
Deferred	`defer` attribute	Load after page render
Bundled	`lazy.bundle`	Load multiple together

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

特性	用法	用途
独立组件	`@island(name: 'stats')`	隔离更新区域
异步操作	`wire:click.async` 或 `#[Async]`	非阻塞操作
延迟加载	`defer` 属性	页面渲染后加载
捆绑加载	`lazy.bundle`	批量加载多个组件

New Directives

新指令

wire:sort

wire:intersect

wire:ref

.renderless

.preserve-scroll

are available for use.

```
data-loading
```
attribute automatically added to elements triggering network requests.

Directive	Purpose
`wire:sort`	Drag-and-drop sorting
`wire:intersect`	Viewport intersection detection
`wire:ref`	Element references for JS
`.renderless`	Component without rendering
`.preserve-scroll`	Preserve scroll position

wire:sort

、

wire:intersect

、

wire:ref

、

.renderless

、

.preserve-scroll

已可用。

触发网络请求的元素会自动添加
```
data-loading
```
属性。

指令	用途
`wire:sort`	拖拽排序
`wire:intersect`	视口交叉检测
`wire:ref`	供JS使用的元素引用
`.renderless`	无渲染组件
`.preserve-scroll`	保留滚动位置

Best Practices

最佳实践

Always use
```
wire:key
```
in loops
Use
```
wire:loading
```
for loading states
Use
```
wire:model.live
```
for instant updates (default is debounced)
Validate and authorize in actions (treat like HTTP requests)

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

Configuration

配置

smart_wire_keys

defaults to

true

; new configs:

component_locations

component_namespaces

make_command

csp_safe

smart_wire_keys

默认值为

true

；新增配置项：

component_locations

、

component_namespaces

、

make_command

、

csp_safe

。

Alpine & JavaScript

Alpine与JavaScript

```
wire:transition
```
uses browser View Transitions API;
```
$errors
```
and
```
$intercept
```
magic properties available.
Non-blocking
```
wire:poll
```
and parallel
```
wire:model.live
```
updates improve performance.

For interceptors and hooks, see reference/javascript-hooks.md.

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

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

Testing

测试

<code-snippet name="Testing Example" lang="php">

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

</code-snippet>

<code-snippet name="Testing Example" lang="php">

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

</code-snippet>

Verification

验证

Browser console: Check for JS errors
Network tab: Verify Livewire requests return 200
Ensure
```
wire:key
```
on all
```
@foreach
```
loops

浏览器控制台：检查JS错误
网络面板：验证Livewire请求返回200状态码
确保所有
```
@foreach
```
循环都使用
```
wire:key
```

Common Pitfalls

常见误区

Missing
```
wire:key
```
in loops → unexpected re-rendering
Expecting
```
wire:model
```
real-time → use
```
wire:model.live
```
Unclosed component tags → syntax errors in v4
Using deprecated config keys or JS hooks
Including Alpine.js separately (already bundled in Livewire 4)

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