Transition 过渡动画

过渡容器：包一层内容，show 受控切换时以淡入 / 滑入 / 缩放过渡显示与隐藏。完整生命周期事件（前 / 中 / 后 × 进 / 出）可用于动画编排、联动与埋点。内容默认流式排布，配合 custom-style 定位可以做成浮层壳、引导层、展开面板等任意需要过渡出入场的形态。

平台兼容性

App(Android/iOS)	Web	微信小程序	鸿蒙
✓	✓	✓	✓

基本使用

通过 show 控制显隐；内容经默认插槽传入：

<n-transition :show="show">
	<view class="box"><text>过渡内容</text></view>
</n-transition>

动画模式

mode 指定过渡模式：fade 淡入（默认）、fade-up / fade-down / fade-left / fade-right 位移淡入、slide-up / slide-down / slide-left / slide-right 纯位移进入、zoom-in 缩放进（由小到大）、zoom-out 缩放出（由大到小）：

<n-transition :show="show" mode="slide-left">
	<view class="box"><text>从右侧滑入</text></view>
</n-transition>

mode 也接受数组，组合多个正交效果（淡入与位移 / 缩放叠加），值域 fade / slide-top / slide-right / slide-bottom / slide-left / zoom-in / zoom-out：

<n-transition :show="show" :mode="['slide-left', 'fade']">
	<view class="box"><text>左滑淡入</text></view>
</n-transition>

过渡时长与时间函数

duration 控制过渡时长（ms，0 为即显即隐）；timing-function 可选 ease / linear / ease-in / ease-out / ease-in-out：

<n-transition :show="show" :duration="600" timing-function="linear" mode="zoom-in" />

浮层壳形态

内容默认流式排布。需要全屏壳（引导层、全屏面板）时经 custom-style 设置定位，z-index 控制层级：

<n-transition
	:show="show"
	:z-index="1200"
	custom-style="position:fixed;left:0;top:0;right:0;bottom:0"
	@click="show = false"
/>

生命周期事件

进出场各阶段依次触发，可用于动画联动与统计：

<n-transition
	:show="show"
	@before-enter="log('进入前')"
	@enter="log('进入中')"
	@after-enter="log('进入完成')"
	@before-leave="log('离开前')"
	@leave="log('离开中')"
	@after-leave="log('离开完成')"
/>

API

Props

属性	说明	类型	默认值
show	是否显示过渡内容；受控开关，false 时组件整体不渲染	boolean	false
mode	过渡模式。单个具名模式：fade / fade-up / fade-down / fade-left / fade-right / slide-up / slide-down / slide-left / slide-right / zoom-in / zoom-out；或数组组合正交效果，值域 fade / slide-top / slide-right / slide-bottom / slide-left / zoom-in / zoom-out（如 ["slide-left","fade"]）	string | string[]	"fade"
duration	过渡时长（ms）；0 为即显即隐（无过渡、无卸载缓冲）	number	300
timing-function	过渡时间函数：ease / linear / ease-in / ease-out / ease-in-out	string	"ease-out"
z-index	层级；仅根节点被 custom-style 设为 fixed / absolute 定位时生效	number	0
custom-class	根节点自定义类；类须定义在组件样式表内（页面样式打不进组件），示例见组件样式表的圆角内容 n-transition--rounded	string	—
custom-style	根节点行内样式，如 position:fixed;left:0;top:0;right:0;bottom:0（浮层壳形态）；拼接在内部样式之后，可覆盖层级等内部默认值	string	—

Events

事件名	说明	回调参数
before-enter	进入前触发（show 置 true 同帧，挂载之前）	—
enter	进入中触发（挂载完成、过渡开始前）	—
after-enter	进入后触发（过渡播完；即显模式紧随 enter）	—
before-leave	离开前触发（show 置 false 同帧，隐藏位上链之前）	—
leave	离开中触发（隐藏位生效、过渡开始）	—
after-leave	离开后触发（节点卸载时）	—
click	点击组件时触发（显示态有效；进出场过渡中不发，防误触）	—

Slots

名称	说明
default	过渡内容

实现说明

• 显隐机制：show → enter（挂载，隐藏位）→ 约 50ms 后切显示位（播放过渡）→ 时长播完发 after-enter → false → leave（隐藏位上链）→ 时长 + 40ms 缓冲后卸载发 after-leave；duration=0 即显即隐（无过渡、无缓冲）。挂载后等首帧渲染再上显示位，过渡才会真实播放；与弹层族（n-popup / n-overlay）同一套状态机。
• 过渡属性：transition-property: opacity, transform 由类声明，时长与时间函数行走内联（随 props 动态）。fade / fade-* 系在进出场期挂透明类，纯位移 / 缩放模式透明度恒 1。
• transform 函数集恒定：所有模式的 transform 统一为 translate(x, y) scale(s) 三段形式——显示位 (0px, 0px) scale(1)，隐藏位按模式填偏移；两端函数列表一致，过渡才能逐段平滑插值（含数组组合的复合偏移）。
• 运行中切换 mode：按新隐藏位即时生效；过渡中途切换模式，节点以当前状态向新目标位过渡。
• 形态分工：内容默认流式排布（过渡容器本体）；遮罩层归 n-overlay、弹层面板归 n-popup、本组件专注内容过渡——需要浮层壳形态经 custom-style 自行定位，不设 fixed 默认。
• 浮层壳必须配层级：壳形态（fixed + transform 过渡）是独立合成层，z-index:0 时可能被页面静态内容盖住（H5 端实测）——fixed/absolute 定位时显式传 :z-index（示例见上文浮层壳形态一节）。
• 参考源差异取舍：数组正交组合模式沿用组合值域同义词（slide-top 等价 slide-up、slide-bottom 等价 slide-down），具名 11 模式覆盖常用场景，数组承接自由组合；样式对象式配置不收录（换 custom-style 通道）；动画完成回调不重复收录（after-enter / after-leave 已是同语义拆分）；duration / z-index 收敛 number（字符串冗余形态不收）。