Livewire 中文文档

主题

全部文档

@persist ​

@persist 指令在使用 wire:navigate 时跨页面导航保留元素，维持其状态并避免重新初始化。

基本用法 ​

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

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

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

TIP

需要 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">
        <!-- Chat interface... -->
    </div>
@endpersist

第三方小部件

blade
@persist('analytics-widget')
    <div id="analytics-dashboard">
        <!-- Complex widget that's expensive to initialize... -->
    </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:navigate:scroll 以保持滚动位置：

blade
@persist('scrollable-list')
    <div class="overflow-y-scroll" wire:navigate:scroll>
        <!-- Scrollable content... -->
    </div>
@endpersist

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

blade
@persist('navigation')
    <nav>
        <a href="/dashboard" wire:navigate wire:current="font-bold">Dashboard</a>
        <a href="/posts" wire:navigate wire:current="font-bold">Posts</a>
        <a href="/users" wire:navigate wire:current="font-bold">Users</a>
    </nav>
@endpersist

了解更多关于 wire:current →

工作原理 ​

使用 wire:navigate 导航时：

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

了解更多关于导航 →

参考 ​

blade
@persist(string $key)
    <!-- Content -->
@endpersist
参数类型默认值说明
$keystring必填用于跨页面导航识别要持久化元素的唯一名称