JRoll 2 使用文檔（史上最強大的下拉刷新，滾動，無限加載插件）

概述

說明

JRoll，一款能滾起上萬條數據，具備滑動加速、回彈、縮放、滾動條、滑動事件等功能，兼容CommonJS/AMD/CMD模塊規範，開源，免費的輕量級html5滾動插件。

JRoll第二版是在JRoll初版基礎上重寫JRoll滑動算法，基於時間運動，解決幀頻下降時滑動緩慢的問題，更改垂直水平方向判斷方法，使捕獲垂直水平方向更準確靈敏。

JRoll第二版增減了一些api不徹底兼容JRoll初版。

先睹爲快

http://www.chjtx.com/JRoll/demos/

 

運行示例

請先安裝 git 和 nodejs

#克隆倉庫 Clone repository git clone https://github.com/chjtx/JRoll.git #進入項目 Go into project cd JRoll #安裝express Install express npm install -g express #若是用蘋果電腦，須要加sudo #If on mac, use sudo sudo npm install -g express #運行 Run node server.js 

而後在瀏覽器打開 localhost:3020/demos/

 

兼容性

• [√] IOS 6+
• [√] Android 4.0+
• [√] Chrome
• [√] Firefox
• [√] IE 9+

注意：JRoll專爲移動應用度身設計，對PC瀏覽器的兼容只爲方便開發調試，沒做過多處理，所以強烈建議使用谷歌瀏覽器模擬器進行開發，在移動端使用。

在UC瀏覽器上表現較差，做者已將UC瀏覽器定義爲資訊類應用，非專業瀏覽器，不會專門去兼容它

引入

普通方式引入

                    <script src='jroll.js'></script> 

CommonJS規範引入

                    var JRoll = require('jroll'); 

AMD規範引入（requireJS）

                    require(['jroll'], function(JRoll) { ... }); 

CMD規範引入（seaJS）

                    seajs.use('jroll', function(JRoll) { ... }); 

簡單例子

html代碼

                    <div id="wrapper"> <ul id="scroller"> <li>有一美人兮，見之不忘。</li> <li>一日不見兮，思之如狂。</li> <li>鳳飛翱翔兮，四海求凰。</li> <li>無奈佳人兮，不在東牆。</li> <li>將琴代語兮，聊寫衷腸。</li> <li>何日見許兮，慰我彷徨。</li> <li>願言配德兮，攜手相將。</li> <li>不得於飛兮，使我淪亡。</li> </ul> </div> 

css代碼

                    ul {margin: 0; padding: 0;} li {line-height: 24px; margin-left: 24px;} #wrapper {width: 200px; height: 100px; border: 1px solid;} 

js代碼

                    new JRoll("#wrapper"); 

 

使用

如何使用

            var jroll = new JRoll(selector [, options]); 

selector是容器，能夠是id選擇器字符串#wrapper，也能夠是dom對象document.getElementById('wrapper')，第二個參數是可選對象，該參數內容決定了建立一個怎樣的JRoll對象

例：建立一個帶垂直滾動條的對象

            var jroll = new JRoll("#wrapper", {scrollBarY:true}); 

保存了JRoll對象後，可動態對部分可選參數進行修改

例：禁止回彈

            jroll.options.bounce = false; 

可選參數

可選值	默認值	說明
id	[隨機生成]	id，jroll對象的惟一標記，建議手動提供id，方便在全局JRoll.jrollMap訪問指定jroll對象，不提供時系統自動建立。
scrollX	false	使能水平滑動可動態修改
scrollY	true	使能垂直滑動可動態修改
scrollFree	false	使能自由滑動，默認狀況下，x方向在滑動時，y方向不能滑動，相反亦然，若是應用於對圖片進行放大滑動，可將此參數設爲true可動態修改
minX	0	向左滑動的邊界值可動態修改
maxX	[負scroller的寬]	向右滑動的邊界值可動態修改
minY	0	向下滑動的邊界值可動態修改
maxY	[負scroller的高]	向上滑動的邊界值可動態修改
zoom	false	使能縮放可動態修改
zoomMin	1.0	最小縮放倍數可動態修改
zoomMax	4.0	最大縮放倍數可動態修改
bounce	true	容許回彈可動態修改
scrollBarX	false	開啓水平滾動條
scrollBarY	false	開啓垂直滾動條
scrollBarFade	false	滾動條使用漸隱模式
preventDefault	true	禁止touchmove默認事件
momentum	true	開啓滑動加速，慣性過渡可動態修改
autoStyle	true	自動爲wrapper和scroller添加樣式
adjustTop	190	從JRoll v2.2.0版本開始，JRoll刪除了adjustTop選項，自動調整安卓機輸入框位置的功能抽離到jroll-fixedinput.js裏。安卓手機彈出軟鍵盤時自動調整輸入框位置，做者不建議使用該項，如遇軟鍵盤遮擋輸入框的狀況，建議從新設計表單頁面。參考：WebAPP輸入框被軟鍵盤遮擋腫麼辦？
scroller	[wrapper的第一個子元素]	指定scroller，不可動態更改，能夠是id選擇器字符串#scroller，也能夠是dom對象document.getElementById('scroller')

