RSuite Animation 动画组件完全指南：Fade / Collapse / Bounce / Slide / Transition 的实现原理与实战配置

前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载Animation 是 rsuite 提供的动画组件集合内置淡入淡出Fade、折叠展开Collapse、弹入弹出Bounce、滑入滑出Slide四种开箱即用的过渡效果并提供一个底层 Transition 组件供开发者自定义任意 CSS 动画。本文以官方文档为主体结合仓库源码系统讲解五个组件的 API 配置、状态机原理、className 切换机制以及自定义动画的完整实战方案帮助你在实际项目中精准控制元素显示与隐藏的过渡细节。Animation 组件总览与引入方式Animation 通过Animation.Transition、Animation.Collapse、Animation.Fade、Animation.Bounce、Animation.Slide五个子组件对外暴露它们统一挂在同一个命名空间下从 src/Animation/index.tsx 中可以看到完整的聚合导出结构export const Animation: AnimationAPI { Transition, Collapse, Fade, Bounce, Slide }; export { Transition, Slide, Collapse, Fade, Bounce }; export default Animation;在业务代码中按需引入即可import { Animation } from rsuite; // 或者单独引入 import { Transition, Slide, Collapse, Fade, Bounce } from rsuite;五个组件的定位如下组件效果典型场景Animation.Fade淡入淡出过渡轻量级的显隐切换Animation.Collapse折叠展开过渡手风琴、折叠面板、表格行展开Animation.Bounce弹入弹出过渡强调型入场/退场动效Animation.Slide滑入滑出过渡抽屉、提示条等从边缘进入的动效Animation.Transition自定义过渡效果任何自定义 CSS 动画的统一载体其中 Fade、Collapse、Bounce、Slide 四者在实现上都是对核心 Transition 组件的封装见 src/Animation/Fade.tsx、src/Animation/Collapse.tsx、src/Animation/Bounce.tsx、src/Animation/Slide.tsx因此理解 Transition 的状态机就掌握了整套动画体系的钥匙。快速上手用in属性控制动画开关所有动画组件都通过in属性必填控制显示状态in{true}触发进入动画in{false}触发退出动画。下面以 Fade 演示代码 为例展示最基础的使用形态import { Animation, Button, Card } from rsuite; const AnimatedPanel React.forwardRef((props, ref) ( Card {...props} ref{ref} shaded bordered{false} w{240} h{120} cwhite bglinear-gradient(45deg, #4CAF50, #2196F3) div Card.HeaderFade Animation/Card.Header Card.BodyThis panel demonstrates a smooth fade transition effect./Card.Body /div /Card )); const App () { const [show, setShow] React.useState(true); const onChange () setShow(!show); return ( div Button appearanceprimary onClick{onChange} Toggle Fade /Button hr / div Animation.Fade in{show} {(props, ref) AnimatedPanel {...props} ref{ref} /} /Animation.Fade /div /div ); };两个值得注意的用法要点children 支持函数形式{(props, ref) ...}动画组件会把合并好的 className 与 ref 通过参数注入到你的自定义节点上。这一形式被所有五个组件支持在 Transition.tsx 的render方法中函数子节点会直接接收childProps与this.childRef普通元素子节点则通过React.cloneElement合并 props、ref 与 className。动画施加在 DOM 节点上传入的ref指向实际 DOM 元素Transition 通过getDOMNode拿到该节点并绑定 transitionend/animationend 事件监听动画类名最终都落在该节点上。核心组件Animation.Transition一套完整的过渡状态机Animation.Transition是所有动画的底层基座它维护了一个五状态枚举定义在 src/Animation/Transition.tsxexport enum STATUS { UNMOUNTED 0, // 已卸载不在 DOM 中 EXITED 1, // 已退出 ENTERING 2, // 进入中 ENTERED 3, // 已进入 EXITING 4 // 退出中 }配合状态机流转Transition 会在不同阶段为子节点挂载对应的 CSS 类名状态挂载的 classNameEXITEDexitedClassNameENTERINGenteringClassNameENTEREDenteredClassNameEXITINGexitingClassName类名切换的实际逻辑位于render()中从 src/Animation/Transition.tsx 可以看到它按当前状态依次选择对应 className并通过classNames与用户传入的className合并let transitionClassName; if (status STATUS.EXITED) { transitionClassName exitedClassName; } else if (status STATUS.ENTERING) { transitionClassName enteringClassName; } else if (status STATUS.ENTERED) { transitionClassName enteredClassName; } else if (status STATUS.EXITING) { transitionClassName exitingClassName; }关键 Props 说明属性名称类型(默认值)描述enteredClassNamestring进入动画过渡后的 classNameenteringClassNamestring进入动画过渡中的 classNameexitedClassNamestring退出动画过渡后的 classNameexitingClassNamestring退出动画过渡中的 classNamein*boolean是否进入触发进入/退出动画的总开关onEnter(node) void开始显示动画前的回调onEntering(node) void显示动画进行中的回调onEntered(node) void显示动画结束后的回调onExit(node) void开始退出动画前的回调onExiting(node) void退出动画进行中的回调onExited(node) void退出动画结束后的回调timeoutnumber(1000)动画最长等待时间Transition 默认 1000ms其余组件默认 300mstransitionAppearboolean初始挂载且in{true}时是否执行入场动画unmountOnExitboolean退出动画结束后是否将组件从 DOM 中卸载动画结束的判定机制Transition 并不依赖 setTimeout 简单估算动画时长而是通过事件监听来精确感知动画是否结束相关逻辑见 src/Animation/Transition.tsx 的onTransitionEnd方法监听节点上的transitionend事件若组件声明了animation属性如 Slide、Bounce则改为监听animationend事件——事件名由 src/Animation/utils.ts 中的getAnimationEnd()动态判定兼容webkitAnimationEnd前缀同时设置timeout兜底定时器防止某些极端情况下事件未触发导致状态卡死通过setNextCallback保证回调只执行一次active标记且仅在事件目标与动画节点一致时才真正响应。此外Transition 构造时对初始状态做了精细推导Transition.tsxin{true}且开启transitionAppear初始为EXITED挂载后立即执行入场动画in{true}未开transitionAppear初始直接为ENTERED不做入场动画in{false}且开启unmountOnExit初始为UNMOUNTED直接不渲染in{false}未开unmountOnExit初始为EXITED渲染但不显示。该行为在 src/Animation/test/Transition.spec.tsx 中有完整测试覆盖包括 enteredClassName/exitedClassName 的正确输出、transitionAppear 触发 onEntered、以及 onEnter/onEntering/onEntered 与 onExit/onExiting/onExited 六组回调的依次调用。内置动画一Fade 淡入淡出Fade 是最轻量的过渡效果源码实现src/Animation/Fade.tsx非常简洁——它只是为 Transition 注入默认类名并把默认 timeout 收敛为 300Transition {...propsWithDefaults} ref{ref} timeout{timeout} className{merge(className, prefix(fade))} enteredClassName{prefix(in)} enteringClassName{prefix(in)} /Props属性名称类型(默认值)描述enteredClassNamestring进入动画过渡后的 classNameenteringClassNamestring进入动画过渡中的 classNameexitedClassNamestring退出动画过渡后的 classNameexitingClassNamestring退出动画过渡中的 classNamein*boolean进入onEnter/onEntering/onEntered(node) void显示前 / 显示中 / 显示后的回调函数onExit/onExiting/onExited(node) void退出前 / 退出中 / 退出后的回调函数timeoutnumber(300)动画过渡延迟时间transitionAppearboolean初始显示时开启过渡效果unmountOnExitboolean退出时卸载组件Fade 默认会挂载rs-anim-fade基类并切换rs-anim-in类其对应的 SCSS 定义在 src/Animation/styles/_fade.scss动画时长由全局 CSS 变量--rs-anim-fade-duration: 0.15s控制见 src/Animation/styles/_variables.scss。内置动画二Collapse 折叠展开Collapse 用于实现高度或宽度的平滑折叠是手风琴类 UI 的核心依赖。与纯 className 方案不同Collapse 在动画的每个阶段用内联样式直接操控尺寸源码见 src/Animation/Collapse.tsxonEnter先把目标尺寸设为0addStyle(elem, dimension, 0)onEntering将尺寸设为scrollHeight/scrollWidth的实际像素值让元素展开到完整高度onEntered将尺寸恢复为auto避免固定高度限制内容变化onExit用getDimensionValue计算当前实际尺寸默认取offsetHeight 上下 margin见defaultGetDimensionValue并固化为像素值onExiting先强制浏览器回流读取offsetHeight再把尺寸设为0触发折叠动画。其中各阶段回调通过createChainedFunction与用户自定义的onEnter等回调链式串联互不覆盖。Props属性名称类型(默认值)描述dimensionheight/width/() height \| width设置折叠尺寸类型默认高度enteredClassNamestring(collapse in)进入动画过渡后的 classNameenteringClassNamestring(collapsing)进入动画过渡中的 classNameexitedClassNamestring(collapse)退出动画过渡后的 classNameexitingClassNamestring(collapsing)退出动画过渡中的 classNamegetDimensionValue(dimension, elem) number自定义折叠展开的尺寸值in*boolean进入onEnter等六组回调(node) void与 Transition 语义一致的过渡回调rolestringHTML role 属性timeoutnumber(300)动画过渡延迟时间transitionAppearboolean初始显示时开启过渡效果unmountOnExitboolean退出时卸载组件横向折叠用法dimensionwidth即可把折叠方向切换为水平方向参考 Collapse 演示代码HStack spacing{16} alignItemsflex-start VStack w{240} TextVertical Collapse/Text Animation.Collapse in{show} {(props, ref) AnimatedPanel {...props} ref{ref} /} /Animation.Collapse /VStack VStack w{240} TextHorizontal Collapse/Text Animation.Collapse in{show} dimensionwidth {(props, ref) AnimatedPanel {...props} ref{ref} /} /Animation.Collapse /VStack /HStack从 src/Animation/Collapse.tsx 可以看到横向折叠时组件会自动追加rs-anim-collapse-horizontal类便于针对宽度折叠做样式微调。折叠状态对应的 CSS 定义在 src/Animation/styles/_collapse.scss折叠态默认display: none.rs-anim-collapse展开态.rs-anim-in恢复display: block同时兼容tr、tbody等表格元素的display: table-row / table-row-group过渡中的.rs-anim-collapsing则固定overflow: hidden并配合height/width的 transition时长取 CSS 变量--rs-anim-collapse-duration: 0.35s。内置动画三Bounce 弹入弹出Bounce 提供带弹性的入场退场效果实现同样是对 Transition 的封装src/Animation/Bounce.tsx但会额外开启animation事件监听Transition {...propsWithDefaults} ref{ref} animation timeout{timeout} enteringClassName{prefix(bounce-in)} enteredClassName{prefix(bounce-in)} exitingClassName{prefix(bounce-out)} exitedClassName{prefix(bounce-out)} /Props属性名称类型(默认值)描述enteredClassNamestring进入动画过渡后的 classNameenteringClassNamestring进入动画过渡中的 classNameexitedClassNamestring退出动画过渡后的 classNameexitingClassNamestring退出动画过渡中的 classNamein*boolean进入onEnter/onEntering/onEntered(node) void显示前 / 显示中 / 显示后的回调函数onExit/onExiting/onExited(node) void退出前 / 退出中 / 退出后的回调函数timeoutnumber(300)动画过渡延迟时间transitionAppearboolean初始显示时开启过渡效果unmountOnExitboolean退出时卸载组件Bounce 使用独立的bounce-in/bounce-out动画样式位于 src/Animation/styles/_bounce.scss。内置动画四Slide 滑入滑出Slide 支持从四个方向滑入滑出默认从右侧滑入src/Animation/Slide.tsxconst enterClassName prefix(slide-in, placement); const exitClassName prefix(slide-out, placement); Transition {...propsWithDefaults} ref{ref} animation timeout{timeout} enteringClassName{enterClassName} enteredClassName{enterClassName} exitingClassName{exitClassName} exitedClassName{exitClassName} /Props属性名称类型(默认值)描述placementtop \| right \| bottom \| left(right)动画进入 / 退出的方位enteredClassNamestring进入动画过渡后的 classNameenteringClassNamestring进入动画过渡中的 classNameexitedClassNamestring退出动画过渡后的 classNameexitingClassNamestring退出动画过渡中的 classNamein*boolean进入onEnter等六组回调(node) void与 Transition 语义一致的过渡回调timeoutnumber(300)动画过渡延迟时间transitionAppearboolean初始显示时开启过渡效果unmountOnExitboolean退出时卸载组件演示代码slide.md展示了通过切换placement控制滑动方向的典型用法ButtonToolbar Button appearanceprimary onClick{() onChange(left)}Slide Left/Button Button appearanceprimary onClick{() onChange(right)}Slide Right/Button Button appearanceprimary onClick{() onChange(top)}Slide Top/Button Button appearanceprimary onClick{() onChange(bottom)}Slide Bottom/Button /ButtonToolbar hr / div Animation.Slide in{show} placement{placement} {(props, ref) AnimatedPanel {...props} ref{ref} /} /Animation.Slide /divSlide 的 SCSS 实现src/Animation/styles/_slide.scss值得一提它针对rs-anim-right、rs-anim-left、rs-anim-top、rs-anim-bottom分别调用slideIn*/slideOut*动画并且在 RTL[dirrtl]环境下自动把 left/right 的滑动方向互换保证阿拉伯语等从右向左布局下的体验一致。自定义过渡效果用Animation.Transition组合任意动画当内置四类动画无法满足需求时直接使用Animation.Transition搭配自定义 CSS 动画即可。官方文档给出了完整的 自定义过渡演示核心思路是给四个过渡类名各自传入自定义 className然后自己编写对应的 CSS keyframes。import { Animation, Button, ButtonToolbar, Card } from rsuite; const AnimatedPanel React.forwardRef(({ ...props }, ref) ( Card {...props} ref{ref} shaded bordered{false} w{240} h{120} cwhite bglinear-gradient(45deg, #4CAF50, #2196F3) div Card.HeaderCustom Transition/Card.Header Card.BodyClick different buttons to see various animation effects!/Card.Body /div /Card )); const App () { const [show, setShow] React.useState(true); const [effect, setEffect] React.useState(zoom); const onChange newEffect { setShow(!show); setEffect(newEffect); }; return ( div ButtonToolbar Button appearanceprimary onClick{() onChange(zoom)}Zoom/Button Button appearanceprimary onClick{() onChange(flip)}Flip/Button Button appearanceprimary onClick{() onChange(rotate)}Rotate/Button Button appearanceprimary onClick{() onChange(bounce)}Bounce/Button /ButtonToolbar hr / div Animation.Transition exitedClassName{custom-exited custom-${effect}-exited} exitingClassName{custom-exiting custom-${effect}-exiting} enteredClassName{custom-entered custom-${effect}-entered} enteringClassName{custom-entering custom-${effect}-entering} in{show} {(props, ref) AnimatedPanel {...props} ref{ref} /} /Animation.Transition /div /div ); };对应地为进入/退出的中间态统一声明动画属性再为每种效果定义不同的animation-name与 keyframes.custom-exiting, .custom-entering { animation: 0.5s cubic-bezier(0.4, 0, 0.2, 1); animation-fill-mode: forwards; } /* Zoom 效果缩放 透明度 */ .custom-zoom-exiting { animation-name: zoomOut; } .custom-zoom-entering { animation-name: zoomIn; } keyframes zoomIn { from { opacity: 0; transform: scale3d(0.3, 0.3, 0.3); } 50% { opacity: 1; } } keyframes zoomOut { from { opacity: 1; } 50% { opacity: 0; transform: scale3d(0.3, 0.3, 0.3); } to { opacity: 0; } } /* Flip 效果3D 翻转 */ .custom-flip-exiting { animation-name: flipOut; } .custom-flip-entering { animation-name: flipIn; } keyframes flipIn { from { opacity: 0; transform: perspective(400px) rotate3d(1, 0, 0, 90deg); } 40% { transform: perspective(400px) rotate3d(1, 0, 0, -20deg); } 60% { opacity: 1; transform: perspective(400px) rotate3d(1, 0, 0, 10deg); } 80% { transform: perspective(400px) rotate3d(1, 0, 0, -5deg); } to { transform: perspective(400px); } } keyframes flipOut { from { transform: perspective(400px); } 30% { opacity: 1; transform: perspective(400px) rotate3d(1, 0, 0, -20deg); } to { opacity: 0; transform: perspective(400px) rotate3d(1, 0, 0, 90deg); } } /* Rotate 效果旋转 缩放 */ .custom-rotate-exiting { animation-name: rotateOut; } .custom-rotate-entering { animation-name: rotateIn; } keyframes rotateIn { from { opacity: 0; transform: rotate3d(0, 0, 1, -180deg) scale(0.3); } 50% { opacity: 1; } } keyframes rotateOut { from { opacity: 1; } to { opacity: 0; transform: rotate3d(0, 0, 1, 180deg) scale(0.3); } } /* Bounce 效果弹性缩放 */ .custom-bounce-exiting { animation-name: bounceOut; } .custom-bounce-entering { animation-name: bounceIn; } keyframes bounceIn { from { opacity: 0; transform: scale3d(0.3, 0.3, 0.3); } 20% { transform: scale3d(1.1, 1.1, 1.1); } 40% { transform: scale3d(0.9, 0.9, 0.9); } 60% { opacity: 1; transform: scale3d(1.03, 1.03, 1.03); } 80% { transform: scale3d(0.97, 0.97, 0.97); } to { opacity: 1; transform: scale3d(1, 1, 1); } } keyframes bounceOut { 20% { transform: scale3d(0.9, 0.9, 0.9); } 50%, 55% { opacity: 1; transform: scale3d(1.1, 1.1, 1.1); } to { opacity: 0; transform: scale3d(0.3, 0.3, 0.3); } } /* 终态兜底 */ .custom-entered { opacity: 1; } .custom-exited { opacity: 0; }这里的命名规则与状态机完全对应custom-exiting/custom-entering用于定义过渡通用属性时长、缓动、fill-modecustom-${effect}-exiting/custom-${effect}-entering用于区分具体动画效果.custom-entered/.custom-exited作为终态样式兜底。由于 Transition 默认以animationend事件作为完成信号自定义动画务必保证元素上确实存在 animation 声明否则状态机只能依赖timeout默认 1000ms兜底收尾。进阶实践建议transitionAppear控制首屏动画页面初始化时若希望元素「从出现的那一刻就播放入场动画」需显式开启transitionAppear默认行为是首帧直接以最终态渲染。unmountOnExit与性能对频繁显隐且体积较大的内容建议开启unmountOnExit让退出动画结束后从 DOM 中移除节点避免无效节点长期占用对需要保留下落状态如表单值、滚动位置的场景则保持关闭。timeout与动画时长的匹配Transition 的默认timeout为 1000msFade/Collapse/Bounce/Slide 的默认值为 300ms。自定义动画时若 keyframes 时长超过 timeout建议同步调整timeout属性防止回调提前触发导致状态切换过早。回调的链式组合Collapse 等组件内部通过createChainedFunction将内置的尺寸操控逻辑与用户传入的onEnter等回调串联因此你传入的回调一定会执行可以放心在onEntered/onExited中做数据加载、埋点等副作用操作。无障碍与 RTLCollapse 支持透传role属性Slide 在 RTL 环境下会自动镜像滑动方向见 src/Animation/styles/_slide.scss无需额外适配。相关资源组件入口与类型导出src/Animation/index.tsx核心状态机实现src/Animation/Transition.tsx折叠动画实现src/Animation/Collapse.tsx动画样式入口src/Animation/styles/index.scss动画时长变量src/Animation/styles/_variables.scss行为验证测试src/Animation/test/Transition.spec.tsx、src/Animation/test/Collapse.spec.tsx各效果完整演示代码fade.md、collapse.md、slide.md、bounce.md、transition.md赞分享前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载相关推荐rsuite Animation 组件实战指南Fade、Collapse、Bounce、Slide 与自定义 Transition 动画rsuite Animation 组件实战指南Fade、Collapse、Bounce、Slide 与自定义 Transition 动画 rsuite 的 A前端UI组件Element Plus 内置过渡动画完全指南Fade、Zoom 与 Collapse Transition 的原理与实战Element Plus 内置过渡动画完全指南Fade、Zoom 与 Collapse Transition 的原理与实战 Element Plus 在官方文前端UI组件CANN数学算子BesselI0e函数BesselI0e 产品支持情况 | 产品 | 是否支持 | |: | : : | | term Ascend 950PR/Ascend 950DT/ter算子库人工智能CANN上一篇终极指南10个提升城市天际线体验的必备模组 ✨下一篇Expo expo/router-server 深度解析SSR、Streaming 与静态站点生成的底层引擎演进全记录创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考