ScrollToTop功能添加jQuery .animate后出现异常行为求助

问题背景 #

实现Scroll To Top功能时，仅添加淡入淡出效果脚本运行正常：

正常代码示例 #

JavaScript

jQuery(document).ready(function(){
    jQuery("#top").hide();
    jQuery(function toTop() {
        jQuery(window).scroll(function () {
            if (jQuery(this).scrollTop() > 100) {
                jQuery('#top').fadeIn();
            } else {
                jQuery('#top').fadeOut();
            }
        });

        jQuery('#top').click(function () {
            jQuery('body,html').animate({
                scrollTop: 0
            }, 1200);
            return false;
        });
    });         
});        

CSS

div.wrapper {
  width: 100%;
  height: 2500px;
}
  
#top {
    background-image:url("https://blindspotetc.com/wp-content/uploads/2022/11/icon-up.png");
    background-repeat:no-repeat;
    position: fixed;
    width: 50px;
    height: 50px;
    bottom: 5%;
    cursor: pointer;
    opacity: 1;
    z-index: 99;
}

HTML

<script src="https://code.jquery.com/jquery-3.6.4.js"></script>
<div class="wrapper">
<p>Scroll down to test.</p>
<a onclick="toTop()" id="top" class="back-to-top" title="Go to top"></a>
</div>

但添加jQuery animate方法后，功能出现异常：

• 按钮需滚动到div底部两次才会显示并执行动画
• 向上滚动时无法按预期返回原位
• 第三次及之后滚动时按钮不再显示

异常代码示例 #

JavaScript

jQuery(document).ready(function(){
    jQuery("#top").hide();
    jQuery(function toTop() {
        jQuery(window).scroll(function () {
            if (jQuery(this).scrollTop() > 200) {
                jQuery('#top').fadeIn().animate({left:'90%'});
            } else {
                jQuery('#top').animate({left:'10%'}).fadeOut();
            }
        });

        jQuery('#top').click(function () {
            jQuery('body,html').animate({
                scrollTop: 0
            }, 1200);
            return false;
        });
    });         
});

CSS（与正常代码一致，未设置初始left值）

div.wrapper {
  width: 100%;
  height: 2500px;
}
  
#top {
    background-image:url("https://blindspotetc.com/wp-content/uploads/2022/11/icon-up.png");
    background-repeat:no-repeat;
    position: fixed;
    width: 50px;
    height: 50px;
    bottom: 5%;
    cursor: pointer;
    opacity: 1;
    z-index: 99;
}

HTML（与正常代码一致）

<script src="https://code.jquery.com/jquery-3.6.4.js"></script>
<div class="wrapper">
<p>Scroll down to test.</p>
<a onclick="toTop()" id="top" class="back-to-top" title="Go to top"></a>
</div>

问题原因 #

1. 动画队列堆积：滚动事件会被频繁触发，每次触发都会给按钮添加新的animate动画，导致动画队列积压，之前的动画未执行完就被新动画叠加，最终表现为延迟、位置异常。
2. 初始位置未定义：CSS中#top元素没有设置初始left值，animate的目标值缺乏基准，导致动画起始位置混乱。
3. 冗余的嵌套ready回调与全局调用冲突：jQuery(function toTop())是重复的ready回调，且toTop函数作用域在ready内部，HTML中的onclick="toTop()"无法访问该函数，点击时会报错，进一步干扰逻辑。

解决办法 #

修正后的代码 #

JavaScript

jQuery(document).ready(function(){
    // 初始化按钮状态，设置初始位置
    const $topBtn = jQuery('#top').hide().css('left', '10%');

    jQuery(window).scroll(function () {
        if (jQuery(this).scrollTop() > 200) {
            // 清除之前的动画队列，立即完成当前动画，再执行新动画
            $topBtn.stop(true, true).fadeIn().animate({left:'90%'});
        } else {
            $topBtn.stop(true, true).animate({left:'10%'}, function(){
                // 动画完成后再淡出，避免位置未到位就隐藏
                jQuery(this).fadeOut();
            });
        }
    });

    $topBtn.click(function () {
        jQuery('body,html').animate({
            scrollTop: 0
        }, 1200);
        return false;
    });
});

CSS

div.wrapper {
  width: 100%;
  height: 2500px;
}
  
#top {
    background-image:url("https://blindspotetc.com/wp-content/uploads/2022/11/icon-up.png");
    background-repeat:no-repeat;
    position: fixed;
    width: 50px;
    height: 50px;
    bottom: 5%;
    cursor: pointer;
    opacity: 1;
    z-index: 99;
    /* 设置初始left值 */
    left: 10%;
}

HTML（移除无效的onclick调用）

<script src="https://code.jquery.com/jquery-3.6.4.js"></script>
<div class="wrapper">
<p>Scroll down to test.</p>
<a id="top" class="back-to-top" title="Go to top"></a>
</div>

关键优化点 #

• 使用.stop(true, true)：第一个true清空动画队列，第二个true让当前动画立即完成，避免队列堆积。
• 定义初始left值：在CSS中设置按钮初始位置，确保动画有明确的起始点。
• 移除冗余嵌套：去掉重复的ready回调，避免作用域问题；删除HTML中无效的onclick调用。
• 调整动画顺序：在返回左侧的动画完成后再执行淡出，保证位置到位后再隐藏。

内容的提问来源于stack exchange，提问作者5150 Design