滚动条插件 mCustomScrollbar 使用介绍

2016-08-07 本文已影响21155人爱鸽子的玉米君

用法

HTML

在HTML文档头部引入mCustomScrollbar.css

<head>
    <meta charset="UTF-8">
    <title>Document</title>
    <link rel="stylesheet" href="/path/to/jquery.mCustomScrollbar.css" />
</head>

在body的结束标签之前引入插件所需js文件

<script src="/path/to/jquery/1.11.1/jquery.min.js"></script>
<script src="/path/to/jquery.mCustomScrollbar.concat.min.js"></script>

CSS

需要创建滚动条的元素必须具有明确的CSS属性使元素形成包裹的块级元素：

具有高度值（height）
最大高度值（max-height）
具有overflow属性值为auto或者hidden
元素的内容具有足够的高度（或宽度，针对横向滚动条）

初始化

通过JavaScript初始化

把相关的文件加载进页面之后，call mCustomScrollbar function on the element selector you want to add the scrollbar(s)

<script>
    (function($){
        $(window).on("load",function(){
            $(".content").mCustomScrollbar();
        });
    })(jQuery);
</script>

通过HTML初始化

在你需要创建自定义滚动条的元素的标签里添加默认的class="mCustomScrollbar"类，同时你可以根据需要的设置它的 axis 通过 HTML 的 data-msc-axis 属性，例如属性值为"x" 代表水平滚动条，属性值为 "y"代表垂直滚动条。或者设置它的主题通过HTML的 data-msc-theme属性。
举个例子~

<div class="mCustomScrollbar" data-mcs-theme="dark">
  <!-- your content -->
</div>

基础设置和可选参数

axis

插件默认情况下会生成垂直方向的滚动条。如果要创建水平或水平垂直两个方向的滚动条的话，可以在mCustomScrollbar的函数里将axis的选项设置为"x"或"yx"，例如

$(".content").mCustomScrollbar({
    axis:"x" // horizontal scrollbar
});
$(".content").mCustomScrollbar({
    axis:"yx" // vertical and horizontal scrollbar
});

theme

要快速改变滚动条的外观，可以设置 theme 选项的参数为任何一种已经在 jquery.mCustomScrollbar.css 中定义好的主题，例如

$(".content").mCustomScrollbar({
    theme:"dark"
});

基本的插件使用就介绍到这里，接下来我将针对插件的部分设置进行介绍

配置

你可以通过下面的可选参数来配置你创建的滚动条（只介绍项目中实际使用到的）

用法 $(selector).mCustomScrollbar({ option: value });

scrollInertia: integer： 设置滚动条的滚动动量，它将会作为滚动动画的持续时间（以毫秒计算），越高的数值会让滚动条滚动得更加平滑，将它的值设置为0可以禁止滚动动画
autoHideScrollbar: boolean： 设置是否自动隐藏滚动条
alwaysShowScrollbar: integer： 设置是否一直显示滚动条
mouseWheel:{ preventDefault:true }： 阻止滚动条滚动到顶部或者底部时自动带动父级元素的滚动条往上滚动的表现（这和浏览器自身的滚动条的表现是一致的）

插件的方法

通过以下的方法你可以利用你的脚本代码执行插件的各种变化

update

用法 $(selector).mCustomScrollbar("update");

调用插件的 update方法来手动让存在的滚动条来更新适应新的内容或者重新设置元素的大小。当元素自身的的内容或滚动条尺寸变化时，这个方法默认是由插件（的updateOnContentResize选项来）自动调用的。

scrollTo

用法 $(selector).mCustomScrollbar("scrollTo",position,options);

调用scrollTo方法来将内容滚动到设定好的位置参数

position parameter（位置参数）

位置参数可以是：

"string"

e.g. element selector: "#element-id"
e.g. special pre-defined position: "bottom"
e.g. number of pixels less/more: "-=100"/"+=100"

integer

e.g. number of pixels: 100
[array]
e.g. different y/x position: [100,50]

object/function

e.g. jQuery object: $("#element-id")
e.g. js object: document.getelementbyid("element-id")
e.g. function: function(){ return 100; }

Pre-defined position strings:

"bottom" – scroll to bottom
"top" – scroll to top
"right" – scroll to right
"left" – scroll to left
"first" – scroll to the position of the first element within content
"last" – scroll to the position of the last element within content

Method options（方法选项）

scrollInertia: integer

Scroll-to事件的持续时间（毫秒计）

例子：

$(selector).mCustomScrollbar("scrollTo","bottom",{
scrollInertia:3000
});

scrollEasing: "string"

Scroll-to时间的动画过渡效果,可以是: "linear", "easeOut", "easeInOut".

例子：

$(selector).mCustomScrollbar("scrollTo","bottom",{
scrollEasing:"easeOut"
});

moveDragger: boolean

Scroll scrollbar dragger (instead of content).

例子：

$(selector).mCustomScrollbar("scrollTo",80,{
moveDragger:true
});

timeout: integer

为方法设定计时器(默认的计时器是60ms以便配合和滚动条的自动更新事件)

例子：

$(selector).mCustomScrollbar("scrollTo","top",{
timeout:1000
});
callbacks: boolean
Trigger user defined callbacks after scroll-to completes.

例子：

$(selector).mCustomScrollbar("scrollTo","left",{
callbacks:false
});

stop

用法 $(selector).mCustomScrollbar("stop");

停止当前任何正在运行的滚动事件 (当你希望阻止之前的 scrollTo 方法的调用时很有用).

disable

用法 $(selector).mCustomScrollbar("disable");

调用 disable 方法将会暂时的禁用滚动条

被禁用掉的滚动条可以通过重新调用 update 方法来启用
为了禁止滚动条并且重置它的内容所处的位置，设置它的方法的 reset 参数为 true

$(selector).mCustomScrollbar("disable",true);

destroy

用法 $(selector).mCustomScrollbar("destroy");

Calling destroy method will completely remove the custom scrollbar and return the element to its original state (demo).

滚动条样式和主题

作为一款可以高度自定义的滚动条插件，自己定义滚动条样式和主题当然是必不可少的功能
你可以通过纯 CSS 设计并且可视化的自定义你的滚动条，也可以使用 jquery.mCustomScrollbar.css 中具有的默认和基础样式以及所有的滚动条主题
最便捷的方式是选择一个已经定义好的滚动条主题，举个例子：

$(selector).mCustomScrollbar({
  theme:"dark"
});

详细的自定义方法可参考官方文档

以上为笔者薄力选译，如有疏忽翻译错漏之处，还请读者指正。