本文目录

插件 jQuery.Custom Scrollbar 中文API文档

🌙
手机阅读
本文目录结构

插件 jQuery.Custom Scrollbar 中文API文档 https://github.com/mzubala/jquery-custom-scrollbar h1. jQuery Custom Scrollbar

jQuery Custom Scrollbar is a jQuery plugin that lets you add fully customizable scrollbars to your sites. With the plugin you can apply any css styles you want to your scrollbars.

h2. Features

  • vertical and horizontal scrollbars you can style your own way
  • scrolling by mouse dragging, mouse wheel, keyboard - just as you would with native browser scrollbar
  • touch scrolling on mobile devices (Android, iPhone and iPad)
  • a couple predefined skins showing you how to style scrollbars
  • simple api that lets you scroll programmatically and be notified about scroll events

h2. Requirements

The plugin supports all major browsers: Chrome, Firefox, IE 7+.

To use the plugin you obviously need jQuery (it should work in jQuery 1.4 and later versions).

h2. Download

You can download the latest version “here”:https://github.com/mzubala/jquery-custom-scrollbar/raw/master/build/jquery-custom-scrollbar-0.5.5.zip

h2. Demos

In demos folder of this repo, there are some example usages of custom scrollbar and its api. The demos are also available online “here”:http://jquery-custom-scrollbar.rocketmind.pl/

h2. Usage

First download and add jquery.custom-scrollbar.js and jquery.custom-scrollbar.css to your site.

Suppose you have a container on your site with some lengthy content and you want to make it scrollable:


Define it’s width and height (below some example size is used):


.container {
  width: 300px; // you can also use max-width
  height: 400px; // you can also use max-height
}

Add a skin class to your container:


In the example we use default-skin. Plugin comes with two other predefined skins: gray-skin and modern-skin. You are not limited to that and you can style scrollbar your own way.

Finally call this js code:


$(document).ready(function() {
  $(".container").customScrollbar();
});

If container content does not fit in those sizes scrollbar will appear.

The above method will add vertical scrollbar only. If you also want to add horizontal scrollbar, there is one more css step required:


.container .overview {
  width: 1000px;
}

This defines example total width of the scrolled content (not just the width of the visible part as in previous step).

h2. Options

There are some options you can pass when initializing scrollbar:

|. Option |. Type|. Default value |. Description | | animationSpeed | Number | 300 | Speed of the animation of programmatic scrolling. It’s possible to edit it with setAnimationSpeed method. Animation speed equal to 0 means no animation.| | fixedThumbHeight | Number | undefined | By default thumb height (in case of vertical scrollbar) is calculated automatically depending on viewport and overview height but you can fix thumb height to your chosen pixel value by setting this option. Make sure to not set min-height in css if you set fixedThumbHeight because min-height has priority.| | fixedThumbWidth | Number | undefined | Option analogical to fixedThumbHeight but applied to thumbs of horizontal scrollbars.| | hScroll | Boolean | true | Indicates whether or not, horizontal scrollbar should be shown when it’s necessary. | | preventDefaultScroll | Boolean | false | When the scrolling event occurs (e.g. down arrow key, mouse wheel) and it doesn’t cause the scrollbar to move (e.g. because the scrollbar is in extreme position), the event is propagated further which will cause the parent container to scroll. If it does cause the scrollbar movement then such event is stopped from propagating further and the parent container won’t scroll. This default behaviour can be changed by setting preventDefaultScroll: true. It will cause the custom scrollbar to always stop scrolling event propagation no matter if the scrollbar changed or didn’t change its position.| | skin|String|undefined|A css skin class that will be added to the scrolled container. You can define it in html as well as here in options. Note that skin has to be defined in one of those ways.| | swipeSpeed|Number|1|Indicates how fast touch scroll should be. When you swipe your finger by x pixels the content will be scrolled by swipeSpeed * x pixels.| | updateOnWindowResize | Boolean | false | Indicates whether scrollbar should recalculate thumb size when window is resized. See demos/resize.html for an example.| | vScroll | Boolean | true | Same as above but applies to vertical scrollbar. | | wheelSpeed|Number|40|Indicates how fast mouse wheel scroll should be. When you make the smallest possible mouse wheel move, the content will be scrolled by wheelSpeed pixels.|

