文档章节

jQuery custom content scroller

lgscofield
 lgscofield
发布于 2015/06/26 13:58
字数 2520
阅读 72
收藏 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

粉丝 23
博文 140
码字总数 63036
作品 0
南京
架构师
私信 提问
15 个免费的 jQuery 网页滚动插件

这里向你推荐 15 个用 jQuery 开发的网页滚动插件,可实现很酷炫的网页滚动效果: Endless Scroll Demo | Download Perfect-Scrollbar Demo | Download JQuery.ScrollTo Demo | Download Ani...

oschina
2015/04/23
7.2K
3
mCustomScrollbar 鼠标无法滚动

网页中设置了 jQuery custom content scroller 后,发现鼠标无法滚动了,可以拖动滚动条进行上下滚动,在线等各位大牛解释哈,谢谢了!

Xiaopeng
2014/08/17
887
2
40 个内容图片旋转滑块和幻灯的 jQuery 插件

All Around – jQuery Content Slider / Carousel All in one Slider jQuery Banner Rotator / Content Slider Full Width Slider 2 Layer Slider (Must see parallax effects) Lush – Cont......

oschina
2013/07/16
3.8K
5
55 个超强的 jQuery 导航菜单插件

不再翻译了,大家看截图: 1. mb.verticalSlider jquery.mb.verticalSlider lets you show a long list of elements managing pagination, it can work with elements already in the DOM of......

红薯
2011/03/01
2.7K
2
11 个专业的 jQuery 内容滑动插件

Responsive Image Gallery with Thumbnail Carousel Elastic Image Slideshow with Thumbnail Preview FlexSlider – The Best Responsive jQuery Slider jQuery Responsive Thumbnail Gall......

红薯
2012/02/15
6.7K
3

没有更多内容

加载失败,请刷新页面

加载更多

iOS个人中心渐变动画、微信对话框、标签选择器、自定义导航栏、短信验证输入框等源码

iOS精选源码 简单的个人中心页面-自定义导航栏并予以渐变动画 程序员取悦女票的正确姿势---Tip1(iOS美容篇) iOS 前台重启应用和清除角标的问题 微信原生提醒对话框3.0 JHLikeButton - 有趣...

Android爱开源
15分钟前
0
0
Yii2使用驼峰命名的形式访问控制器

yii2在使用的时候,访问控制器的时候,如果控制器的名称是驼峰命名法,那访问的url中要改成横线的形式。例如: public function actionRoomUpdate(){//}//访问的时候就要www.test.co...

dragon_tech
18分钟前
0
0
Navicat使用教程:使用Navicat Query Analyzer优化查询性能(第2部分)

下载Navicat Monitor最新版本 Navicat Monitor 是一套安全、简单而且无代理的远程服务器监控工具。它具有强大的功能使你的监控发挥最大效用。受监控的服务器包括 MySQL、MariaDB 和 Percona ...

电池盒
25分钟前
0
0
Python3 读写utf-8文本文件

with open('testRead.txt', 'r', encoding='utf-8') as f: for each_line in f: Passwith open('testWrite.txt', 'w', encoding='utf-8') as f: f.write('写入的内容'......

编程老陆
28分钟前
0
0
Linux syslog相关函数详解

介绍 syslog是Unix系统的日志系统。可以将日志记录在本地系统中。 一个完整的syslong日志包含如下信息:程序模块 | 严重性 | 时间 | 主机名 | 进程名 | 进程ID | 正文。 syslong相关函数 1....

RongJinhui0
32分钟前
0
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部