perfect scrollbar jQuery鼠标滚轮滚动事件

# `perfect-scrollbar` Minimalistic but perfect custom scrollbar plugin [](https://travis-ci.org/noraesae/perfect-scrollbar) If you want information of old versions&lt;0.6.0, please refer to [an old documentation](https://github.com/noraesae/perfect-scrollbar/tree/0.5.9). ## Why perfect-scrollbar? I was once working on a personal project, and trying to find the jQuery scrollbar plugin that's *perfect*. But there was no *perfect* one. That's why I decided to make one. perfect-scrollbar is minimalistic but *perfect* (for me, and maybe for most developers) scrollbar plugin working with jQuery or vanilla JavaScript as well. I hope you love it! ## [Demo](http://noraesae.github.com/perfect-scrollbar/) [It's on the GitHub Pages](http://noraesae.github.com/perfect-scrollbar/). ## What does *perfect* mean? *perfect* means... * There should be no css change on any original element. * The scrollbar should not affect the original design layout. * The design of the scrollbar should be (nearly) fully customizable. * If the size of the container or the content changes, the scrollbar size and position should be able to change. * *New!* It should work with vanilla JavaScript and major tools like NPM or Browserify. ## Then perfect-scrollbar is really *perfect*? * perfect-scrollbar has some requirements, but doesn't change or add any style on original elements. * perfect-scrollbar is designed not to have width or height. It's fixed on the right and bottom side of the container. * You can change nearly all css styles of the scrollbar. The scrollbar design has no dependency on scripts. * perfect-scrollbar supports an 'update' function. Whenever you need to update the size or position of the scrollbar, just update. * Additionally, perfect-scrollbar uses 'scrollTop' and 'scrollLeft', not absolute positioning or something messy. * perfect-scrollbar supports RTL perfectly on both WebKit and Gecko based browsers. It's cool, isn't it? ## Install The best way to install and use perfect-scrollbar is with NPM. It's registered on [npm](https://www.npmjs.org/package/perfect-scrollbar) as `perfect-scrollbar`. ``` $ npm install perfect-scrollbar ``` You can download the latest stable version with download links [here](http://noraesae.github.io/perfect-scrollbar/). You also can find all releases on [Releases](https://github.com/noraesae/perfect-scrollbar/releases). If you want to use the development version of the plugin, use the source files which are not minified. They're in the `src` directory. The development version may be unstable, but some known bugs may have been fixed. ``` $ git clone https://github.com/noraesae/perfect-scrollbar.git $ cd perfect-scrollbar/src $ npm install $ gulp # will lint and build the source code. ``` There is a Bower package for perfect-scrollbar as well. It is managed under the [perfect-scrollbar-bower](https://github.com/noraesae/perfect-scrollbar-bower) repository. The plugin is registered as `perfect-scrollbar`. ``` $ bower install perfect-scrollbar ``` You can also load it from [cdnjs](http://cdnjs.com/). It is registered as [`jquery.perfect-scrollbar`](http://www.cdnjs.com/libraries/jquery.perfect-scrollbar). ## Requirements To make this plugin *perfect*, some requirements were unavoidable. But, they're all very trivial and there is nothing to worry about. The following requirements should meet. * the container must have a 'position' css style. The following requirements are included in the basic CSS, but please keep in mind when you'd like to change the CSS files. * the container must have an 'overflow:hidden' css style. * the scrollbar's position must be 'absolute'. * the scrollbar-x must have a 'bottom' css style, and the scrollbar-y must have a 'right' css style. ## How to use First of all, please check if the container element meets the requirements. ```html <link rel='stylesheet' href='dist/css/perfect-scrollbar.css' /> <style> #container { position: relative; height: 100%; /* Or whatever you want (eg. 400px) */ } </style> ``` I would recommend using the plugin with NPM and CommonJS module system like Browserify. ```javascript var Ps = require('perfect-scrollbar'); ``` Or you can just load the script file as usual. ```html <script src='dist/js/perfect-scrollbar.js'></script> ``` To initialise the plugin, `Ps.initialize` is used. ```javascript var container = document.getElementById('container'); Ps.initialize(container); ``` It can be initialised with optional parameters. ```javascript Ps.initialize(container, { wheelSpeed: 2, wheelPropagation: true, minScrollbarLength: 20 }); ``` If the size of your container or content changes, call `update`. ```javascript Ps.update(container); ``` If you want to destory the scrollbar, use `destroy`. ```javascript Ps.destroy(container); ``` If you want to scroll to somewhere, just use a `scrollTop` property and update. ```javascript container.scrollTop = 0; Ps.update(container); ``` You can also get information about how to use the plugin from code in the `examples` directory of the source tree. ## jQuery As you may already know, perfect-scrollbar was a jQuery plugin. And it *is* as well. There's a jQuery adaptor and the plugin can be used in the same way it used to be used before. I also recommend using NPM and CommonJS here, but it's not mandatory. ```javascript var $ = require('jquery'); require('perfect-scrollbar/jquery')($); ``` For sure, you can just import a built script. ```html <script src='dist/js/perfect-scrollbar.jquery.js'></script> ``` After importing it, you can use the plugin in the usual way. ```javascript $('#container').perfectScrollbar(); // Initialize $('#container').perfectScrollbar({ ... }); // with options $('#container').perfectScrollbar('update'); // Update $('#container').perfectScrollbar('destroy'); // Destroy ``` ## RequireJS usage For RequireJS loader, no need to write shim, simply import two libs: ```javascript require.config({ paths: { perfectScrollbarJQuery: '.../perfect-scrollbar.jquery', perfectScrollbar: '.../perfect-scrollbar', } ... }) ``` and load `perfectScrollbar` in the initialiser of your app: ```javascript # for vanilla JS: window.Ps = require('perfectScrollbar'); # for jQuery: require('perfectScrollbarJQuery'); ``` ## AngularJS + RequireJS usage With the require.config settings above, at the beginning of your app module definition, you can have following code: ```javascript define([ 'angular', 'perfectScrollbar', 'perfectScrollbarJquery' ], function (angular) { var myApp = angular.module('myApp', []) .run(function() { window.Ps = require('perfectScrollbar'); require('perfectScrollbarJQuery'); }) return myApp; }); ``` And initialise perfectScrollbar in a controller: ```javascript # by vanilla JS: var container = document.getElementById('imgLoader'); Ps.initialize(container); Ps.update(container); # or by jQuery: var imgLoader = $("#imgLoader") imgLoader.perfectScrollbar(); ``` ## Optional parameters perfect-scrollbar supports optional parameters. ### wheelSpeed The scroll speed applied to mousewheel event. **Default: 1** ### wheelPropagation If this option is true, when the scroll reaches the end of the side, mousewheel event will be propagated to parent element. **Default: false** ### swipePropagation If this option is true, when the scroll reaches the end of the side, touch scrolling will be propagated to parent element. **Default: true** ### minScrollbarLength When set to an integer value, the thumb part of the scrollbar will not shrink below that number of pixels. **Default: null** ### maxScrollbarLength When set to an integer value, the thumb part of the scrollbar will not expand over that number of pixels. **Default: null** ### useBothWheelAxes When set to true, and only one (vertical or horizontal) scrollbar