同步更新官网文档:v3.1 2017/8/17

instantclick 中文文档

简介

instantclick.js 是一种ajax无刷新和预加载页面的技术,对于普通博客程序,有着明显的加速作用。(instantclick.js ≈ pjax + 预加载页面)而且,使用方法也十分的简单。在github截止目前,已经由4447个star了,非常可观。

但是官方文档纯英文,可能阅读上有点障碍,所以,在此,翻译一下大部分的官方文档内容,方便新手快速使用。大部分采用直译方式,需要注意的地方 用小括号注释起来。(尽管如此,instantclick.js 仍然有一些bug亟待解决,如果你可以忽略缺点吧,我们一起开始吧!)

目录

初级阶段
  • 开始使用
  • instantclick 工作原理
  • 预加载页面
  • 黑名单规则
  • 事件和脚本的重新加载
进阶阶段
  • 跟踪页面内容的变化
  • 自定义加载条

初级阶段

开始使用

下载instantclick.js

最新的发布版本是2014/12/25发布的V3.1.0 (虽然github一直有更新,但是并没有发布新的版本~)

压缩版本2.7kb

开发版本21kb

其他的下载方式

  • github上面的最新开发版本
  • 通过bower(一种前端开发工具) : bower install instantclick

初始化instantclick

把 instantclick.js 和 初始化代码 放在你的页面的结束之前(</body>标签结束之前)

...
<script src="instantclick.min.js" data-no-instant></script>
<script data-no-instant>InstantClick.init();</script>
</body>
</html>

现在instantclick 已经成功在你的网页上面生效。阅读下面的文章以便更熟练的使用instantclick。

  • instantclick 工作原理:将会让你建立正确的模型以便更好的理解instantclick的机制
  • 预加载页面:将会向你展示不同的预加载页面的方法
  • 黑名单规则:因为有些链接你不想预加载
  • 事件和脚本的重新加载:将会帮助你使instantclick更好的配合你的网页中的JavaScript。

instantclick不总是“即插即用”(不是通过两行代码就可以在你的网页上运行),你可能需要自定义一些设置来适应你的网站,这也是为什么阅读上述文章是强制性的。

instantclick 工作原理

InstantClick与传统的web应用区别不大,但是很有必要去了解这些不同的地方!

instantclick使浏览器不再刷新整个页面(即无刷新页面效果)

首先:你需要理解的核心内容是:instantclick在技术上使你的网站成为单页应用程序;浏览器不再刷新整个页面,而是通过instantclick技术来更改页面内容,这意味着:

  • 你不能依赖DOMContentLoadedjQuery.ready()这两个函数来触发相关事件(这两个事件在刷新整个页面的时候才会触发,但是你可以使用[InstantClick’s events]()来替代)
  • 依赖上面两个函数的第三方脚本(比如js代码)需要调整(参阅[事件和脚本的重新加载]())
  • 在加载页面的时候,浏览器不会在显示原本加载进度条了,instantclick有它自己的加载进度条。

其次:你需要明白instantclick只会改变<body>title,所以你的脚本只会被加载一次(带来的好处是速度的明显提升)。

下面还有一些内容你需要了解:

  • 通过instantclick加载的每个页面的<head>标签里面的样式和脚本应该是相同的(因为instantclick只会加载一次<head>标签里的内容)
  • 如果<head>标签里面的某些内容依赖于网页的内容(比如在页面加载时运行的脚本或css动画),它需要调整以便正常运行。

InstantClick是渐进式增强功能:如果访问者的浏览器不支持InstantClick,您的网站链接将照常工作,只是不会提升速度了。

预加载页面

InstantClick 关于预加载方式有多种选择。你可以根据你的服务器配置来选择合适的方式。

但是不管怎样,当每个页面改变时,不会重新加载脚本和样式表,这样会使你的页面加载速度提升一倍!(与Turbolinks、pjax等等技术是类似的)

默认: 在鼠标悬停预加载(on mouseover)

当用户鼠标悬停在链接上开始预加载页面。如果用户网络链接不错的话,你的页面会很快的打开。

初始化方法就是[开始使用]()设置的方式。

不会给服务器带来额外负担:在鼠标点击的瞬间预加载(mousedown)

当用户按下你的链接按钮的瞬间,页面开始预加载。这为你的服务器带来了接近零的开销,但仍然能够带来一个很“神奇”的速度提升!

使用方法:将'mousedown'作为参数传递给InstantClick.init

InstantClick.init('mousedown');

折中的方式:鼠标悬停延迟一定时间才会预加载