For example:


$("#my-container").customScrollbar({
  skin: "default-skin", 
  hScroll: false,
  updateOnWindowResize: true
  })

h2. API

There are some methods of the plugin you may want to call.

h3. setAnimationSpeed(speed)

Changes programmatic scroll animation speed to the passed speed - an integer indicating how many milliseconds the animation should last.

It’s also possible to set the animation speed upon plugin initialization. By default it equals 300.

Note that you may use this method if want to have some scrolls animated and some without animation - to get rid of the animation just call it with 0.


$(".container").customScrollbar("setAnimationSpeed", 200)

h3. scrollTo(element)

Scrolls viewport to a given element inside scrolled content. An element might be jQuery object or a selector string. To control animation speed use animationSpeed initialization option. Example usage:


$(".container").customScrollbar("scrollTo", "#some-element-inside-container")

h3. scrollToX(x)

Sets horizontal scrollbar position to x pixels. x should be in range from 0 to scrolled content width. If it’s outside that range, content will be scrolled to the start or to the end. To control animation speed use animationSpeed initialization option.


$(".container").customScrollbar("scrollToX", 100)

h3. scrollToY(y)

Sets vertical scrollbar position to y pixels. x should be in range from 0 to scrolled content height. If it’s outside that range, content will be scrolled to the start or to the end. To control animation speed use animationSpeed initialization option.


$(".container").customScrollbar("scrollToY", 200)

h3. scrollByX(x)

Moves horizontal scrollbar by x pixels. x can be positive or negative.


$(".container").customScrollbar("scrollByX", 100)

h3. scrollByY(y)

Moves vertical scrollbar by y pixels. y can be positive or negative.


$(".container").customScrollbar("scrollByY", 200)

h3. resize(keepPosition)

Recalculates and sets sizes of all scrollbar components. Call this whenever your scrolled block changes its size and scrollbar becomes invalid. After you call it scrollbar is adjusted to new sizes of your block.

Use keepPosition parameter to decide if the scrollbar should stay in the same position (keepPosition == true) or change position (keepPosition == true) so that the thumb position change is proportional to the size change. The first case is useful if your container changes size and you want to show exactly the same content that was visible before size change. The second case is useful when you’re listening to window resize.


$(".container").customScrollbar("resize", true)

h3. remove()

Removes all the DOM changes and event bindings added by the plugin.


$(".container").customScrollbar("remove")

h2. Events

h3. customScroll

Triggered whenever content is scrolled. Separate events are fired when vertical and horizontal scrollbar is moved.


$(".container").on("customScroll", function(event, scrollData) {});

Handler function takes two arguments. event is standard jquery event object. scrollData is an object with 3 fields holding scroll specific information:

  • scrollPercent - floating point number in range 0.0 to 100.0 indicating percentage position of the scrollbar
  • scrollDirection - string that can take following 4 values: left, right, up, down - indicates what direction the scrollbar was moved in
  • scrollAxis - string indicating which scrollbar was moved: X for horizontal scrollbar and Y for vertical scrollbar

You can also bind handler to that event when initializing scrollbar:


$(".container").customScrollbar({
  onCustomScroll: function(event, scrollData) {}
});

h2. License

The plugin is released under “MIT license”:http://www.opensource.org/licenses/MIT.

AXIHE / 精选资源

浏览全部教程

面试题

学习网站

前端培训
自己甄别

前端书籍

关于朱安邦

我叫 朱安邦,阿西河的站长,在杭州。

以前是一名平面设计师,后来开始接接触前端开发,主要研究前端技术中的JS方向。

业余时间我喜欢分享和交流自己的技术,欢迎大家关注我的 Bilibili

关注我: Github / 知乎

于2021年离开前端领域,目前重心放在研究区块链上面了

我叫朱安邦,阿西河的站长

目前在杭州从事区块链周边的开发工作,机械专业,以前从事平面设计工作。

2014年底脱产在老家自学6个月的前端技术,自学期间几乎从未出过家门,最终找到了满意的前端工作。更多>

于2021年离开前端领域,目前从事区块链方面工作了