Livewire 中文文档

主题

@persist ​

@persist 指令用于在使用 wire:navigate 进行页面导航时保留元素的状态，避免重新初始化。

基本用法 ​

用 @persist 包裹元素并提供唯一名称，以便在页面访问之间保留它：

blade
@persist('player')
    <audio src="{{ $episode->file }}" controls></audio>
@endpersist

当导航到同样包含相同名称持久化元素的新页面时，Livewire 会复用现有 DOM 元素而非创建新元素。对于音频播放器，这意味着播放会持续进行不会中断。

需要 wire:navigate

@persist 指令仅在使用 Livewire 的 wire:navigate 功能处理导航时生效。标准页面加载不会保留元素。

常见用例 ​

音频/视频播放器

blade
@persist('podcast-player')
    <audio src="{{ $episode->audio_url }}" controls></audio>
@endpersist

聊天小部件

blade
@persist('support-chat')
    <div id="chat-widget">
        <!-- 聊天界面... -->
    </div>
@endpersist

第三方组件

blade
@persist('analytics-widget')
    <div id="analytics-dashboard">
        <!-- 初始化成本高的复杂组件... -->
    </div>
@endpersist

在布局中放置 ​

持久化元素通常应放在 Livewire 组件外部，一般在主布局中：

blade
<!-- resources/views/layouts/app.blade.php -->

<!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>
        <main>
            {{ $slot }}
        </main>

        @persist('player')
            <audio src="{{ $episode->file }}" controls></audio>
        @endpersist

        @livewireScripts
    </body>
</html>

保持滚动位置 ​

对于可滚动的持久化元素，添加 wire:scroll 来保持滚动位置：

blade
@persist('scrollable-list')
    <div class="overflow-y-scroll" wire:scroll>
        <!-- 可滚动内容... -->
    </div>
@endpersist

在持久化元素内部，使用 wire:current 而非服务端条件判断来高亮活动链接：

blade
@persist('navigation')
    <nav>
        <a href="/dashboard" wire:navigate wire:current="font-bold">仪表盘</a>
        <a href="/posts" wire:navigate wire:current="font-bold">文章</a>
        <a href="/users" wire:navigate wire:current="font-bold">用户</a>
    </nav>
@endpersist

了解更多关于 wire:current →

工作原理 ​

使用 wire:navigate 导航时：

  1. Livewire 在两个页面上查找具有匹配 @persist 名称的元素
  2. 如果找到，现有元素会被移动到新页面的 DOM 中
  3. 元素的状态、事件监听器和 Alpine 数据都会被保留

了解更多关于导航 →

参考 ​

blade
@persist(string $key)
    <!-- 内容 -->
@endpersist
参数类型默认值说明
$keystring必需用于在页面导航之间标识要保留的元素的唯一名称