iScroll API

下面,咱们开始iScroll之旅,请系好安全带。


iScroll简介


iScroll是一个高性能,资源占用少,无依赖,多平台的javascript滚动插件。


它能够在桌面,移动设备和智能电视平台上工做。它一直在大力优化性能和文件大小以便在新旧设备上提供最顺畅的体验。


iScroll不只仅是 滚动。它能够处理任何须要与用户进行移动交互的元素。在你的项目中包含仅仅4kb大小的iScroll,你的项目便拥有了滚动,缩放,平移,无限滚动,视差滚动,旋转功能。给它一个扫帚它甚至能帮你打扫办公室。


即便平台自己提供的滚动已经很不错,iScroll能够在此基础上提供更多难以想象的功能。具体来讲:javascript

  • 细粒度控制滚动位置,甚至在滚动过程当中。你老是能够获取和设置滚动器的x,y坐标。
  • 动画可使用用户自定义的擦出功能(反弹'bounce',弹性'elastic',回退'back',...)。
  • 你能够很容易的挂靠大量的自定义事件(onBeforeScrollStart, *
  • 开箱即用的多平台支持。从很老的安卓设备到最新的iPhone,从Chrome浏览器到IE浏览器。

 

iScroll的版本

针对iScroll的优化。为了达到更高的性能,iScroll分为了多个版本。你能够选择最适合你的版本。php

目前咱们有如下版本:css

  • iscroll.js,这个版本是常规应用的脚本。它包含大多数经常使用的功能,有很高的性能和很小的体积。
  • iscroll-lite.js,精简版本。它不支持快速跳跃,滚动条,鼠标滚轮,快捷键绑定。但若是你所须要的是滚动(特别是在移动平台) iScroll 精简版 是又小又快的解决方案。
  • iscroll-probe.js,探查当前滚动位置是一个要求很高的任务,这就是为何我决定创建一个专门的版本。若是你须要知道滚动位置在任何给定的时间,这是iScroll给你的。(我正在作更多的测试,这可能最终在常规iscroll.js脚本,请留意)。
  • iscroll-zoom.js,在标准滚动功能上增长缩放功能。
  • iscroll-infinite.js,能够作无限缓存的滚动。处理很长的列表的元素为移动设备并不是易事。 iScroll infinite版本使用缓存机制,容许你滚动一个潜在的无限数量的元素。

 

入门

Scroll是一个类,每一个须要使用滚动功能的区域均要进行初始化。每一个页面上的iScroll实例数目在设备的CPU和内存能承受的范围内是没有限制的。java

尽量保持DOM结构的简洁。iScroll使用硬件合成层可是有一个限制硬件能够处理的元素。
最佳的HTML结构以下:git

<div id="wrapper"> <ul> <li>...</li> <li>...</li> ... </ul> </div> 

iScroll做用于滚动区域的外层。在上面的例子中,UL元素能进行滚动。只有容器元素的第一个子元素能进行滚动,其余子元素彻底被忽略。github

最基本的脚本初始化的方式以下:ajax

<script type="text/javascript"> var myScroll = new IScroll('#wrapper'); </script> 

**第一个参数能够是滚动容器元素的DOM选择器字符串**,**也能够是滚动容器元素的引用对象**。下面是一个有效的语法:sql

var wrapper = document.getElementById('wrapper'); var myScroll = new IScroll(wrapper); 

因此基本上你要么直接传递元素,要么传递一个querySelector字符串。所以可使用css名称代替ID去选择一个滚动器容器,以下:编程

var myScroll = new IScroll('.wrapper'); 

注意,iScroll使用的是querySelector 而不是 querySelectorAll,因此iScroll只会做用到选择器选中元素的第一个。若是你须要对多个对象使用iScroll,你须要构建本身的循环机制。api

初始化

当DOM准备完成后iScroll须要被初始化。最保险的方式是在w**indow的onload事件中启动它**。
在**DOMContentLoaded**事件中或者**inline initialization**中作也能够,须要记住的是脚本须要知道滚动区域的高度和宽度。***若是你有一些图片在滚动区域致使不能立马获取区域的高度和宽度,iScroll的滚动尺寸有可能会错误***。

为滚动起容器增长position:relative或者absolute样式。这将解决大多数滚动器容器大小计算不正确的问题。
综上所述,最小的iScroll配置以下:

<head> ... <script type="text/javascript" src="iscroll.js"></script> <script type="text/javascript"> var myScroll; function loaded() { myScroll = new IScroll('#wrapper'); } </script> </head> ... <body onload="loaded()"> <div id="wrapper"> <ul> <li>...</li> <li>...</li> ... </ul> </div> </body> 

**注:**若是你有一个复杂的DOM结构,最好在onload事件以后适当的延迟,再去初始化iScroll。最好给浏览器100或者200毫秒的间隙再去初始化iScroll。

参数配置

在iScroll初始化阶段能够经过构造函数的第二个参数配置它。

var myScroll = new IScroll('#wrapper', { mouseWheel: true, scrollbars: true }); 

上面的例子示例了在iScroll初始化时开启鼠标滚轮支持和滚动条支持。

理解核心

iScroll使用基于设备和浏览器性能的各类技术来进行滚动。一般不须要你来配置引擎,iScroll会为你选择最佳的方式。

尽管如此,理解iScroll工做机制和了解如何去配置他们也是很重要的。

options.useTransform

默认状况下引擎会使用**CSStransform**属性。若是如今仍是2007年,那么能够设置这个属性为false,这就是说:引擎将使用top/left属性来进行滚动。
这个属性在滚动器感知到Flash,iframe或者视频插件内容时会有用,可是须要注意:性能会有极大的损耗。
默认值:true

options.useTransition

iScroll使用**CSS transition**来实现动画效果(动量和弹力)。若是设置为false,那么将使用requestAnimationFrame代替。
在如今浏览器中这二者之间的差别并不明显。在老的设备上transitions执行得更好。默认值:true

options.HWCompositing

这个选项尝试使用**translateZ(0)**来把滚动器附加到硬件层,以此来改变CSS属性。在移动设备上这将提升性能,但在有些状况下,你可能想要禁用它(特别是若是你有太多的元素和硬件性能跟不上)。
默认值:true

*注:***若是不肯定iScroll的最优配置。从性能角度出发,上面的全部选项应该设置为true。(或者更好的方式,让他们自动设置属性为true)。你能够尝试这配置他们,可是要当心内存泄漏。

滚动条

滚动条不仅是像名字所表达的意义同样,在内部它们是做为indicators的引用。

一个指示器侦听滚动条的位置而且现实它在全局中的位置,可是它能够作更多的事情。
先从最基本的开始。

options.scrollbars

正如咱们在基本功能介绍中提到的,激活滚动条只须要作一件事情,这件事情就是:

var myScroll = new IScroll('#wrapper', { scrollbars: true }); 

固然这个默认的行为是能够定制的。

滚动的编程接口

固然还能够经过编程来进行滚动。

scrollTo(x, y, time, easing)

对应存在的一个叫作myScroll的iScroll实例,能够经过下面的方式滚动到任意的位置:

myScroll.scrollTo(0, -100);

经过上面的方式将向下滚动100个像素。记住:0永远是左上角。须要滚动你必须传递负数。
time 和 easing是可选项。他们控制滚动周期(毫秒级别)和动画的擦除效果。
擦除功能是一个有效的IScroll.utils.ease对象。例如应用一个一秒的经典擦除动画你应该这么作:

myScroll.scrollTo(0, -100, 1000, IScroll.utils.ease.elastic);

擦除动画的类型选项有:quadratic, circular, back, bounce, elastic。

scrollBy(x, y, time, easing)

和上面一个方法相似,可是能够传递X和Y的值从当前位置进行滚动。

myScroll.scrollBy(0, -10);

上面这个语句将在当前位置向下滚动10个像素。若是你当前所在位置为-100,那么滚动结束后位置为-110.

scrollToElement(el, time, offsetX, offsetY, easing)

这是一个颇有用的方法,你会喜欢它的。
在这个方法中只有一个强制的参数就是el。传递一个元素或者一个选择器,iScroll将尝试滚动到这个元素的左上角位置。
time是可选项,用于设置动画周期。
offsetX 和 offsetY定义像素级的偏移量,因此你能够滚动到元素而且加上特别的偏移量。但并不只限于此。若是把这两个参数设置为true,元素将会位于屏幕的中间。
easing参数和scrollTo方法里的同样。

对齐

iScroll能对齐到固定的位置和元素。

options.snap

最简单的对齐配置以下:

var myScroll = new IScroll('#wrapper', { snap: true }); 

这将按照页面容器的大小自动分割滚动条。
snap属性也能够传递字符类型类型的值。这个值是滚动条将要对齐到的元素的选择器。好比下面:

var myScroll = new IScroll('#wrapper', { snap: 'li' }); 

这个示例中滚动条将会对齐到每个LI标记的元素。
下面将帮助你快速浏览iScroll提供的关于对齐的一系列有趣的方法。

goToPage(x, y, time, easing)

x 和 y呈现你想滚动到横向轴或者纵向轴的页面数。若是你须要在单个惟独上使用滚动条,只须要为你不须要的轴向传递0值。
time属性是动画周期,easing属性是滚动到指定点使用的擦除功能类型。请参考高级功能中的option.bounceEasing。这两个属性都是可选项。

myScroll.goToPage(10, 0, 1000);
上面这个例子将在一秒内沿着横向滚动到第10页。

next()

prev()

滚动到当前位置的下一页或者前一页。

缩放

为了使用缩放功能,你最好使用iscroll-zoom.js脚本。
和前面的示例同样,一个好的缩放功能的配置以下:

myScroll = new IScroll('#wrapper', { zoom: true, mouseWheel: true, wheelAction: 'zoom' }); 

刷新

iScroll须要知道包装器和滚动器确切的尺寸,在iScroll初始化的时候进行计算,若是元素大小发生了变化,须要告诉iScroll DOM发生了变化。
下面将提供调用refresh方法的正确时机。

每次触摸DOM,浏览器渲染器重绘页面。一旦发生了重画咱们能够安全地读新的DOM属性。从新绘制阶段不是瞬时发生的只是范围结束时触发。这就是为何咱们须要给渲染器刷新iScroll以前一点时间。

为了确保javascript获得更新后的属性,应该像下面的例子这样使用刷新方法:

ajax('page.php', onCompletion); function onCompletion () { // Update here your DOM setTimeout(function () { myScroll.refresh(); }, 0); }; 

这里调用refresh()使用了零秒等待,若是你须要当即刷新iScroll边界就是如此使用。固然还有其余方法能够等待页面重绘,但零超时方式至关稳定。

**注:***若是你有一个至关复杂的HTML结构,你应该给浏览器更多的执行事件,能够设置100到200毫秒的超时时间。
这一般适用于全部任务必须在DOM上进行。一般给渲染器一些执行的时间。*

自定义事件

iScroll还提供额一些你能够挂靠的有用的自定义事件。
使用on(type, fn)方法注册事件。

myScroll = new IScroll('#wrapper'); myScroll.on('scrollEnd', doSomething); 

上面的代码会在每次滚动中止是执行doSomething方法。
能够挂靠的事件以下:

beforeScrollStart,在用户触摸屏幕但尚未开始滚动时触发。
scrollCancel,滚动初始化完成,但没有执行。
scrollStart,开始滚动
scroll,内容滚动时触发,只有在scroll-probe.js版本中有效,请参考onScroll event。
scrollEnd,中止滚动时触发。
flick,用户打开左/右。
zoomStart,开始缩放。
zoomEnd,缩放结束。

按键绑定

你能够激活keyBindings选项来支持键盘控制。默认状况下iScroll监听方向键,上下翻页建,home/end键,但这些按键绑定彻底能够自定义。
你能够经过传递一个包含按键代码列表的对象来进行按键绑定。
默认的按键值以下:

keyBindings: {
    pageUp: 33,
    pageDown: 34,
    end: 35, home: 36, left: 37, up: 38, right: 39, down: 40 } 

固然你也能够传递字符串进行按键绑定(例如:pageUp: 'a')。只要你设置了对于的按键值,那么iScroll就会响应你的设置。

滚动条信息

iScroll存储了不少有用的信息,您可使用它们来加强您的应用。
你可能会发现有用的:

myScroll.x/y,当前位置
myScroll.directionX/Y,最后的方向 (-1 down/right, 0 still, 1 up/left)
myScroll.currentPage,当前对齐捕获点
下面是关于处理时间的代码示例:

myScroll = new IScroll('#wrapper'); myScroll.on('scrollEnd', function () { if ( this.x < -1000 ) { // do something } }); 

若是 x 位置是低于-1000 像素滚轮中止时,上述执行某些代码。请注意我用这个产品而不是 myScroll,您可使用两个固然,但 iScroll 传递自己做为这种状况下,当触发自定义事件的功能。

销毁

在不须要使用iScoll的时候调用iScroll实例的公共方法destroy()能够释放一些内存。

myScroll.destroy();
myScroll = null; 

参考:
https://github.com/cubiq/iscroll
https://iiunknown.gitbooks.io/iscroll-5-api-cn/content/