Ant Design 按钮波纹效果Wave原理与自定义实现从源码到 showEffect 实战【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design本文围绕 Ant Design Button 组件的波纹Wave效果展开。默认波纹是为点击操作提供的视觉反馈而 Ant Design 允许通过ConfigProvider的wave配置项完全接管这一行为关闭波纹、更换触发事件、甚至用自定义的showEffect回调写出内嵌光斑或抖动等替代反馈。读完本文你可以完整理解波纹从事件监听到 DOM 卸载的整条调用链并能够基于 官方示例源码 为自己的组件实现任意交互反馈。波纹效果在哪里生效波纹并非 Button 独有的能力而是 Ant Design 内置的一个通用交互反馈机制。以 Button 为例Button 主实现 中用Wave componentButton disabled{innerLoading}包裹按钮内容即把波纹能力注入到了按钮渲染链路中Tag、Checkbox、Radio、Switch、Steps 等组件同样会挂接Wavecomponent的可选类型定义在 interface.ts 中为Tag | Button | Checkbox | Radio | Switch | Steps。波纹的全部实现集中在 components/_util/wave 目录核心文件分工如下文件职责index.tsWave组件监听目标节点事件决定是否触发波纹useWave.ts组装触发逻辑读取wave配置、选择默认或自定义showEffectWaveEffect.tsx默认波纹效果的渲染与自清理util.ts波纹颜色提取从目标元素计算样式中取色style.ts波纹 CSSbox-shadow扩散动画与wave-quick加速档位interface.tsShowWaveEffect类型与TARGET_CLS等常量触发链路从 click 到波纹出现事件监听与过滤Wave 组件 在useEffect中给目标元素以捕获阶段第三个参数true挂载事件监听。事件类型默认是click但可以被wave.triggerType改写合法取值来自内部映射表const TRIGGER_TYPE_TO_EVENT_MAP { click: click, mousedown: mousedown, mouseup: mouseup, pointerdown: pointerdown, pointerup: pointerup, } as const;监听到的每次事件都会先经过一层过滤以下情况不会触发波纹事件目标不可见isVisible判定节点带disabled属性、HTMLdisabled属性或aria-disabledtrue类名包含disabled但排除disabled:这类纯工具类写法节点带有退出动画类类名含-leave。此外Wave组件的disabled属性本身也会直接短路例如 Button 处于 loading 时波纹被禁用。按帧合并debounceuseWave 返回的不是原始回调而是showDebounceWave它先raf.cancel上一帧的调度再用requestAnimationFrame把本帧内的多次触发合并为一次。这避免了快速连点时生成大量波纹 DOM。组件卸载时会取消未执行的 RAF防止陈旧回调。目标节点选择触发时会先在目标元素里查找.ant-wave-targetTARGET_CLS见 interface.tsconst targetNode node.querySelectorHTMLElement(.${TARGET_CLS}) || node;也就是说组件可以在内部指定一个更精确的波纹锚点找不到才回退到整个组件根节点。默认或自定义 showEffectuseWave 的核心逻辑 可以概括为一行const { showEffect } wave || {}; (showEffect || showWaveEffect)(targetNode, { className, token, component, event, hashId, colorSource, });若用户在ConfigProvider里提供了wave.showEffect则完全替代默认实现showWaveEffect并拿到组件级token、hashId、事件对象等上下文——这是自定义反馈的官方扩展点下文结合示例代码展开。默认波纹是怎么画出来的showWaveEffect 的做法非常直接在目标节点内插入一个绝对定位的 holder div然后把WaveEffect组件直接渲染进去render(WaveEffect .../, holder)。WaveEffect组件内部完成三件事同步几何信息syncPos读取目标的getComputedStyle取出宽高、四角圆角并根据position是否为static决定偏移方式——static 元素用offsetLeft/offsetTop否则用负的borderLeftWidth/borderTopWidth抵消边框。同时通过ResizeObserver持续跟踪目标尺寸变化保证波纹始终贴合。提取波纹颜色getTargetWaveColor若未指定colorSource会按borderTopColor → borderColor → backgroundColor的顺序取第一个“有效色”isValidWaveColor会排除白色、transparent以及各种透明写法alpha 为 0 的 rgba / hex。指定colorSource时则直接从对应 CSS 属性取色颜色最终以 CSS 变量--ant-wave-color写入波纹元素并映射到box-shadow的currentcolor。播放动画波纹是一个box-shadow: 0 0 0 0 currentcolor向外扩到0 0 0 6px再淡出的过程初始opacity: 0.2动画曲线与时长全部来自全局 motion tokenmotionEaseOutCirc、motionDurationSlow等见 style.ts。动画通过rc-component/motion的CSSMotion驱动onAppearEnd中检测到deadline或opacity属性过渡结束后会unmount并移除整个 holder——波纹的 DOM 是自清理的不会残留在页面里。另外有两个细节值得注意小尺寸加速当component为Checkbox或Radio且目标带ant-wave-target类时波纹附加wave-quick类把 0.4s/2s 的过渡缩短为motionDurationSlow档的快进节奏避免小控件上的波纹显得迟缓未选中 Checkbox 不播波纹showWaveEffect入口处直接跳过checked为 false 的 CheckboxWaveEffect.tsx。通过 ConfigProvider 配置 waveConfigProvider的wave属性类型可用GetPropConfigProviderProps, wave推导支持三类配置配置类型作用disabledboolean全局关闭波纹useWave中wave?.disabled直接短路triggerTypeclick \| mousedown \| mouseup \| pointerdown \| pointerup更换触发事件映射逻辑见上文TRIGGER_TYPE_TO_EVENT_MAPshowEffectShowWaveEffect完全自定义波纹表现替代默认showWaveEffectWave组件自身还接受一个colorSource属性color | backgroundColor | borderColor | null定义见 WaveProps用于指定波纹取色来源它会随info.colorSource一并传入showEffect。自定义 showEffect 实战内嵌光斑与抖动效果官方 demo 源码 演示了两个典型自定义效果两者都只作用于component Button是学习showEffect签名的最佳范本。内嵌光斑Inset思路在按钮内创建一个绝对定位的 holder用inset: -borderWidth抵消边框、overflow: hidden裁剪、pointer-events: none保证不影响交互在鼠标落点位置生成一个小圆点下一帧把圆点放大到 200px 并淡出transitionend时移除 holderconst showInsetEffect: WaveConfig[showEffect] (node, { event, component }) { if (component ! Button) { return; } const holder createHolder(node); // 绝对定位、inset 为负边框宽、zIndex 999 const rect holder.getBoundingClientRect(); const left event.clientX - rect.left; const top event.clientY - rect.top; const dot createDot(holder, rgba(255, 255, 255, 0.65), left, top); // Motion requestAnimationFrame(() { dot.ontransitionend () { holder.remove(); }; dot.style.width 200px; dot.style.height 200px; dot.style.opacity 0; }); };这里体现了showEffect的核心自由度event.clientX/clientY让反馈可以跟随精确的鼠标落点这是默认波纹从元素边界整体扩散做不到的。抖动效果Shake用关键帧序列[0, -15, 15, -5, 5, 0]模拟一次“拒绝”式的水平抖动每 10 步插值一次旋转角通过requestAnimationFrame循环写node.style.transformconst showShakeEffect: WaveConfig[showEffect] (node, { component }) { if (component ! Button) { return; } const seq [0, -15, 15, -5, 5, 0]; const itv 10; let steps 0; const loop () { cancelAnimationFrame((node as any).effectTimeout); (node as any).effectTimeout requestAnimationFrame(() { const currentStep Math.floor(steps / itv); const current seq[currentStep]; const next seq[currentStep 1]; if (next undefined || next null) { node.style.transform ; node.style.transition ; return; } const angle current ((next - current) / itv) * (steps % itv); node.style.transform rotate(${angle}deg); node.style.transition none; steps 1; loop(); }); }; loop(); };组织方式demo 用一个Wrapper组件为每枚按钮套上独立的ConfigProvider从而在同一屏上并行展示四种行为——disabled、默认波纹、Inset、Shake以及通过ant-design/happy-work-theme包的HappyProvider实现的动态波纹该主题是 Ant Design 官方配套的主题包内部正是利用wave.showEffect机制注入动画const Wrapper: React.FCWaveConfig { name: string } ({ name, ...wave }) ( ConfigProvider wave{wave} Button typeprimary{name}/Button /ConfigProvider );Flex gaplarge wrap Wrapper nameDisabled disabled / Wrapper nameDefault / Wrapper nameInset showEffect{showInsetEffect} / Wrapper nameShake showEffect{showShakeEffect} / HappyProvider Button typeprimaryHappy Work/Button /HappyProvider /Flex实践要点与边界结合源码可以归纳出使用wave配置时的几条实用结论showEffect是全量替换而非叠加一旦传入默认波纹不会再出现想让多种组件呈现不同反馈就按component字段在回调里分支处理。自行负责 DOM 生命周期默认实现会自动清理 holder自定义实现需自己保证动画结束后移除节点demo 中分别用ontransitionend和关键帧序列结束来回收否则会留下残留元素。触发时机可控triggerType支持pointerdown/pointerup适合需要“按下即反馈”或仅“松开成功才反馈”的交互设计配合useWave的 RAF 合并高频触发也不会产生波纹堆积。颜色来源可调默认取色链是borderTopColor → borderColor → backgroundColor且过滤白底与透明色如果你的组件依赖color文字色做反馈可用Wave的colorSource或在showEffect里自行getComputedStyle。禁用态天然安全disabled属性、aria-disabled、不可见节点与 loading 中的 Button 都不会触发波纹自定义实现若依赖event也应自行判断目标可交互性。完整源码可参考 wave 工具目录、官方示例 及其说明文档 wave.md测试用例位于 button 的tests目录可进一步验证波纹相关行为。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考