laravel-livewire

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Laravel Livewire

Agent Workflow (MANDATORY)

Agent 工作流（必填）

Before ANY implementation, use

TeamCreate

to spawn 3 agents:

fuse-ai-pilot:explore-codebase - Check existing Livewire components
fuse-ai-pilot:research-expert - Verify Livewire 3 patterns via Context7
mcp__context7__query-docs - Check specific Livewire features

After implementation, run fuse-ai-pilot:sniper for validation.

在任何实现工作开始前，使用

TeamCreate

生成3个Agent：

fuse-ai-pilot:explore-codebase - 检查现有Livewire组件
fuse-ai-pilot:research-expert - 通过Context7验证Livewire 3的开发模式
mcp__context7__query-docs - 查阅Livewire的特定功能

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

Overview

概述

Feature	Description
Components	Reactive PHP classes with Blade views
wire:model	Two-way data binding
Actions	Call PHP methods from frontend
Events	Component communication
Volt	Single-file components
Folio	File-based routing

特性	描述
Components	搭配Blade视图的响应式PHP类
wire:model	双向数据绑定
Actions	从前端调用PHP方法
Events	组件间通信
Volt	单文件组件
Folio	基于文件的路由

Critical Rules

关键规则

Always use wire:key in loops
Use wire:model.blur for validation, not .live everywhere
Debounce search inputs with .debounce.300ms
#[Locked] for sensitive IDs
authorize() in destructive actions
protected methods for internal logic

在循环中必须使用wire:key
验证场景下使用wire:model.blur，不要到处用.live
为搜索输入添加防抖处理，使用.debounce.300ms
敏感ID使用**#[Locked]**注解
破坏性动作中调用authorize()
内部逻辑使用protected方法

Decision Guide

决策指南

Component Type

组件类型

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

选择组件类型？
├── 复杂逻辑 → 基于类的组件
├── 简单页面 → Volt函数式API
├── 中等复杂度 → Volt基于类的组件
├── 快速嵌入 → @volt内联方式
└── 基于文件的路由 → Folio + Volt

Data Binding

数据绑定

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

选择绑定类型？
├── 表单字段 → wire:model.blur
├── 搜索输入 → wire:model.live.debounce.300ms
├── 复选框/切换按钮 → wire:model.live
├── 下拉选择框 → wire:model
└── 无需同步 → 本地Alpine x-data

Reference Guide

参考指南

Core Concepts (WHY & Architecture)

核心概念（设计思路与架构）

Topic	Reference	When to Consult
Components	components.md	Creating components
Wire Directives	wire-directives.md	Data binding, events
Lifecycle	lifecycle.md	Hooks, mount, hydrate
Forms	forms-validation.md	Validation, form objects
Events	events.md	Dispatch, listen
Alpine	alpine-integration.md	$wire, @entangle
File Uploads	file-uploads.md	Upload handling
Nesting	nesting.md	Parent-child
Loading	loading-states.md	wire:loading, lazy
Navigation	navigation.md	SPA mode
Testing	testing.md	Component tests
Security	security.md	Auth, rate limit
Volt	volt.md	Single-file components

主题	参考文档	查阅场景
Components	components.md	创建组件时
Wire Directives	wire-directives.md	数据绑定、事件处理时
Lifecycle	lifecycle.md	钩子函数、mount、hydrate阶段
Forms	forms-validation.md	验证、表单对象时
Events	events.md	事件分发、监听时
Alpine	alpine-integration.md	$wire、@entangle使用时
File Uploads	file-uploads.md	文件上传处理时
Nesting	nesting.md	父子组件开发时
Loading	loading-states.md	wire:loading、懒加载使用时
Navigation	navigation.md	SPA模式开发时
Testing	testing.md	组件测试时
Security	security.md	认证、速率限制时
Volt	volt.md	单文件组件开发时

Advanced Features

高级特性

Topic	Reference	When to Consult
Folio	folio.md	File-based routing
Precognition	precognition.md	Live validation
Reverb	reverb.md	WebSockets

主题	参考文档	查阅场景
Folio	folio.md	基于文件的路由开发时
Precognition	precognition.md	实时验证时
Reverb	reverb.md	WebSockets使用时

Templates (Complete Code)

模板（完整代码）

Template	When to Use
BasicComponent.php.md	Standard component
FormComponent.php.md	Form with validation
VoltComponent.blade.md	Volt patterns
DataTableComponent.php.md	Table with search/sort
FileUploadComponent.php.md	File uploads
NestedComponents.php.md	Parent-child
ComponentTest.php.md	Testing patterns

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

Quick Reference

快速参考

Basic Component

基础组件

php

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

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

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

php

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

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

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

Volt Functional

Volt 函数式组件

php

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

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

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

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

php

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

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

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

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

Wire Directives

Wire 指令

blade

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

blade

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

Best Practices

最佳实践

DO

建议做法

Use wire:key in @foreach loops
Debounce search/filter inputs
Use Form Objects for reusable logic
Test with Livewire::test()
#[Locked] for IDs, #[Computed] for derived data

在@foreach循环中使用wire:key
对搜索/筛选输入添加防抖处理
使用表单对象实现可复用逻辑
使用Livewire::test()进行测试
对ID使用#[Locked]注解，对派生数据使用#[Computed]注解

DON'T

不建议做法

wire:model.live on every field
Query in render() method
Forget authorization in actions
Skip wire:key in loops
Store sensitive data in public properties

对所有字段都使用wire:model.live
在render()方法中执行查询
动作中忘记添加授权验证
循环中省略wire:key
在公共属性中存储敏感数据