Livewire 中文文档

主题

全部文档

快速开始 ​

Livewire 让你只用 PHP 就能构建动态、响应式的界面——无需编写 JavaScript。不必在 JavaScript 框架里写前端代码，你只需编写简单的 PHP 类和 Blade 模板，复杂的 JavaScript 由 Livewire 在幕后处理。

下面我们会做一个带实时验证的简单文章创建表单。你会看到 Livewire 如何校验输入并动态更新页面，全程不用写一行 JavaScript，也不用手动处理 AJAX 请求。

前置条件 ​

开始之前，请确认已安装：

  • Laravel 10 或更高版本
  • PHP 8.1 或更高版本

安装 Livewire ​

在 Laravel 应用根目录下，运行以下 Composer 命令：

shell
composer require livewire/livewire

创建布局 ​

创建组件之前，先准备一个布局文件，供 Livewire 组件渲染到其中。默认情况下，Livewire 会查找：resources/views/layouts/app.blade.php

可以运行以下命令创建该文件：

shell
php artisan livewire:layout

这会生成 resources/views/layouts/app.blade.php，内容如下：

blade
<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">

        <title>{{ $title ?? config('app.name') }}</title>

        @vite(['resources/css/app.css', 'resources/js/app.js'])

        @livewireStyles
    </head>
    <body>
        {{ $slot }}

        @livewireScripts
    </body>
</html>

@livewireStyles 和 @livewireScripts 指令会引入 Livewire 运行所需的 JavaScript 和 CSS。你的组件会渲染到 {{ $slot }} 所在的位置。

创建 Livewire 组件 ​

Livewire 提供了方便的 Artisan 命令来生成新组件。运行以下命令创建一个页面组件：

shell
php artisan make:livewire pages::post.create

因为该组件会作为整页使用，我们加上 pages:: 前缀，把它放在 pages 目录下统一管理。

该命令会在 resources/views/pages/post/⚡create.blade.php 生成一个新的单文件组件。

INFO

⚡ 表情是怎么回事？

闪电符号让 Livewire 组件在编辑器里一眼就能认出来。它完全可选，也可以在配置里关闭。详情见组件文档。

编写组件 ​

打开 resources/views/pages/post/⚡create.blade.php，把内容替换为：

blade
<?php

use Livewire\Component;

new class extends Component {
    public string $title = '';

    public string $content = '';

    public function save()
    {
        $this->validate([
            'title' => 'required|max:255',
            'content' => 'required',
        ]);

        dd($this->title, $this->content);
    }
};
?>

<form wire:submit="save">
    <label>
        Title
        <input type="text" wire:model="title">
        @error('title') <span style="color: red;">{{ $message }}</span> @enderror
    </label>

    <label>
        Content
        <textarea wire:model="content" rows="5"></textarea>
        @error('content') <span style="color: red;">{{ $message }}</span> @enderror
    </label>

    <button type="submit">Save Post</button>
</form>

INFO

先不用管样式

这个表单刻意不加样式，方便专注于 Livewire 的功能。真实应用里你可以加 CSS，或使用 Tailwind 这类框架。

上面代码在做什么：

组件属性：

  • public string $title = ''; — 声明文章标题的公共属性
  • public string $content = ''; — 声明文章内容的公共属性

组件方法：

  • public function save() — 表单提交时调用。校验数据并把结果 dump 出来便于测试。

Livewire 指令：

  • wire:submit="save" — 表单提交时调用 save()，并阻止默认的整页刷新
  • wire:model="title" — 在输入框与 $title 属性之间建立双向绑定。输入时属性会自动更新
  • wire:model="content" — 对 textarea 与 $content 做同样的双向绑定
  • @error('title') 和 @error('content') — 校验失败时显示错误信息

WARNING

Livewire 组件必须有且仅有一个根元素

组件必须恰好有一个根 HTML 元素。本例中 <form> 就是唯一的根。多个根元素，或根元素外的 HTML 注释，都会导致错误。渲染整页组件时，布局的具名插槽可以放在根元素之外。

TIP

在真实应用中

save() 方法用 dd() dump 值是为了方便测试。生产环境里通常会把数据写入数据库并重定向：

php
public function save()
{
    $validated = $this->validate([
        'title' => 'required|max:255',
        'content' => 'required',
    ]);

    Post::create($validated); // Assumes you have a Post model and database table

    return $this->redirect('/posts');
}

注册路由 ​

打开 Laravel 应用中的 routes/web.php，添加：

php
Route::livewire('/post/create', 'pages::post.create');

之后用户访问 /post/create 时，Livewire 会在布局文件中渲染 pages::post.create 组件。

试一试 ​

一切就绪后，来测试这个组件！

如果还没启动，先启动 Laravel 开发服务器：

shell
php artisan serve

在浏览器打开 http://localhost:8000/post/create（若使用 Valet、Herd 等工具，则访问 http://yourapp.test/post/create）。

你应该会看到一个带两个字段和提交按钮的简单表单。

试着这样做：

  1. 测试校验： 不填任何字段直接点 "Save Post"。每个字段下方会立刻出现红色错误信息——无需刷新页面。

  2. 测试提交： 填好两个字段再点 "Save Post"。你会看到调试页面显示出刚才输入的值。

这展示了 Livewire 的核心能力：响应式数据绑定、实时校验和表单处理——全部用 PHP 完成，不用碰 JavaScript。

排查问题 ​

找不到组件错误：

  • 确认组件文件存在于 resources/views/pages/post/⚡create.blade.php
  • 检查路由中的组件名是否匹配：'pages::post.create'

表单无法提交或校验不显示：

  • 确认布局的 <head> 中有 @livewireStyles，且 </body> 前有 @livewireScripts
  • 检查浏览器控制台是否有 JavaScript 错误

访问路由出现 404：

  • 确认路由已写入 routes/web.php

下一步 ​

写出第一个 Livewire 组件之后，可以继续了解这些关键概念：

  • 组件 — 了解单文件与多文件组件、传参等
  • 属性 — 理解组件属性及其生命周期
  • 动作 — 深入方法、参数与事件处理
  • 表单 — 探索 Livewire 强大的表单能力，包括实时校验
  • 校验 — 掌握 Livewire 的全部校验能力

这只是 Livewire 能力的冰山一角。继续阅读文档，你会看到 Livewire 能做的更多事情。