README

允许轻松实现页面内链接的平滑滚动。

注意：此插件的2.0+版本需要jQuery 1.7或更高版本。

下载

使用npm

npm install jquery-smooth-scroll

传统方式

在浏览器中访问以下URL并复制/粘贴代码到自己的文件中： https://raw.githubusercontent.com/kswedberg/jquery-smooth-scroll/master/jquery.smooth-scroll.js

演示

您可以在kswedberg.github.io/jquery-smooth-scroll/demo/尝试一个简单的演示。

功能

$.fn.smoothScroll

使用方法：$('a').smoothScroll();
如果您想指定一个包含元素： $('#container a').smoothScroll();
如果链接位于包含元素内，则排除链接：$('#container a').smoothScroll({excludeWithin: ['.container2']});
如果链接符合某些条件，则排除链接：$('a').smoothScroll({exclude: ['.rough','#chunky']});
调整滚动停止的位置：$('.backtotop').smoothScroll({offset: -100});
添加在滚动开始前触发的回调函数：$('a').smoothScroll({beforeScroll: function() { alert('准备出发！'); }});
添加在滚动完成后触发的回调函数：$('a').smoothScroll({afterScroll: function() { alert('我们做到了！'); }});
通过使用hashchange事件监听器添加返回按钮支持。您还可以包括像Ben Alman的BBQ这样的历史管理插件以支持旧浏览器（IE < 8），但您需要jQuery 1.8或更早版本。请参阅demo/hashchange.html或demo/bbq.html中的实现示例。

选项

以下选项（显示其默认值）可用于$.fn.smoothScroll和$.smoothScroll

{
  offset: 0,

  // one of 'top' or 'left'
  direction: 'top',

  // only use if you want to override default behavior or if using $.smoothScroll
  scrollTarget: null,

  // automatically focus the target element after scrolling to it (see readme for details)
  autoFocus: false,

  // string to use as selector for event delegation
  delegateSelector: null,

  // fn(opts) function to be called before scrolling occurs.
  // `this` is the element(s) being scrolled
  beforeScroll: function() {},

  // fn(opts) function to be called after scrolling occurs.
  // `this` is the triggering element
  afterScroll: function() {},

  // easing name. jQuery comes with "swing" and "linear." For others, you'll need an easing plugin
  // from jQuery UI or elsewhere
  easing: 'swing',

  // speed can be a number or 'auto'
  // if 'auto', the speed will be calculated based on the formula:
  // (current scroll position - target scroll position) / autoCoefficient
  speed: 400,

  // autoCoefficent: Only used when speed set to "auto".
  // The higher this number, the faster the scroll speed
  autoCoefficient: 2,

  // $.fn.smoothScroll only: whether to prevent the default click action
  preventDefault: true

}

$.fn.smoothScroll的选项对象可以接受两个额外的属性：exclude和excludeWithin。这两个的值都是一个选择器、DOM元素或jQuery对象的数组。两者的默认值都是空数组。

在初始调用后设置选项

如果您需要在调用.smoothScroll()之后更改任何选项，可以通过传递第一个参数为字符串"options"以及第二个参数为选项对象来实现。

$.smoothScroll

实用方法不需要选择器：$.smoothScroll()
可以用于滚动任何元素（不仅仅是document.documentElement / document.body）

它不会自动触发，因此您需要将其绑定到其他用户交互。例如

$('button.scrollsomething').on('click', function() {
  $.smoothScroll({
    scrollElement: $('div.scrollme'),
    scrollTarget: '#findme'
  });
  return false;
});

$.smoothScroll方法可以接受一个或两个参数。
- 如果第一个参数是数字或“相对字符串”，则文档将滚动到该位置。如果它是一个选项对象，则这些选项将确定文档（或其他元素）如何滚动。
- 如果提供数字或“相对字符串”作为第二个参数，它将覆盖可能已为scrollTarget选项设置的任何内容。
- 相对字符串的语法（自2.1版本引入）看起来像+=100px或"-=50px"（下面有示例）。

附加选项

以下选项，除了上面为 $.fn.smoothScroll 列出的选项外，还适用于 $.smoothScroll

{
  // The jQuery set of elements you wish to scroll.
  //  if null (default), $('html, body').firstScrollable() is used.
  scrollElement: null
}

$.fn.scrollable

选择匹配的、可滚动的元素。就像一个DOM遍历方法，如 .find() 或 .next()。
生成的jQuery集合可能包含 零个、一个或多个 元素。

$.fn.firstScrollable