屬性

id

JRoll對象的惟一標識符。

var jroll = new JRoll("#wrapper"); console.log(jroll.id); 

jrollMap

對象，JRoll對象集合，保存了當前頁面的全部JRoll對象。

console.log(JRoll.jrollMap); 

方法

refresh 支持鏈式調用

當scroller或wrapper的高度發生變化時，須要用此方法對JRoll對象進行刷新

var jroll = new JRoll("#wrapper"); //do something，例：動態修改scroller的內容，使scroller的高度發生變化 jroll.refresh(); 

scrollTo 支持鏈式調用

該方法用於移動scroller，共五個參數，第一個參數是x偏移量（必填），第二個是y偏移量（必填），第三個是滑動時間（可選，單位ms)，第四個是是否容許超出邊界（可選，true/false），第五個回調方法（可選）。若是想獲取當前x,y偏移量，可直接輸出jroll.x和jroll.y

jroll.scrollTo(x, y, duration [, bool, callback]) 

var jroll = new JRoll("#wrapper"); //200ms內滑動到0px, -100px位置 jroll.scrollTo(0, -100, 200); //容許超出邊界 jroll.scrollTo(100, 100, 0, true); //回調 jroll.scrollTo(0, 100, 400, false, function() { //滑動結束後執行 }); 

enable 支持鏈式調用

使能滑動，使用disable禁止滑動後可用該方法從新開啓

jroll.enable(); 

disable 支持鏈式調用

使不能滑動

jroll.disable(); 

destroy

銷燬jroll對象

jroll.destroy(); 

scale 支持鏈式調用

縮放，只接受一個整型/浮點型參數

//放大1.5倍 jroll.scale(1.5); 

call

在滑動時中轉移對象，返回轉移給的對象。適合於嵌套滑動時內層滑動到末尾開始滑動外層的場景。