如果用户在您选择的延迟过后仍悬停在链接上,则该网页将开始预加载。

推荐的延迟时间为:100ms和50ms。超过100ms效果比mousedown效果更差。低于50ms,则会与mouseover效果相似。

要使InstantClick延迟一定时间后预加载,请将延迟(毫秒)作为参数传递给InstantClick.init。

InstantClick.init(50);

手机端效果

上面的任何预加载方式,在手机端的时候,当用户手指接触链接时候都会开始预加载。

如果您的网站针对移动设备(在安卓和iOS界面上使用了[FashClick]()技术)进行了优化,则当访问者从链接中释放手指时,会发生“点击”,导致预加载大约100 ms的延迟。

如果您的网站没有针对手机进行优化,延迟时间则取决于操作系统。 Android给出300 ms,iOS给出450 ms。

在同一站点上的3G请求的延迟时间通常需要大约200ms。

如何选择?

如果您的网站可以处理额外的负载,选择 在鼠标悬停时预加载方式。

如果你的网站不能,选择在鼠标点击的瞬间预加载方式。您的网站的速度仍然会超过99%的网站。

如果你想确定你的服务器是否可以,先选择在鼠标点击的瞬间预加载方式,你的服务器几乎不会有额外的压力。然后使用鼠标悬停延迟100毫秒预加载。然后50毫秒延迟(或减少更小的减少,如果你有耐心)。然后直接用在鼠标悬停时预加载,分别看你的服务器是否能够承受额外的负担。

如果服务器端分析很重要,你只能使用在鼠标点击的瞬间预加载,使用任何其他方式都会带来误差。

黑名单规则

有一些链接是不需要通过instantclick来预加载。黑名单规则可以实现这个效果。

哪些需要进入黑名单

哪些需要进入黑名单,而不能进入白名单的:

  • 链接指向操作,例如注销和切换语言。
  • 链接指向需要一段时间加载的非HTML内容
  • 链接指向的页面与当前页面<head>标签内的css样式和脚本不同
  • 链接触发JavaScript的操作

