http://cubiq.org/iscroll
The overflow:scroll for mobile webkit. Project started because webkit for iPhone does not provide a native way to scroll content inside a fixed size (width/height) div. So basically it was impossible to have a fixed header/footer and a scrolling central area. Until now.
How to use
First of all we need to prevent the default behavior of standard touch events. This is easily done adding preventDefault() to the touchmove event. Then initialize the iScroll object on DOMContentLoaded or on window load. Here an example:
function loaded() {
document.addEventListener('touchmove', function(e){ e.preventDefault(); });
myScroll = new iScroll('scroller');
}
document.addEventListener('DOMContentLoaded', loaded);
iScroll takes two parameters. The first is mandatory and is the ID of the element you want to scroll. The second is optional and can be used to pass additional parameters (see below).
On the HTML/CSS side the scrolling area needs to be wrapped by an element which determines the scroller actual size. The following is a common tags configuration for an iScroll.
<div id="wrapper">
<div id="scroller">
<ul>
<li>...</li>
</ul>
</div>
</div>
The #wrapper also needs some classes:
#wrapper {
position:relative;
z-index:1;
width:/* your desired width, auto and 100% are fine */;
height:/* element height */;
overflow:/* hidden|auto|scroll */;
}
That’s it. Enjoy your scrolling. Have a look at the source code of the online example to get a better idea of how the iScroll works.
Syntax
The iScroll syntax is: iScroll(mixed element_id, object options).
element_id, can be both an object pointing to or a string with the ID name of the element to be scrolled. Example: iScroll(document.getElementsByTagName('div')[1]) or iScroll('scroller')
Accepted options are:
- hScrollbar: set to
falseto never show the horizontal scrollbar. The default valuetruemakes the iScroll smartly decide when the scrollbar is needed. Note that if device does not supporttranslate3dhScrollbar is set tofalseby default. - vScrollbar: set to
falseto never show the vertical bar. The default valuetruemakes the iScroll smartly decide when the scrollbar is needed. Note that if device does not supporttranslate3dvScrollbar is set tofalseby default. - bounce: set to
falseto prevent the scroller to bounce outside of boundaries (Android behavior). Defaulttrue(iPhone behavior). - bounceLock:, if set to
truethe scroller stops bouncing if the content is smaller than the visible area. Default:false(as per native iphone scroll). - checkDOMChanges: set to
falseto prevent auto refresh on DOM changes. If you switch off this feature you have to calliScroll.refresh()function programmatically every time the DOM gets modified. If your code makes many subsequent DOM modifications it is suggested to set checkDOMChanges tofalseand to refresh the iScroll only once (ie: when all changes have been done). Defaulttrue. - fadeScrollbar: define wether the scrollbars should fade in/out. Default
trueon iPhone,falseon Android. Set tofalsefor better performance. - momentum: set to
falseto remove the deceleration effect on swipe. Defaulttrueon devices that support translate3d. - shrinkScrollbar: set to
falseto remove the shrinking scrollbars when content is dragged over the boundaries. Defaulttrueon iPhone,falseon Android. It has no impact on performances. - desktopCompatibility: for debug purpose you can set this to
trueto have the script behave on desktop webkit (Safari and Chrome) as it were a touch enabled device. - snap: set to
trueto activate snap scroll. - scrollbarColor: changes the color of the scrollbar. It accepts any valid CSS color (default:
'rgba(0,0,0,0.5)'
Note: options must be sent as object not string. Eg:
myScroll = new iScroll(’scroller’, { checkDOMChanges: false, bounce: false, momentum: false });
Snap scroll
When calling iScroll with “snap” option the scrolling area is subdivided into pages and whenever you swipe the scroll position will always snap to the page. Have a look at the screencast to get an idea.
Probably the best way to use “snap” is by calling it without momentum and scrollbars:
new iScroll('scroller', { snap:true, momentum:false, hScrollbar:false, vScrollbar:false });
If you keep momentum, you get a free-scrolling that will always stop to prefixed positions.
To have a perfect snapping experience the scrolling area should be perfectly divisible by the container size. Eg: If the container width is 200px and you have 10 elements, the whole scroller should be 2000px wide. This is not mandatory as iScroll doesn’t break if the last page is smaller than the container.
Methods
- refresh(): updates all iScroll variables. Useful when the content of the page doesn’t scroll and just “jumps back”. Call refresh() inside a zero
setTimeout. Eg:setTimeout(function () { myScroll.refresh() }, 0). - scrollTo(x, y, timeout): scrolls to any x,y location inside the scrolling area.
- scrollToElement(el, runtime): scrolls to any element inside the scrolling area.
elmust be a CSS3 selector. Eg:scrollToElement("#elementID", '400ms'). - scrollToPage(pageX, pageY, runtime): if snap option is active, scrolls to any page.
pageXandpageYcan be an integer orprev/next. Two keywords that snap to previous or next page in the raw. The “carousel” example in the zip file is a good starting point on using the snap feature. - destroy(full): completely unloads the iScroll. If called with
fullset totrue, the scroller is also removed from the DOM.
Best practices
DOM Changes – If scrolling doesn’t work after an ajax call and DOM change, try to initialize iScroll with checkDOMChanges: false and call refresh() function once the DOM modifications have been done. If this still doesn’t work try to put refresh() inside a 0ms setTimeout. Eg:
setTimeout(function () { myScroll.refresh(); }, 0);
Performance – CSS animations are heavy on the small device CPU. When too many elements are loaded into the scrolling area expect choppy animation. Try to reduce the number of tags inside the scrolling area to the minimum. Try to use just ULs for lists and Ps for paragraphs. Remember that you don’t actually need an anchor to create a button or send an action, so <li><a href="#" onclick="..." />text</a></li> is a waste of tags. You could remove the anchor and place the click event directly on the LI tag.
Try to avoid box-shadow and CSS gradients (especially on Android). I know they are cool and classy, but they don’t play well with CSS animations. Webkit on iPhone seems to handle shadows and gradients a bit better than its counterpart on Android, so you may selectively add/remove features based on the device.
Use a flat color for the #wrapper background, images in the scroller wrapper once again reduce performance.
Important: to preserve resources on devices that don’t support translate3d (namely: Android<2.0) iScroll disables momentum, scrollbars and bounce. You can however reactivate them using the respective options.
(0) 
(0)Posted by 홍반장
