Livewire 中文文档

主题

安装 ​

Livewire 是一个 Laravel 包,因此在安装和使用 Livewire 之前,你需要有一个正在运行的 Laravel 应用程序。如果你需要帮助设置新的 Laravel 应用程序,请参阅 Laravel 官方文档。

前置要求 ​

在安装 Livewire 之前,请确保你有:

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

安装 Livewire ​

Livewire v4 目前处于 beta 阶段

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

要安装 Livewire,请打开终端并导航到你的 Laravel 应用程序目录,然后运行以下命令:

shell
composer require livewire/livewire:^4.0@beta

就是这样!Livewire 使用 Laravel 的包自动发现功能,因此不需要额外的设置。

准备好构建你的第一个组件了吗?前往 快速入门指南 在几分钟内创建你的第一个 Livewire 组件。

创建布局文件 ​

当将 Livewire 组件用作完整页面时,你需要一个布局文件。你可以使用 Livewire 命令生成一个:

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 将 Alpine.js 与其 JavaScript 打包在一起,因此两者一起加载。

资源注入是自动的

即使没有这些指令,Livewire 也会自动将其资源注入到包含 Livewire 组件的页面中。然而,包含这些指令可以让你明确控制资源的放置位置,这对于性能优化或与其他包的兼容性很有帮助。

发布配置文件 ​

Livewire 是“零配置”的,这意味着你可以通过遵循约定来使用它,而无需任何额外配置。然而,如果需要,你可以发布并自定义 Livewire 的配置文件:

shell
php artisan livewire:publish --config

这将在你的 Laravel 应用程序的 config 目录中创建一个新的 livewire.php 文件,你可以在其中自定义各种 Livewire 设置。

高级配置 ​

以下部分涵盖了大多数应用程序不需要的高级场景。只有在你有特定需求时才配置这些。

手动打包 Livewire 和 Alpine ​

何时需要:如果你想使用 Alpine.js 插件或对 Alpine 和 Livewire 的初始化时机进行精细控制。

默认情况下,Livewire 会自动加载与其 JavaScript 打包在一起的 Alpine.js。然而,如果你需要注册 Alpine 插件或自定义初始化顺序,可以使用 JavaScript 构建工具手动打包 Livewire 和 Alpine。

首先,将 @livewireScriptConfig 指令添加到你的布局文件中:

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
        @vite(['resources/js/app.js'])
    </head>
    <body>
        {{ $slot }}

        @livewireScriptConfig
    </body>
</html>

@livewireScriptConfig 指令注入 Livewire 需要的配置和运行时全局变量,但不包含实际的 Livewire 和 Alpine JavaScript(因为你自己打包它们)。手动打包时用 @livewireScriptConfig 替换 @livewireScripts。

接下来,在你的 resources/js/app.js 文件中导入并启动 Livewire 和 Alpine:

js
import { Livewire, Alpine } from '../../vendor/livewire/livewire/dist/livewire.esm';
import Clipboard from '@ryangjchandler/alpine-clipboard'

Alpine.plugin(Clipboard)

Livewire.start()

Livewire 更新后重新构建资源

手动打包时,请记住在通过 Composer 更新 Livewire 时重新构建 JavaScript 资源 (npm run build)。

自定义 Livewire 的更新端点 ​

何时需要:如果你的应用程序使用路由前缀进行本地化(如 /en/、/fr/)或多租户(如 /tenant-1/、/tenant-2/),你可能需要自定义 Livewire 的更新端点以匹配你的路由结构。

默认情况下,Livewire 将组件更新发送到 /livewire/update。要自定义此项,请在服务提供者中注册你自己的路由(通常是 App\Providers\AppServiceProvider):

php
use Livewire\Livewire;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        Livewire::setUpdateRoute(function ($handle) {
            return Route::post('/custom/livewire/update', $handle);
        });
    }
}

你还可以向更新路由添加中间件:

php
Livewire::setUpdateRoute(function ($handle) {
    return Route::post('/custom/livewire/update', $handle)
        ->middleware(['web', 'auth']);
});

自定义 JavaScript 资源 URL ​

何时需要:如果你的应用程序使用路由前缀进行本地化或多租户,你可能需要自定义 Livewire 从哪里提供其 JavaScript 以匹配你的路由结构。

默认情况下,Livewire 从 /livewire/livewire.js 提供其 JavaScript。要自定义此项,请在服务提供者中注册你自己的路由:

php
use Livewire\Livewire;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        Livewire::setScriptRoute(function ($handle) {
            return Route::get('/custom/livewire/livewire.js', $handle);
        });
    }
}

将 Livewire 的资源发布到 public 目录 ​

何时需要:如果你想直接通过 Web 服务器提供 Livewire 的 JavaScript(例如,用于 CDN 分发或特定的缓存策略)而不是通过 Laravel 路由。

你可以将 Livewire 的 JavaScript 资源发布到你的 public 目录:

bash
php artisan livewire:publish --assets

为了确保在更新 Livewire 时资源保持最新,请将此添加到你的 composer.json:

json
{
    "scripts": {
        "post-update-cmd": [
            "@php artisan vendor:publish --tag=livewire:assets --ansi --force"
        ]
    }
}

大多数应用程序不需要此项

发布资源很少必要。只有在你有特定的架构需求阻止 Laravel 动态提供资源时才这样做。

禁用自动资源注入 ​

何时需要:如果你想完全控制 Livewire 资源的加载时机和方式,可以禁用自动注入。

更新你的 config/livewire.php 文件中的 inject_assets 配置选项:

php
'inject_assets' => false,

禁用时,你必须在布局中手动包含 @livewireStyles 和 @livewireScripts,否则 Livewire 将无法运行。

或者,你可以在特定页面上强制资源注入:

php
\Livewire\Livewire::forceAssetInjection();

在你想要确保注入资源的路由或控制器中调用此项。

故障排除 ​

Livewire JavaScript 未加载 (404 错误) ​

症状:访问 /livewire/livewire.js 返回 404 错误,或 Livewire 功能不起作用。

常见原因:

Nginx 配置阻止路由: 如果你使用自定义配置的 Nginx,它可能会阻止 Laravel 的 /livewire/livewire.js 路由。你可以:

路由缓存: 如果你运行了 php artisan route:cache,Laravel 可能无法识别 Livewire 的路由。清除缓存:

shell
php artisan route:clear

缺少 @livewireScripts: 如果你禁用了自动资源注入,请确保 @livewireScripts 在你的布局文件中在 </body> 之前。

在没有 Livewire 组件的页面上 Alpine.js 不可用 ​

症状:你想在没有任何 Livewire 组件的页面上使用 Alpine.js。

解决方案:由于 Alpine 与 Livewire 打包在一起,即使在没有 Livewire 组件的页面上也需要包含 @livewireScripts:

blade
<!DOCTYPE html>
<html>
    <head>
        @livewireStyles
    </head>
    <body>
        <!-- No Livewire components, but we want Alpine -->
        <div x-data="{ open: false }">
            <button @click="open = !open">Toggle</button>
        </div>

        @livewireScripts
    </body>
</html>

或者,手动打包 Livewire 和 Alpine 并在你的 JavaScript 中导入 Alpine。

组件未更新或浏览器控制台中出现错误 ​

检查以下项:

  • 确保 @livewireStyles 在布局的 <head> 中
  • 确保 @livewireScripts 在布局中在 </body> 之前
  • 检查浏览器的开发者控制台是否有 JavaScript 错误
  • 验证你正在运行支持的 PHP 版本 (8.1+) 和 Laravel 版本 (10+)
  • 清除应用程序缓存: php artisan cache:clear

如果问题仍然存在,请查看故障排除文档以获取更详细的调试步骤。