快速开始

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

为了演示，我们将构建一个带有实时验证的简单文章创建表单。你将看到 Livewire 如何在不编写任何 JavaScript 或手动处理 AJAX 请求的情况下验证输入并动态更新页面。

前置要求

在开始之前，请确保已安装以下内容：

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

安装 Livewire

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

shell

composer require livewire/livewire:^4.0

创建布局文件

在创建组件之前，让我们先设置一个布局文件，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 资源。你的组件将在变量的位置渲染。

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

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

尝试以下操作：

测试验证： 不填写任何字段直接点击"Save Post"。你会看到红色错误消息立即出现在每个字段下方——无需页面刷新。
测试提交： 填写两个字段并点击"Save Post"。你应该会看到一个调试界面显示你输入的值。

这展示了 Livewire 的核心能力：响应式数据绑定、实时验证和表单处理——全部用 PHP 编写，无需接触 JavaScript。

故障排除

组件未找到错误：

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

表单不提交或验证不显示：

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

访问路由时出现 404 错误：

验证路由已添加到 routes/web.php

下一步

现在你已经构建了第一个 Livewire 组件，以下是一些需要探索的关键概念：

组件 — 了解单文件与多文件组件、传递数据等
属性 — 理解组件属性的工作原理和生命周期
操作 — 深入了解方法、参数和事件处理
表单 — 探索 Livewire 强大的表单功能，包括实时验证
验证 — 掌握 Livewire 的所有验证能力

我们只是触及了 Livewire 能力的表面。继续阅读文档，了解 Livewire 提供的一切功能。

快速开始 ​

前置要求 ​

安装 Livewire ​

创建布局文件 ​

创建 Livewire 组件 ​

编写组件 ​

注册路由 ​

测试一下 ​

故障排除 ​

下一步 ​

快速开始

前置要求

安装 Livewire

创建布局文件

创建 Livewire 组件

编写组件

注册路由

测试一下

故障排除

下一步