文档章节

jQuery custom content scroller

lgscofield
 lgscofield
发布于 2015/06/26 13:58
字数 2520
阅读 55
收藏 0

基于 jQuery 实现的非常精致的自定义内容滑动条。

Custom scrollbar plugin utilizing jquery UI that’s fully customizable with CSS. Features vertical/horizontal scrolling, mouse-wheel support (via Brandon Aaron jquery mouse-wheel plugin), scroll inertia & easing, auto-adjustable scrollbar length, scroll-to functionality and scrolling buttons.

How to use it

Download the archive which contains all plugin files and examples. Extract files and upload jquery.mCustomScrollbar.js,jquery.mousewheel.min.jsjquery.mCustomScrollbar.css and mCSB_buttons.png to your web server.

Include jquery.mCustomScrollbar.css inside the head tag your html document

 

<link href="jquery.mCustomScrollbar.css" rel="stylesheet" type="text/css" />

 

Include jquery, jquery UI, jquery.mousewheel.min.js and jquery.mCustomScrollbar.js in your html document

 

No wrap HTML
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7/jquery.min.js"></script>
<script src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/jquery-ui.min.js"></script>
<script src="jquery.mousewheel.min.js"></script>
<script src="jquery.mCustomScrollbar.js"></script>

 

The code above can be inserted inside the head tag or at the very bottom of your document, before the closing body tag (which is normally recommended for better performance). In either case, it’s more efficient to include css files before any javascript (usually inside the head tag). We’re using Google’s CDN to get jquery and jquery UI libraries (why?). The archive contains copies of both jquery and jquery UI (I’ve made a custom build of jquery UI to decrease its size to 43kb) in case you wanna load them from your own server or locally. You can find both files inside jquery directory.

The way I recommend and what I’ve used in all demos and examples is to load both jquery and jquery UI from Google and have local copies to fallback in case Google files cannot load:

 

No wrap HTML
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7/jquery.min.js"></script>
<script>!window.jQuery && document.write(unescape('%3Cscript src="jquery/jquery-1.7.2.min.js"%3E%3C/script%3E'))</script>
<script src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/jquery-ui.min.js"></script>
<script>!window.jQuery.ui && document.write(unescape('%3Cscript src="jquery/jquery-ui-1.8.21.custom.min.js"%3E%3C/script%3E'))</script>

 

What these files do

jquery is the javascript library used by the plugin (in case you don’t know what jquery is, here it is).

jquery UI (jQuery User Interface) extends jquery library and provides animation easing and drag functionality for our scrollbar.

jquery.mousewheel.min.js is a great 2kb plugin by Brandon Aaron that adds mouse-wheel support for all OS and browsers.

jquery.mCustomScrollbar.js is our main plugin file. The archive contains an additional minified version (jquery.mCustomScrollbar.min.js) which you can find inside the minified directory and is reduced to 16kb.

jquery.mCustomScrollbar.css is the css file we use to style our scrollbar(s) and contains the default styling. You could of course put scrollbars styling in your main stylesheet document to reduce http requests.

The mCSB_buttons.png is a single png image file that contains the default plus some additional sets for the up, down, left and right arrows used by the the scroll buttons. I’ve created a single file in order to use CSS sprites for the buttons (defined in jquery.mCustomScrollbar.css). The archive also contains the PSD source (sources/mCSB_buttons.psd) so you can add your own.

After files inclusion, you call mCustomScrollbar function on the element you want to add custom scrollbars. You can place the following code either in the head or body tag (depending on which tag you included the plugin files). The example below adds scrollbars to all elements with class name “content”:

 

No wrap Javascript
<script>
    (function($){
        $(window).load(function(){
            $(".content").mCustomScrollbar();
        });
    })(jQuery);
</script>

 

Note that we’re wrapping our jquery code with (function($){ ... })(jQuery);. This ensures no conflict between jquery and other libraries using $ shortcut. See Using jQuery with Other Libraries for more info. We also call our function on window load ($(window).load()) so the code executes after all page elements are fully loaded, ensuring the script calculates correctly content’s length. If the scrollbars apply to content that has no elements with external sources (e.g. images, objects etc.) you can use document ready instead (code executes after the DOM is ready):

 

No wrap Javascript
<script>
    (function($){
        $(document).ready(function(){
            $(".content").mCustomScrollbar();
        });
    })(jQuery);
</script>

 

