快速入门

Livewire 让你可以仅使用 PHP 构建动态、响应式的界面——无需编写 JavaScript。你不用在 JavaScript 框架中编写前端代码，只需编写简单的 PHP 类和 Blade 模板，Livewire 会在幕后处理所有复杂的 JavaScript 逻辑。

为了演示，我们将构建一个带有实时验证的简单文章创建表单。你会看到 Livewire 如何验证输入并动态更新页面，而无需编写一行 JavaScript 代码或手动处理 AJAX 请求。

前置要求

在开始之前，请确保你已安装以下环境：

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

安装 Livewire

Livewire v4 目前处于测试阶段

Livewire v4 仍在积极开发中，尚未稳定。建议在升级生产环境应用之前，先在开发环境中进行充分测试。测试版本之间可能会出现破坏性更改。

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

shell

composer require livewire/livewire:^4.0@beta

创建布局文件

在创建组件之前，让我们先设置一个布局文件，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 ?? 'Page Title' }}</title>

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

        @livewireScripts
    </body>
</html>

@livewireStyles 和 @livewireScripts 指令会引入 Livewire 运行所需的 JavaScript 和 CSS 资源。你的组件将在变量的位置渲染。

创建 Livewire 组件

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

shell

php artisan make:livewire pages::post.create

由于这个组件将作为完整页面使用，我们使用 pages:: 前缀将其组织在 pages 目录中。

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

⚡ 表情符号是什么意思？

闪电符号让 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>

不用担心样式

这个表单故意没有添加样式，这样我们可以专注于 Livewire 的功能。在实际应用中，你可以添加 CSS 或使用 Tailwind 等框架。

以下是上述代码的详细解释：

组件属性：

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

组件方法：

public function save() — 当表单提交时调用。验证数据并输出结果以便测试。

Livewire 指令：

wire:submit="save" — 当表单提交时调用 save() 方法，阻止默认的页面重载
wire:model="title" — 在输入框和 $title 属性之间创建双向数据绑定。当你输入时，属性会自动更新
wire:model="content" — 为文本域和 $content 属性创建相同的双向绑定
@error('title') 和 @error('content') — 当验证失败时显示验证错误信息

Livewire 组件必须有一个根元素

组件必须有且仅有一个根 HTML 元素。在本例中，<form> 元素就是这个根元素。多个根元素或根元素外的 HTML 注释会导致错误。当渲染全页面组件时，可以在根元素外放置布局的命名插槽。

在实际应用中

save() 方法使用 dd() 输出值以便测试。在生产环境中，你通常会将数据保存到数据库并重定向：

php

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

    Post::create($validated); // 假设你有 Post 模型和数据表

    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）。

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

尝试以下操作：

测试验证：不填写任何字段，直接点击“保存文章”。你会看到红色错误信息立即出现在每个字段下方——无需重载页面。
测试数据绑定：开始在标题字段中输入。Livewire 会自动实时将你的输入与服务端的 $title 属性同步。
测试提交：填写两个字段并点击“保存文章”。你应该会看到一个调试页面，显示你输入的值。

这展示了 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 的更多功能。

快速入门 ​

前置要求 ​

安装 Livewire ​

创建布局文件 ​

创建 Livewire 组件 ​

编写组件 ​

注册路由 ​

测试运行 ​

故障排除 ​

下一步 ​

快速入门

前置要求

安装 Livewire

创建布局文件

创建 Livewire 组件

编写组件

注册路由

测试运行

故障排除

下一步