部分链接已在内部列入黑名单,且无法列入白名单:

  • 链接有target或者download属性
  • 链接与当前的域名或者协议不同
  • 链接指向当前页面的锚点链接(#anchor)

把一个链接列入黑名单

把一个链接加入黑名单,只需要在链接中加入data-no-instant属性

<a href="/blog/" data-no-instant>Blog</a>

把一组链接列入黑名单

有时候要把一组链接一起列入黑名单,这时候比给所有链接分别添加data-no-intant要方便的多。

把父元素内部的所有链接列入黑名单,只需要向该父元素添加data-no-instant属性。

把一个链接或者一组链接列入白名单

如果您已将某个父元素列入黑名单,并且希望将其中的某个链接(或者子元素内部的所有链接)列入白名单,只需要向该链接或子元素添加data-instant属性。

InstantClick在后台中从当前链接的位置到</html>的位置,遍历所有的父元素,如果找到data-no-instant属性,它就会认为该链接已经被列入黑名单,并停止循环遍历父元素。如果它找到data-instant属性,它会认为该链接已经被列入白名单。(此处翻译可能需要修改)

如果您希望默认将所有链接列入黑名单,然后逐个将链接列入白名单或仅想把某个容器的链接列入白名单,请在<body>添加一个data-no-instant属性,然后向该链接或者容器中添加data-instant属性。

白名单模式

下面的方法已经弃用,可能会在4.0版本中删除。只有当你的网站正确激活参数(真正的参数传递给InstantClick.init),这种方法才会有用。(此处翻译可能需要修改)

正确的方式™:如果要实现与白名单模式相同的效果,只需添加data-no-instant到你的<body>标签中,参见上一条目“把一个链接或者一组链接列入白名单”。

通过向InstantClick.init传递true参数来启用白名单模式。

InstantClick.init(true);
/* or */
InstantClick.init(50, true);
/* or */
InstantClick.init('mousedown', true);

事件和脚本的重新加载

InstantClick技术上使你的网站成为单页应用程序,因此当页面切换的时候,不会触发DOMContentLoaded函数。因此,一些脚本可能需要调整才能与InstantClick正常工作。

InstantClick会触发4个事件以便于挂钩到页面的整个生命周期:

  • change:当前的页面一旦改变会触发该事件,即使浏览器不支持instantclick,页面初始加载的时候也会触发该事件,这个事件可以用来替换DOMContentLoaded.

它的回调可以接受一个可选的isInitialLoad参数,它是一个布尔值,当它是初始页面更改或当InstantClick不被支持时为true,而当InstantClick更改页面时为false。(此处翻译需要修改)

  • fetch:页面开始预加载的时候
  • receive:页面已经预加载完成,你可以使用该事件[修改页面的内容]().
  • wait:用户已经点击了链接,但是页面还没有开始预加载。仅在页面不是立即显示(可能由于网络原因)的时候触发。

监听一个事件,比如change,你可以使用InstantClick.on:

InstantClick.on('change', yourCallback);

您需要在InstantClick.init之前调用InstantClick.on,因为change事件在网页初始加载时就会被触发,包括浏览器不支持pushState的时候。(此处翻译可能需要修改)


如果在<body>标签内部有一个脚本,当instantclick切换到另一个页面的时候,你并不希望重新加载它 ,你可以添加一个data-no-instant属性。

<script data-no-instant>alert("I’m only run once.");</script>

如果有一些脚本与instantclick发生冲突,建议向所有脚本添加一个data-no-instant属性,然后逐个删除每个属性,直到找到罪魁祸首。您可以通过查看Turbolinks兼容性站点上的示例(在CoffeeScript中)了解如何解决兼容性问题。


例如,以下是如何使Google Analytics(网站统计与分析)(2013年末的代码)正常工作:

<script src="instantclick.min.js" data-no-instant></script>
<script data-no-instant>
/* Google Analytics code here, without ga('send', 'pageview') */
 
InstantClick.on('change', function() {
  ga('send', 'pageview', location.pathname + location.search);
});
 
InstantClick.init();
</script>

receive事件里改变页面内容

有时,即时改变页面内容比为instantclick重构你的后端代码要简单。你可以使用receive事件。

这个事件有三个参数:url, ,bodytitle

url 接收的页面的地址,它包括哈希值。它是只读的。

body是body对象,title是标题文本。如果你想在页面显示之前改变页面内容,你可以修改这两个参数并返回一个对象(或者只修改其中的一个参数)。

下面是一个例子:

InstantClick.on('receive', function(url, body, title) {
  var dont_display = body.querySelector('#dont_display_me_when_loaded_with_instantclick')
  if (dont_display) {
    dont_display.setAttribute('hidden', '');
  }
  title += ' (loaded with InstantClick)';
  
  return {
    body: body,
    title: title
  };
});

要记住 body 对象是body 而不是document.body!

当您有多个回调函数监听receive函数时,每个后续回调将获得最后更改的内容。

如果你不想修改页面内容,则不用返回任何内容或返回false

进阶阶段

跟踪页面内容的变化

当前跟踪页面内容的变化的方式目前有点笨拙。它可能稍后在InstantClick 4.0中更改。

要检查样式表或脚本(外部或内联)何时更新,请添加一个data-instant-track属性:

<link rel="stylesheet" href="style.css" data-instant-track>
<script src="script.js" data-instant-track></script>
 
<style data-instant-track>body { background: aliceblue; }</style>
<script data-instant-track>window.timingStart = performance.now();</script>

InstantClick将检查hrefsrc属性(如果存在)中的更改。要指示文件已更新,请修改其属性:

<link rel="stylesheet" href="style.css?20140308" data-instant-track>
<script src="script.js?20140308" data-instant-track></script>

如果它是内联脚本或样式,InstantClick将检查元素内容中的更改。

<style data-instant-track>body { background: midnightblue; font: 13px Helvetica; }</style>
<script data-instant-track>var timingStart = performance && performance.now();</script>

当检测到任何更改时,InstantClick将重新加载页面,从而使浏览器重新评估所有脚本和样式。

自定义加载条

进度条是一个假的进度条,只是在那里给你的用户的感觉页面的加载进度。

在未来,应该可以使进度条显示真正的进度(通过查看服务器的Content-Length头)。

即使页面已经立即加载,也会显示进度条,在将来这将更改。你可以在github讨论。

当访问者缩放页面或旋转其设备时,该栏的大小和位置会自动调整,因此即使您的网站未针对移动设备进行优化,也会正常工作。

默认情况下,进度条的颜色为#29d, 你可以改变CSS:

#instantclick-bar {
  background: white;
}

你也可以让进度条消失:

#instantclick {
  display: none;
}

使进度条消失的方式不是最佳的。在稍后的InstantClick版本中,可能可以通过向InstantClick.init传递参数来实现这个效果。

最后修改:2017 年 08 月 17 日
喜欢我的文章吗?
别忘了点赞或赞赏,让我知道创作的路上有你陪伴。