You can change the function call selector (".content") to anything you want (an id, class name, js variable etc.) – see CSS selectors. For instance, if you want custom scrollbars to apply to the element with id “content-1″, you simply do:

 

$("#content-1").mCustomScrollbar();

 

You can also have multiple selectors by inserting comma separated values. For example, the following applies to a)every element with class name “content”, b)every div with rel attribute value with-custom-scrollbar and c)the element with id “content-1″:

 

$(".content,div[rel='with-custom-scrollbar'],#content-1").mCustomScrollbar();

 

The code above will add the default custom scrollbars with the same options parameters to all 3 selectors. Additionally, you can call mCustomScrollbar multiple times within a page for different options (configuration and option parameters explained below) on each selector:

 

No wrap Javascript
<script>
  (function($){
    $(window).load(function(){
      $(".content").mCustomScrollbar();
      $("div[rel='with-custom-scrollbar']").mCustomScrollbar({
        autoDraggerLength:false
      });
      $("#content-1").mCustomScrollbar({
        mouseWheel:false,
        scrollButtons:{
          enable:true
        }
      });
    });
  })(jQuery);
</script>

 

That’s the basics for implementing the plugin. The code below is a most basic html example with a full page markup:

 

No wrap HTML
<!DOCTYPE HTML>
<html>
  <head>
    <style>
      body{background:#333; color:#ddd;}
      .content{width:250px; height:450px; overflow:auto;}
    </style>
    <!-- Custom scrollbars CSS -->
    <link href="jquery.mCustomScrollbar.css" rel="stylesheet" type="text/css" />
  </head>
  <body>
    <div class="content">
      <!-- your long content here... -->
    </div>
    <!-- Get Google CDN's jQuery and jQuery UI with fallback to local -->
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7/jquery.min.js"></script>
    <script>!window.jQuery && document.write(unescape('%3Cscript src="jquery/jquery-1.7.2.min.js"%3E%3C/script%3E'))</script>
    <script src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/jquery-ui.min.js"></script>
    <script>!window.jQuery.ui && document.write(unescape('%3Cscript src="jquery/jquery-ui-1.8.21.custom.min.js"%3E%3C/script%3E'))</script>
    <!-- mousewheel plugin -->
    <script src="jquery.mousewheel.min.js"></script>
    <!-- custom scrollbars plugin -->
    <script src="jquery.mCustomScrollbar.js"></script>
    <script>
      (function($){
        $(window).load(function(){
          $(".content").mCustomScrollbar();
        });
      })(jQuery);
    </script>
  </body>
</html>

 

The plugin will add all necessary markup for the scrollbars to each of your content blocks. The final markup of each content block after being processed by the plugin script, will be:

 

No wrap HTML
<div class="content mCustomScrollbar _mCS_1">
  <div class="mCustomScrollBox">
    <div class="mCSB_container">
      <!-- your long content here... -->
    </div>
    <div class="mCSB_scrollTools">
      <a class="mCSB_buttonUp"></a>
      <div class="mCSB_draggerContainer">
        <div class="mCSB_dragger ui-draggable">
          <div class="mCSB_dragger_bar"></div>
        </div>
        <div class="mCSB_draggerRail"></div>
      </div>
      <a class="mCSB_buttonDown"></a>
    </div>
  </div>
</div>

 

mCSB_buttonUp and mCSB_buttonDown anchors are added only in case you enable scroll buttons (see configuration). The markup for content blocks with horizontal scrollbars is:

 

No wrap HTML
<div class="content mCustomScrollbar _mCS_1">
  <div class="mCustomScrollBox mCSB_horizontal">
    <div class="mCSB_container">
      <!-- your long content here... -->
    </div>
    <div class="mCSB_scrollTools">
      <a class="mCSB_buttonLeft"></a>
      <div class="mCSB_draggerContainer">
        <div class="mCSB_dragger ui-draggable">
          <div class="mCSB_dragger_bar"></div>
        </div>
        <div class="mCSB_draggerRail"></div>
      </div>
      <a class="mCSB_buttonRight"></a>
    </div>
  </div>
</div>

 

All your content resides inside .mCSB_container div. Content blocks with horizontal scrollbars simply get an additional .mCSB_horizontal class name and the button anchors change to mCSB_buttonLeft and mCSB_buttonRight.

Configuration

mCustomScrollbar function can get the following option parameters in order to customize scrollbar behavior and functionality:

set_width: false
Set the width of your content, value in pixels (integer) or percentage (string)
set_height: false
Set the height of your content, value in pixels (integer) or percentage (string)
horizontalScroll: Boolean
Add horizontal scrollbar (default is vertical), values: truefalse
scrollInertia: Integer
Scrolling inertia, value in milliseconds (0 for no scrolling inertia)
scrollEasing: String
Scrolling easing type, see jquery UI easing for all available easing types
mouseWheel: "auto"
Mouse-wheel support, values: truefalse"auto"integer 
By default, mouseWheel is set to “auto” which lowers mousewheel velocity on Safari browser on OSX. To disable mouse wheel set to false or set your own velocity by inserting an integer value (default is 8)
autoDraggerLength: Boolean
Auto-adjust scrollbar dragger length according to content, values: truefalse
scrollButtons:{
    enable: Boolean
}
Scroll buttons support, values: truefalse
scrollButtons:{
    scrollType: String
}
Scroll buttons scroll type, values: "continuous" (scroll continuously while pressing button), "pixels" (scroll by number of pixels on each click) 
See both scroll types in action
scrollButtons:{
    scrollSpeed: Integer
}
Scroll buttons continuous scrolling speed (default: 20), set a higher value for faster scrolling
scrollButtons:{
    scrollAmount: Integer
}
Scroll buttons pixels scroll amount (default: 40), value in pixels
advanced:{
    updateOnBrowserResize: Boolean
}
Update scrollbars on browser resize (for fluid containers & layouts based on percentages), values: truefalse. Set to false only if your content block has fixed dimensions
advanced:{
    updateOnContentResize: Boolean
}
Auto-update scrollbars on content resize (for dynamic content), values: truefalse 
Setting this to true will constantly check for content length changes and update scrollbars accordingly. I recommend to avoid setting this to true if possible, as it causes extra overhead (especially with many scrollbars on a single page). Instead, you can use the update method of the plugin (methods explained below), to update scrollbars manually when needed.
advanced:{
    autoExpandHorizontalScroll: Boolean
}
Auto-expand width for horizontal scrolling, values: truefalse 
Set to true if you have horizontal scrollbar on content that will update dynamically. Demo contains blocks with images and horizontal scrollbars that use this option parameter.
callbacks:{
    onScroll: function(){}
}
User custom callback function to run on scroll event. Run your own function(s) each time a scroll event completes. Example: 
callbacks:{
  onScroll:function(){
    alert("scrolled...");
  }
}
callbacks:{
    onTotalScroll: function(){}
}
User custom callback function to run on scroll end reached event. Example: 
callbacks:{
  onTotalScroll:function(){
    alert("scrolled to end of content.");
  }
}
callbacks:{
    onTotalScrollOffset: Integer
}
Scroll end reached offset, value in pixels 
Demo includes callbacks example. You can also see a more advanced callback example here

Example of defining all options parameters and their default values:

 

No wrap Javascript
$(".content").mCustomScrollbar({
  set_width:false, 
  set_height:false, 
  horizontalScroll:false, 
  scrollInertia:550, 
  scrollEasing:"easeOutCirc", 
  mouseWheel:"auto", 
  autoDraggerLength:true, 
  scrollButtons:{ 
    enable:false, 
    scrollType:"continuous", 
    scrollSpeed:20, 
    scrollAmount:40 
  },
  advanced:{
    updateOnBrowserResize:true, 
    updateOnContentResize:false, 
    autoExpandHorizontalScroll:false 
  },
  callbacks:{
    onScroll:function(){}, 
    onTotalScroll:function(){}, 
    onTotalScrollOffset:0 
  }
});

 

Plugin methods

update

Usage: $(selector).mCustomScrollbar("update");

Call the update method of mCustomScrollbar function to update existing scrollbars each time content changes dynamically (e.g. adding or removing elements with javascript, inserting new content via ajax, hiding/showing content blocks etc.). Methods apply on content blocks that already have custom scrollbars attached. Examples of calling update method:

 

No wrap Javascript
$(".content .mCSB_container").append("<p>New content here...</p>");
$(".content").mCustomScrollbar("update");

 

 

No wrap Javascript
$(".content .myImagesContainer").append("<img src='myNewImage.jpg' />");
$(".content .myImagesContainer img").load(function(){
  $(".content").mCustomScrollbar("update");
});

 

 

No wrap Javascript
$("#content-1").animate({height:800},"slow",function(){
  $(this).mCustomScrollbar("update");
});

 

Always call the update method after newly added content is fully loaded and animations are completed.

scrollTo

Usage: $(selector).mCustomScrollbar("scrollTo",position);

You can auto-scroll to any position within your content by calling the scrollTo method of mCustomScrollbar function. The position can be a string (e.g. “#element-id”, “bottom” etc.) or an integer for scrolling to pixels number. For example, the following will scroll to the last element within your content:

 

$(".content").mCustomScrollbar("scrollTo","last");

 

scrollTo method parameters:

$(selector).mCustomScrollbar("scrollTo",String);
Scrolls to element position, string value can be any unique id, class etc.
$(selector).mCustomScrollbar("scrollTo","top");
Scrolls to top (vertical scrollbars)
$(selector).mCustomScrollbar("scrollTo","bottom");
Scrolls to bottom (vertical scrollbars)
$(selector).mCustomScrollbar("scrollTo","left");
Scrolls to left-end (horizontal scrollbars)
$(selector).mCustomScrollbar("scrollTo","right");
Scrolls to right-end (horizontal scrollbars)
$(selector).mCustomScrollbar("scrollTo","first");
Scrolls to the first element position within the content
$(selector).mCustomScrollbar("scrollTo","last");
Scrolls to the last element position within the content
$(selector).mCustomScrollbar("scrollTo",Integer);
Scrolls to number of pixels, e.g. $(selector).mCustomScrollbar("scrollTo",200);

scrollTo method has 2 additional option parameters:

moveDragger: Boolean
Scroll scrollbar dragger (instead of content) to number of pixels, values: truefalse. Example: 
$(selector).mCustomScrollbar("scrollTo",200,{
  moveDragger:true
});
callback: Boolean
Run callbacks after scroll-to completes, values: truefalse. Example: 
$(selector).mCustomScrollbar("scrollTo",200,{
  callback:true
});

Styling the scrollbars

Style your scrollbar(s) using the jquery.mCustomScrollbar.css file which contains the default style. You can directly change the default styling or you can keep it and add additional styles for each scrollbar (check the stylesheet inside demo_files that I’ve used to style the scrollbars for the demo and examples).

You can have separate styling for each of your scrollbars on the same page, either by giving your content blocks different class names or ids or simply by targeting them in your css like this:

 

No wrap CSS
._mCS_1 .mCSB_scrollTools .mCSB_dragger .mCSB_dragger_bar{
    /* 1st scrollbar dragger style... */
}
._mCS_2 .mCSB_scrollTools .mCSB_dragger .mCSB_dragger_bar{
    /* 2nd scrollbar dragger style... */
}
._mCS_3 .mCSB_scrollTools .mCSB_dragger .mCSB_dragger_bar{
    /* 3rd scrollbar dragger style... */
}

 

…and so on. Each content block in your document that has custom scrollbars gets automatically an additional unique class in the form of _mCS_+index number (e.g. _mCS_1) based on its index number within the DOM. This way you can easily target and style any scrollbar using its parent class name.

Custom scrollbar layout

Additional info

Scrolling content that’s over 9999 pixels with older versions of jQuery

There’s a jQuery bug (prior to version 1.5) that resets to 0, an animate value greater than 9999 pixels. This bug will affect the scrollbar if your content’s width or height is greater than 9999 pixels and you use jQuery version of 1.4 and below, resulting a scrolling jerk (scrolling resets to 0 after pixels limit reached). This annoying bug is fixed on version 1.5 of the library. If you do use an older version, there’s a quick solution that overwrites the jquery function containing the buggy code ;) Insert the following code outside the window load or document ready functions:

 

No wrap Javascript
<script>
/* function to fix the -10000 pixel limit of jquery.animate */
$.fx.prototype.cur = function(){
    if ( this.elem[this.prop] != null && (!this.elem.style || this.elem.style[this.prop] == null) ) {
      return this.elem[ this.prop ];
    }
    var r = parseFloat( jQuery.css( this.elem, this.prop ) );
    return typeof r == 'undefined' ? 0 : r;
}
</script>

 

Loading & updating content dynamically

Each time you programmatically change the contents of a content block with custom scrollbars, you need to call plugin’s updatemethod (see methods section) in order to update its scrollbar according to the newly added content. You should always call theupdate method after dynamic content is fully loaded (see an ajax example).

There’s an option parameter (advanced:{ updateOnContentResize: true }) that automatically calls the update method if content length is changed so you don’t have to do it manually. I do not recommend setting this to true unless absolutely necessary, as it adds unnecessary overhead (especially if you have many scrollbars on a page).

Hiding & showing content blocks with custom scrollbars

Hidden content blocks have zero dimensions, so calling mCustomScrollbar function on them will not work. Instead, you should call the function after your blocks are fully visible, so the plugin calculates content length correctly and apply/update the scrollbar (see an example).

When hiding-showing content blocks with custom scrollbars, always call the update method after animations are completed and content is fully visible.

Touch devices

The plugin checks for touch devices and applies overflow: auto css rules, as well as -webkit-overflow-scrolling: touch to the content block so it can be scrolled natively by swiping (tested on iOS 5.1 on iPad, Android 2.xx).

本文转载自:http://lgscofield.iteye.com/blog/1679525

共有 人打赏支持
lgscofield

lgscofield

粉丝 22
博文 140
码字总数 63036
作品 0
南京
架构师
私信 提问
20个最有创意最实用的jQuery应用

我们看看三年来,这个被成为最优雅的Javascript框架带来那些创意应用。 以下翻译自国外网站,示例网站如无法点击访问,请自觉翻墙~ 原文链接:http://nettuts.com/articles/web-roundups/th...

晨曦之光
2012/03/09
0
0
60款很酷的 jQuery 幻灯片演示和下载

转自:http://www.cnblogs.com/lhb25/archive/2011/05/31/2056103.html jQuery 是一个非常优秀的 JavaScript 框架,使用简单灵活,同时还有许多成熟的插件可供选择,它可以帮助你在项目中加入...

hoojo
2013/09/26
0
0
5月最新超有趣的免费jQuery插件推荐

本文再给大家介绍一些比较有趣的,jQuery 插件。 1) Wow Window - 可用于替换 Lightbox,更有趣而且功能更强大。使用CSS3,这点不太好,没法兼容所有浏览器。 2) jQuery News Ticker - 新闻的...

