Livewire 中文文档

主题

全部文档

Defer ​

#[Defer] 属性使组件在初始页面加载完成后立即加载，防止慢速组件阻塞页面渲染。

基本用法 ​

将 #[Defer] 属性应用到任何应延迟加载的组件上：

php
<?php // resources/views/components/⚡revenue.blade.php

use Livewire\Attributes\Defer;
use Livewire\Component;
use App\Models\Transaction;

new #[Defer] class extends Component { // [tl! highlight]
    public $amount;

    public function mount()
    {
        // Slow database query...
        $this->amount = Transaction::monthToDate()->sum('amount');
    }
};
?>

<div>
    Revenue this month: {{ $amount }}
</div>

使用 #[Defer] 时，组件最初渲染为空的 <div></div>，然后在页面加载完成后立即加载——无需等待其进入视口。

Lazy 与 Defer ​

Livewire 提供两种延迟组件加载的方式：

  • 懒加载（#[Lazy]） - 组件在进入视口可见时加载（用户滚动到它们时）
  • 延迟加载（#[Defer]） - 组件在初始页面加载完成后立即加载

两者都能防止慢速组件阻塞初始页面渲染，但组件实际加载的时机不同。

渲染占位符 ​

默认情况下，组件加载前 Livewire 会渲染空的 <div></div>。你可以使用 placeholder() 方法提供自定义占位符：

php
<?php // resources/views/components/⚡revenue.blade.php

use Livewire\Attributes\Defer;
use Livewire\Component;
use App\Models\Transaction;

new #[Defer] class extends Component {
    public $amount;

    public function mount()
    {
        $this->amount = Transaction::monthToDate()->sum('amount');
    }

    public function placeholder() // [tl! highlight:start]
    {
        return <<<'HTML'
        <div>
            <svg><!-- Loading spinner... --></svg>
        </div>
        HTML;
    } // [tl! highlight:end]
};
?>

<div>
    Revenue this month: {{ $amount }}
</div>

在组件完全加载之前，用户会看到加载动画。

WARNING

占位符元素类型需匹配

若占位符的根元素是 <div>，组件也必须使用 <div> 元素。

打包请求 ​

默认情况下，延迟组件通过独立的网络请求并行加载。要将多个延迟组件打包到单个请求中，请使用 bundle 参数：

php
<?php // resources/views/components/⚡revenue.blade.php

use Livewire\Attributes\Defer;
use Livewire\Component;

new #[Defer(bundle: true)] class extends Component { // [tl! highlight]
    // ...
};

现在，若页面上有十个 revenue 组件，全部十个将通过单个打包的网络请求加载，而不是十个并行请求。

替代方式 ​

使用 defer 参数 ​

除了属性，你也可以用 defer 参数延迟特定组件实例：

blade
<livewire:revenue defer />

当你只想延迟某个组件的部分实例时，这种方式很有用。

覆盖属性 ​

若组件有 #[Defer]，但某些情况下希望立即加载，可以覆盖它：

blade
<livewire:revenue :defer="false" />

何时使用 ​

在以下情况使用 #[Defer]：

  • 组件包含会拖慢页面加载的慢操作（数据库查询、API 调用）
  • 组件在初始页面加载时始终可见（若在首屏以下，请改用 `#[Lazy]`）
  • 希望通过更快显示页面来提升感知性能

了解更多 ​

关于懒加载与延迟加载的完整文档（含占位符与打包策略），请参阅懒加载文档。

参考 ​

php
#[Defer(
    bool|null $bundle = null,
)]
参数类型默认值说明
$bundlebool|nullnull将多个延迟组件打包到单个网络请求中