/* 例： * jroll1在外層，包裹jroll2 * jroll2在滑動到達指定條件時將滾動權交給jroll1 */ var pos; var jroll1 = new JRoll("#wrapper", {bounce:true}); var jroll2 = new JRoll("#inner", {bounce:true}); jroll2.on("scrollStart", function() { pos = this.y; }); jroll2.on("scroll", function(e) { if ((this.y-pos > 0 && pos === 0) || (this.y-pos < 0 && pos === this.maxScrollY)) { jroll2.call(jroll1, e); //返回jroll1 } }); 

事件

JRoll一共提供8個事件，每一個事件均可屢次添加行爲。事件裏的this指向jroll對象。

scrollStart

滑動開始時執行

jroll.on("scrollStart", function() { console.log(this.x); //輸出當前x偏移量，this指向jroll對象 }); 

scroll

滑動過程當中執行

jroll.on("scroll", function() { //該幹嗎幹嗎去... }); 

scrollEnd

滑動結束時執行

jroll.on("scrollEnd", function() { //該幹嗎幹嗎去... }); 

touchEnd

用戶釋放手指時執行，早於scrollEnd晚於scroll事件

jroll.on("touchEnd", function() { //該幹嗎幹嗎去... }); 

zoomStart

開始縮放時執行

jroll.on("zoomStart", function() { //該幹嗎幹嗎去... }); 

zoom

縮放過程當中執行

jroll.on("zoom", function() { //該幹嗎幹嗎去... }); 

zoomEnd

縮放結束後執行

jroll.on("zoomEnd", function() { //該幹嗎幹嗎去... }); 

refresh

使用jroll.refresh()刷新後執行

jroll.on("refresh", function() { //該幹嗎幹嗎去... }); 

 

進階

使用this.s判斷當前滑動狀態

var jroll = new JRoll("#wrapper"); jroll.on("scroll", function() { if (this.s === "scrollY") { //乾點你想幹的事情 } else { //或者乾點別的事情 } }) 

jroll.s中的s表示status，6種可能取值

• 1. null初始狀態，未進行任何滑動操做
• 2. preScroll準備開始滑動
• 3. preZoom準備開始縮放
• 4. scrollX正在進行橫向滑動
• 5. scrollY正在進行豎向滑動
• 6. scrollFree正在進行橫豎方向滑動

注意：JRoll v2.3.0如下版本的min壓縮文件的jroll.s值用一、二、三、四、5表示preScroll、preZoom、scrollX、scrollY、scrollFree。在JRoll v2.3.0版本開始與未壓縮版保持一致，當初真不該該爲了節省那丁點字節取用數字壓縮的。

判斷是否滑動到底部

var jroll = JRoll("#wrapper"); jroll.on("scrollEnd", function() { if (this.y === this.maxScrollY) { console.log("已滑動到底部"); } }); 

有關jroll對象更多的屬性請自行在瀏覽器控制檯輸出jroll對象查看。

自定義滾動條樣式

只要scrollBarX/scrollBarY的值爲字符串，即爲開啓自定義滾動條，須要本身寫樣式。

滾動條對樣式定位有些特殊要求，自定義滾動條大小、顏色時須要先將默認樣式拷貝下來，再對 .jroll-ybar/.jroll-xbar 和 .jroll-ybtn/.jroll-xbtn 進行修改。

var jroll = new JRoll("#wrapper", { scrollBarY: "custom", scrollBarFade: true }); 

解決某些安卓機沒法滑動非播放狀態的<video>

若是您的頁面須要播放視頻，在某些安卓機下沒法滑動<video>，可用如下方法解決。

非播放狀態的<video>其表現像controls同樣沒法捕獲touchstart等事件，所以沒法使用JRoll滑動，可以使用透明div解決。

<div id="parent"> <video id="video" controls="controls"> <source src="./video.ogg" type="video/ogg"> </video> <div class="fixed-video-scroll"></div> </div> <script> var video = document.getElementById("video"); document.addEventListener("click", function(e) { if (e.target.className === "fixed-video-scroll") { if (video.paused) { video.play(); } else { video.pause(); } } }) </script> 

• 1. 使#parent爲相對定位，video的寬度爲100%，高度可自動也可本身計算
• 2. div.fixed-video-scroll絕對定位，覆蓋video，高度爲video的高度減去44px，確保不會遮擋controls
• 3. 添加事件，點擊div.fixed-video-scroll時執行播放或暫停操做

關於被軟鍵盤遮擋input輸入框的問題

評論框貼在底部隨着軟鍵盤升起而升起的功能彷佛很受客戶青睞，這一需求使用H5技術實現非常力不從心，fixed定位失效，第三方輸入法不改變window高度導致input被遮擋，IOS自動移動input到錯誤位置等等問題成了最大的阻力。

現時比較可行的解決方案有：

• 1. 點擊評論時彈出浮動窗，使輸入框位於上半屏。
• 2. 切換到新頁面進行輸入操做。

這兩種設計方案都巧妙地避開了輸入框被軟鍵盤遮擋的狀況，可參考這篇文章WebAPP輸入框被軟鍵盤遮擋腫麼辦？

JRoll使用translate3d滑動頁面，可監聽input聚焦事件，使用scrollTo方法將輸入框移動到可見位置，在Android機上可解決被遮擋的問題，詳見jroll-fixedinput組件

 

下載

建議：下載文件後將文件名版本號去掉，這樣在JRoll有更新時只須要更新jroll.js文件，不須要更新引用jroll的文件。

• jroll.2.3.2.js(30k)
• jroll.2.3.2.min.js(14k)

• jroll.2.3.0.js(28k)
• jroll.2.3.0.min.js(14k)

• jroll.2.2.1.js(27k)
• jroll.2.2.1.min.js(13k)

• jroll.2.2.0.js(27k)
• jroll.2.2.0.min.js(13k)

• jroll.2.1.0.js(28k)
• jroll.2.1.0.min.js(13k)

• jroll.2.0.0.beta(25k)
• jroll.2.0.0.min.beta(12k)

版本日誌

v2.3.2（2016-10-23）

• 兼容IE 9+。
• 優化滑動體驗，bounce爲false滑動到最大/最小值時重置計算開始點和結束點。
• 添加仿QQ列表側滑刪除案例

v2.3.0（2016-10-16）

• 支持PC瀏覽器（只爲方便開發調試使用，並未在PC上做大量測試）。
• 解決wrapper的padding和scroller的margin形成maxWidth/maxHeight計算錯誤的問題。

v2.2.1（2016-07-29）

• 優化滑動。
• utils工具添加IOS判斷。

v2.2.0（2016-07-24）

• 防止按停滑動時誤觸a連接。
• 廢除adjustTop選項。
• 抽離focusin/out到jroll-fixedinput組件。
• 滑動時例input/textarea失焦。
• 調整滑動數值。

v2.1.0（2016-07-01）

• 正式版!!!
• 修復若干bug。
• 調整滑動數值。
• 使用requestAnimationFrame執行回彈，解決IOS在大量dom時使用transition回彈卡頓問題。
• textarea不出現滾動條時容許滾動JRoll實例。
• scrollTo方法添加第五個參數->回調方法。
• 滾動條長度限制最小爲8px。
• 刪除了g可選項，分階段使用不一樣的係數值。

v2.0.0（2016-06-19）

• 上線!!!
• 重寫滑動算法，基於時間運動，解決幀頻下降時滑動緩慢的問題。
• 更改垂直水平方向判斷方法，使捕獲垂直水平向更準確靈敏。
• 添加minX、maxX、minY、maxY選項。
• 添加touchEnd事件。
• 修改滾動條樣式。
• 刪除scroll選項。

 

插件

jroll-pulldown.js 下拉組件

下載：jroll-pulldown.js(9k) jroll-pulldown.min.js(6k)

說明：jroll-pulldown 使用文檔

jroll-infinite.js 無限加載組件

下載：jroll-infinite.js(7k) jroll-infinite.min.js(4k)

詳情：jroll-infinite 使用文檔

jroll-fixedinput.js 固定輸入框

下載：jroll-fixedinput.js(2k) jroll-fixedinput.min.js(1k)

詳情：jroll-fixedinput 使用文檔