任洪君
2011/12/22
0
0
jQuery命名冲突解决的五种方案

引言: 最近遇到个问题,同时引用了jquery库和另外一个js库。当用$XX去调用js库函数时,发现失效了!于是找资料,原来是jquery命名冲突了。因为许多JavaScript 库使用$作为函数或变量名,jqu...

龙上
2012/03/30
0
0
2014年140个最好的jQuery插件集合

Material Design Preloader Want to create a Google’s latest Material Design look-alike pre-loader? If yes, this jQuery plugin created by Aaron Lumsden will help you do so and y......

IanSun
2015/03/14
0
0

没有更多内容

加载失败,请刷新页面

加载更多

Beautiful Soup

定义 Python中的一个库,主要用于从网页爬取数据; 安装 pip install beautifulsoup4 四大对象 Beautiful Soup将复杂的HTML文档转换成树形结构,树中的每个节点都是Python对象,对象可归纳为...

村雨1943
22分钟前
1
0
Visual Studio 昨日发布新版本:增加实时同步编程、共同调试

多名开发者可以在同一个项目中编程,在编写代码和调试代码时只需发送一个 URL 网址,就能邀请他人参与协作,而且无需重新配置开发环境和安装任何附加包。该服务支持 Windows、Mac 与 Linux ...

linuxCool
25分钟前
1
0
发现一种不错的学习方法

这是在《软技能,代码之外的生存之道》所看到的一种学习方法,感觉这个理念不错,分享出来,共勉。 我的「十步学习法」 多年以来,我都承受着巨大的压力:快速学习新技术、新编程语言、新框架...

firepation
25分钟前
0
0
webpack4配置详解之常用插件分享

前言   继上一次webpack的基础配置分享之后,本次将分享一些工作中项目常用的配置插件、也会包含一些自己了解过觉得不错的插件,如有分析不到位的,欢迎纠错,嗯,这些东西文档都有,大佬可...

苏南-首席填坑官
42分钟前
8
1
升压变换器 Boost

工作特点 输入输出极性相同。 开关管 MOS 和负载构成并联,在MOS 导通时,电流通过 L 滤波,电源对 L 充电。 当 MOS 断开时,L 向负载及电源放电,输出电压将是 Ui+U L ,达到升压的目的。 ...

colinux
44分钟前
2
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部