Livewire 中文文档

主题

wire:transition ​

wire:transition 使用浏览器原生的 View Transitions API 在元素出现、消失或更改时启用平滑动画。

与基于 JavaScript 的动画库不同，View Transitions 是硬件加速的，由浏览器原生处理，从而实现更流畅的动画和更少的开销。

基本用法 ​

将 wire:transition 添加到任何可能在 Livewire 更新期间被添加、移除或更改的元素：

php
class ShowPost extends Component
{
    public Post $post;

    public $showComments = false;
}
blade
<div>
    <button wire:click="$toggle('showComments')">Toggle comments</button>

    @if ($showComments)
        <div wire:transition>
            @foreach ($post->comments as $comment)
                <div>{{ $comment->body }}</div>
            @endforeach
        </div>
    @endif
</div>

当评论出现或消失时，浏览器将平滑地淡入淡出它们，而不是突然显示或隐藏。

命名过渡 ​

默认情况下，Livewire 为带有 wire:transition 的元素分配 view-transition-name match-element。你可以提供自定义名称以启用更高级的过渡效果：

blade
<div wire:transition="sidebar">...</div>

这会将元素的 view-transition-name CSS 属性设置为 sidebar，你可以使用 CSS 定位它以实现自定义动画。

使用 CSS 自定义动画 ​

View Transitions 完全通过 CSS 控制。你可以通过定位 view-transition 伪元素来自定义动画：

css
/* Customize the transition for a specific element */
::view-transition-old(sidebar) {
    animation: 300ms ease-out slide-out;
}

::view-transition-new(sidebar) {
    animation: 300ms ease-in slide-in;
}

@keyframes slide-out {
    to { transform: translateX(-100%); }
}

@keyframes slide-in {
    from { transform: translateX(100%); }
}

View Transitions API 提供三个可以设置样式的伪元素：

  • ::view-transition-old(name) — 退出元素的快照
  • ::view-transition-new(name) — 进入元素的快照
  • ::view-transition-group(name) — 两个快照的容器

过渡类型 ​

对于更复杂的场景，如步骤向导，你需要根据方向使用不同的动画，可以使用过渡类型。这允许你以不同的方式为"前进"和"后退"设置动画。

使用 $this->transition() 方法设置过渡类型：

php
class Wizard extends Component
{
    public $step = 1;

    public function goToStep($step)
    {
        $this->transition(type: $step > $this->step ? 'forward' : 'backward');

        $this->step = $step;
    }
}

然后使用 :active-view-transition-type() 选择器在 CSS 中定位类型：

css
html:active-view-transition-type(forward) {
    &::view-transition-old(content) {
        animation: 300ms ease-out slide-out-left;
    }
    &::view-transition-new(content) {
        animation: 300ms ease-in slide-in-right;
    }
}

html:active-view-transition-type(backward) {
    &::view-transition-old(content) {
        animation: 300ms ease-out slide-out-right;
    }
    &::view-transition-new(content) {
        animation: 300ms ease-in slide-in-left;
    }
}

@keyframes slide-out-left {
    from { transform: translateX(0); opacity: 1; }
    to { transform: translateX(-100%); opacity: 0; }
}

@keyframes slide-in-right {
    from { transform: translateX(100%); opacity: 0; }
    to { transform: translateX(0); opacity: 1; }
}

@keyframes slide-out-right {
    from { transform: translateX(0); opacity: 1; }
    to { transform: translateX(100%); opacity: 0; }
}

@keyframes slide-in-left {
    from { transform: translateX(-100%); opacity: 0; }
    to { transform: translateX(0); opacity: 1; }
}

对于始终以相同方向过渡的方法，你可以改用 #[Transition] 属性：

php
use Livewire\Attributes\Transition;

class Wizard extends Component
{
    public $step = 1;

    #[Transition(type: 'forward')]
    public function next()
    {
        $this->step++;
    }

    #[Transition(type: 'backward')]
    public function previous()
    {
        $this->step--;
    }
}

跳过过渡 ​

有时你可能希望为特定操作禁用过渡——例如，一个"重置"按钮应该立即跳转到第一步而没有动画。

使用 $this->skipTransition() 为当前请求禁用过渡：

php
public function reset()
{
    $this->skipTransition();

    $this->step = 1;
}

或者使用带有 skip: true 的 #[Transition] 属性：

php
use Livewire\Attributes\Transition;

#[Transition(skip: true)]
public function reset()
{
    $this->step = 1;
}

尊重减少动画偏好 ​

Livewire 自动尊重用户的 prefers-reduced-motion 设置。启用后，将禁用过渡以避免对对动画敏感的用户造成不适。

浏览器支持 ​

View Transitions 在 Chrome 111+、Edge 111+ 和 Safari 18+ 中受支持。在不支持 View Transitions 的浏览器中，元素将在没有动画的情况下出现和消失——功能仍然有效，只是没有视觉过渡。

在 caniuse.com 上查看浏览器支持 →

另请参阅 ​

参考 ​

blade
wire:transition="name"
表达式描述
(无)使用 match-element 作为 view-transition-name
"name"使用提供的字符串作为 view-transition-name

此指令没有修饰符。