选择第一个匹配的、可滚动的元素。就像一个DOM遍历方法，如 .find() 或 .next()。
生成的jQuery集合可能包含 零个或一个 元素。
此方法由插件内部使用，以确定用于“文档”滚动的元素：$('html, body').firstScrollable().animate({scrollTop: someNumber}, someSpeed)

示例

一次滚动一个“页面”（v2.1+）

从平滑滚动版本2.1开始，您可以使用“相对字符串”语法来滚动元素或文档相对于当前位置的一定数量的像素。以下代码在用户点击““.pagedown”按钮时将文档每次向下滚动一个页面

$('button.pagedown').on('click', function() {
  $.smoothScroll('+=' + $(window).height());
});

页面加载时的平滑滚动

如果要在页面加载时滚动到元素，请在body末尾的脚本中使用 $.smoothScroll()，或使用 $(document).ready()。为了防止浏览器自动滚动到元素，页面1上的链接需要包含一个不匹配页面2上元素id的片段标识符。为了确保没有JavaScript的用户也能到达同一元素，您应该使用JavaScript修改页面1上的链接的hash。然后在您调用 $.smoothScroll() 时，页面2上的脚本将修改它为正确的值。

例如，假设您想平滑滚动到 <div id="scrolltome"></div> 在 page-2.html 上。对于 page-1.html，您的脚本可能如下所示

$('a[href="page-2.html#scrolltome"]').attr('href', function() {
  var hrefParts = this.href.split(/#/);
  hrefParts[1] = 'smoothScroll' + hrefParts[1];
  return hrefParts.join('#');
});

然后对于 page-2.html，您的脚本将这样做

// Call $.smoothScroll if location.hash starts with "#smoothScroll"
var reSmooth = /^#smoothScroll/;
var id;
if (reSmooth.test(location.hash)) {
  // Strip the "#smoothScroll" part off (and put "#" back on the beginning)
  id = '#' + location.hash.replace(reSmooth, '');
  $.smoothScroll({scrollTarget: id});
}

滚动到元素后聚焦元素。

想象一下，您在同一页面上有一个链接到表单。当用户点击链接时，您希望用户能够开始与该表单交互。

从 平滑滚动版本2.2 开始，如果将 autoFocus 选项设置为 true，插件将自动聚焦元素。
在未来，版本3.x及以后的版本将默认将 autoFocus 设置为 true。
如果您正在使用低级 $.smoothScroll 方法，autoFocus 仅在您还提供了 scrollTarget 选项的值时才会工作。
在版本2.2之前，您可以使用 afterScroll 回调函数。以下是一个示例，在滚动到表单后聚焦表单中的第一个输入框

$('a.example').smoothScroll({
  afterScroll: function(options) {
    $(options.scrollTarget).find('input')[0].focus();
  }
});

出于可访问性的原因，您可能需要聚焦您滚动到的任何元素，即使它不是一个原生的可聚焦元素。为了做到这一点，您可以为目标元素添加一个 tabIndex 属性（这同样适用于版本2.2之前的版本）

$('div.example').smoothScroll({
  afterScroll: function(options) {
    var $tgt = $(options.scrollTarget);
    $tgt[0].focus();

    if (!$tgt.is(document.activeElement)) {
      $tgt.attr('tabIndex', '-1');
      $tgt[0].focus();
    }
  }
});

注意

为了确定滚动页面的位置，$.fn.smoothScroll 方法会寻找一个具有 id 属性的元素，该属性与 <a> 元素的hash匹配。它不会查看元素的 name 属性。如果您希望点击的链接滚动到“命名锚点”（例如，<a name="foo">），则需要使用 $.smoothScroll 方法。
该插件的 $.fn.smoothScroll 和 $.smoothScroll 方法使用 $.fn.firstScrollable DOM遍历方法（该方法也由该插件定义）来确定哪个元素是可滚动的。如果没有可滚动的元素，这些方法将返回一个包含空数组的jQuery对象，就像jQuery的所有其他DOM遍历方法一样。因此，任何进一步的链式方法都将对没有元素调用（在大多数情况下，这意味着不会发生任何事情）。

贡献

感谢！在提交拉取请求之前，请在处理这个仓库时考虑以下事项

对于代码更改，请修改“源”文件：src/jquery.smooth-scroll.js。
样式约定记录在jshint grunt文件选项和.jscsrc文件中。为确保您的修改符合要求，请在命令行中运行grunt lint。
如果可能的话，请使用Tim Pope的git提交信息风格。多个提交将在拉取请求中合并为一个提交。我可能会调整信息以提高清晰度、风格或语法。我使用--author标志手动提交所有合并的PR，以确保适当的作者身份（您的）得到维护。

holisticnetworking / jquery-smooth-scroll

维护者

详细信息