
alpine.js 的 x-transition 指令仅支持配合 x-show 使用,无法直接作用于 x-bind 触发的属性变更;本文详解其原理,并提供可立即使用的双图切换 + 过渡动画方案。
在 Alpine.js 中,x-transition 是一个基于显示/隐藏状态(visibility lifecycle)设计的指令,它依赖于元素的 display 属性切换(如 block ↔ none)来触发 CSS 过渡类(如 enter, leave, enter-active, leave-active 等)。而 x-bind:src 仅修改 <img> 的 src 属性——DOM 元素本身始终存在且未重绘,因此 x-transition 完全不会被激活。
✅ 正确解法:用 x-show 控制两张图片的显隐切换,并为两者分别添加 x-transition,从而利用 Alpine 内置的过渡生命周期钩子实现淡入淡出、缩放等动画效果。
以下是一个完整、可运行的示例(兼容 Alpine v3+):
<script src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js" defer></script>
<div x-data="{ hover: false }" class="h-3/5 mb-2 relative overflow-hidden">
<!-- 鼠标移入时显示 hover 图片 -->
<img
x-show="hover"
x-transition:enter="transition-opacity duration-300"
x-transition:enter-start="opacity-0 scale-95"
x-transition:enter-end="opacity-100 scale-100"
x-transition:leave="transition-opacity duration-200"
x-transition:leave-start="opacity-100 scale-100"
x-transition:leave-end="opacity-0 scale-95"
class="h-full w-auto m-auto absolute inset-0"
src="https://picsum.photos/id/237/200/300"
alt="Hover image"
>
<!-- 默认显示基础图片 -->
<img
x-show="!hover"
x-transition:enter="transition-opacity duration-300"
x-transition:enter-start="opacity-0 scale-95"
x-transition:enter-end="opacity-100 scale-100"
x-transition:leave="transition-opacity duration-200"
x-transition:leave-start="opacity-100 scale-100"
x-transition:leave-end="opacity-0 scale-95"
class="h-full w-auto m-auto absolute inset-0"
src="https://picsum.photos/id/238/200/300"
alt="Default image"
>
<!-- 触发逻辑:使用 @mouseover / @mouseleave 更语义化 -->
<div
class="absolute inset-0 cursor-pointer"
@mouseover="hover = true"
@mouseleave="hover = false"
></div>
</div>? 关键要点说明:
- 使用 x-show 而非 x-bind:src 切换图像,确保 Alpine 能捕获显示状态变化并触发 x-transition;
- 两张 <img> 共享相同尺寸与定位(absolute inset-0 + m-auto),避免布局跳动;
- x-transition:* 属性可精细化控制入场/离场的过渡类名与时长(推荐搭配 Tailwind 的 transition-* 工具类);
- 外层透明覆盖层(<div>)用于统一捕获悬停事件,提升响应区域可靠性;
- 若需支持键盘焦点(如无障碍访问),可额外添加 @focus 和 @blur 处理。
⚠️ 注意:不要尝试对单个 <img> 同时使用 x-bind:src 和 x-transition——这属于误用场景,Alpine 不会响应,浏览器也不会触发 CSS 过渡。
通过这种「状态驱动渲染 + 显隐过渡」的设计模式,你不仅能实现丝滑图像切换,还能轻松扩展为多图轮播、加载占位、错误降级等更健壮的交互逻辑。










