当前位置：首页 > news >正文

jQuery custom content scroller滚动条控件代码 - 教程

news 2026/5/11 15:42:56

How to use it

Get started by downloading the archive which contains the plugin files (and a large amount of HTML demos and examples). Extract and upload jquery.mCustomScrollbar.concat.min.js, jquery.mCustomScrollbar.css and mCSB_buttons.png to your web server (alternatively you can load plugin files from a CDN).

HTML

Include jquery.mCustomScrollbar.css in the head tag your HTML document (more info)

Include jQuery library (if your project doesn’t use it already) and jquery.mCustomScrollbar.concat.min.js in the head tag or at the very bottom of your document, just before the closing body tag

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<script src="/path/to/jquery.mCustomScrollbar.concat.min.js"></script>

CSS

The element(s) you want to add scrollbar(s) should have the typical CSS properties of an overflowed block which are a height (or max-height) value, an overflow value of auto (or hidden) and content long enough to require scrolling. For horizontal scrollbar, the element should have a width (or max-width) value set.

If you prefer to set your element’s height/width via javascript, you can use the setHeight/setWidth option parameters.

Initialization

Initialize via javascript

After files inclusion, call mCustomScrollbar function on the element selector you want to add the scrollbar(s)

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

more info

Initialize via HTML

Add the class mCustomScrollbar to any element you want to add custom scrollbar(s) with default options. Optionally, set its axis via the HTML data attribute data-mcs-axis (e.g. "x" for horizontal and "y" for vertical) and its theme via data-mcs-theme. For example:

Basic configuration & option parameters

axis

By default, the script applies a vertical scrollbar. To add a horizontal or 2-axis scrollbars, invoke mCustomScrollbar function with the axis option set to "x" or "yx" respectively

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

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

theme

To quickly change the appearance of the scrollbar, set the theme option parameter to any of the ready-to-use themes available in jquery.mCustomScrollbar.css, for example:

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

Configuration

You can configure your scrollbar(s) using the following option parameters on mCustomScrollbar function
Usage$(selector).mCustomScrollbar({ option: value });

setWidth: false

Set the width of your content (overwrites CSS width), value in pixels (integer) or percentage (string).

setHeight: false

Set the height of your content (overwrites CSS height), value in pixels (integer) or percentage (string).

setTop: 0

Set the initial css top property of content, accepts string values (css top position).
Example: setTop: "-100px".

setLeft: 0

Set the initial css left property of content, accepts string values (css left position).
Example: setLeft: "-100px".

axis: "string"

Define content’s scrolling axis (the type of scrollbars added to the element: vertical and/of horizontal).
Available values: "y", "x", "yx".

axis: "y" – vertical scrollbar (default)
axis: "x" – horizontal scrollbar
axis: "yx" – vertical and horizontal scrollbars

scrollbarPosition: "string"

Set the position of scrollbar in relation to content.
Available values: "inside", "outside".
Setting scrollbarPosition: "inside" (default) makes scrollbar appear inside the element. Setting scrollbarPosition: "outside" makes scrollbar appear outside the element. Note that setting the value to "outside" requires your element (or parent elements) to have CSS position: relative (otherwise the scrollbar will be positioned in relation to document’s root element).

scrollInertia: integer

Set the amount of scrolling momentum as animation duration in milliseconds.
Higher value equals greater scrolling momentum which translates to smoother/more progressive animation. Set to 0 to disable.

autoDraggerLength: boolean

Enable or disable auto-adjusting scrollbar dragger length in relation to scrolling amount (same bahavior with browser’s native scrollbar).
Set autoDraggerLength: false when you want your scrollbar to (always) have a fixed size.

autoHideScrollbar: boolean

Enable or disable auto-hiding the scrollbar when inactive.
Setting autoHideScrollbar: true will hide the scrollbar(s) when scrolling is idle and/or cursor is out of the scrolling area.
Please note that some special themes like “minimal” overwrite this option.

autoExpandScrollbar: boolean

Enable or disable auto-expanding the scrollbar when cursor is over or dragging the scrollbar.

alwaysShowScrollbar: integer

Always keep scrollbar(s) visible, even when there’s nothing to scroll.

alwaysShowScrollbar: 0 – disable (default)
alwaysShowScrollbar: 1 – keep dragger rail visible
alwaysShowScrollbar: 2 – keep all scrollbar components (dragger, rail, buttons etc.) visible

snapAmount: integer

Make scrolling snap to a multiple of a fixed number of pixels. Useful in cases like scrolling tabular data, image thumbnails or slides and you need to prevent scrolling from stopping half-way your elements. Note that your elements must be of equal width or height in order for this to work properly.
To set different values for vertical and horizontal scrolling, use an array: [y,x]

snapOffset: integer

Set an offset (in pixels) for the snapAmount option. Useful when for example you need to offset the snap amount of table rows by the table header.

mouseWheel:{ enable: boolean }

Enable or disable content scrolling via mouse-wheel.

mouseWheel:{ scrollAmount: integer }

Set the mouse-wheel scrolling amount (in pixels). The default value "auto" adjusts scrolling amount according to scrollable content length.

mouseWheel:{ axis: "string" }

Define the mouse-wheel scrolling axis when both vertical and horizontal scrollbars are present.
Set axis: "y" (default) for vertical or axis: "x" for horizontal scrolling.

mouseWheel:{ preventDefault: boolean }

Prevent the default behaviour which automatically scrolls the parent element when end or beginning of scrolling is reached (same bahavior with browser’s native scrollbar).

mouseWheel:{ deltaFactor: integer }

Set the number of pixels one wheel notch scrolls. The default value “auto” uses the OS/browser value.

mouseWheel:{ normalizeDelta: boolean }

Enable or disable mouse-wheel (delta) acceleration. Setting normalizeDelta: true translates mouse-wheel delta value to -1 or 1.

mouseWheel:{ invert: boolean }

Invert mouse-wheel scrolling direction. Set to true to scroll down or right when mouse-wheel is turned upwards.

mouseWheel:{ disableOver: [array] }

Set the tags that disable mouse-wheel when cursor is over them.
Default value:

["select","option","keygen","datalist","textarea"]

scrollButtons:{ enable: boolean }

Enable or disable scrollbar buttons.

scrollButtons:{ scrollAmount: integer }

Set the buttons scrolling amount (in pixels). The default value "auto" adjusts scrolling amount according to scrollable content length.

scrollButtons:{ scrollType: "string" }

Define the buttons scrolling type/behavior.

scrollType: "stepless" – continuously scroll content while pressing the button (default)
scrollType: "stepped" – each button click scrolls content by a certain amount (defined in scrollAmount option above)

scrollButtons:{ tabindex: integer }

Set a tabindex value for the buttons.

keyboard:{ enable: boolean }

Enable or disable content scrolling via the keyboard.
The plugin supports the directional arrows (top, left, right and down), page-up (PgUp), page-down (PgDn), Home and End keys.

keyboard:{ scrollAmount: integer }

Set the keyboard arrows scrolling amount (in pixels). The default value "auto" adjusts scrolling amount according to scrollable content length.

keyboard:{ scrollType: "string" }

Define the keyboard arrows scrolling type/behavior.

scrollType: "stepless" – continuously scroll content while pressing the arrow key (default)
scrollType: "stepped" – each key release scrolls content by a certain amount (defined in scrollAmount option above)

contentTouchScroll: integer

Enable or disable content touch-swipe scrolling for touch-enabled devices.
To completely disable, set contentTouchScroll: false.
Integer values define the axis-specific minimum amount required for scrolling momentum (default: 25).

documentTouchScroll: boolean

Enable or disable document touch-swipe scrolling for touch-enabled devices.

advanced:{ autoExpandHorizontalScroll: boolean }

Auto-expand content horizontally (for "x" or "yx" axis).
If set to true, content will expand horizontally to accommodate any floated/inline-block elements.
Setting its value to 2 (integer) forces the non scrollHeight/scrollWidth method. A value of 3 forces the scrollHeight/scrollWidth method.

advanced:{ autoScrollOnFocus: "string" }

Set the list of elements/selectors that will auto-scroll content to their position when focused.
For example, when pressing TAB key to focus input fields, if the field is out of the viewable area the content will scroll to its top/left position (same bahavior with browser’s native scrollbar).
To completely disable this functionality, set autoScrollOnFocus: false.
Default:

"input,textarea,select,button,datalist,keygen,a[tabindex],area,object,[contenteditable='true']"

advanced:{ updateOnContentResize: boolean }

Update scrollbar(s) automatically on content, element or viewport resize.
The value should be true (default) for fluid layouts/elements, adding/removing content dynamically, hiding/showing elements etc.

advanced:{ updateOnImageLoad: boolean }

Update scrollbar(s) automatically each time an image inside the element is fully loaded.
Default value is auto which triggers the function only on "x" and "yx" axis (if needed).
The value should be true when your content contains images and you need the function to trigger on any axis.

advanced:{ updateOnSelectorChange: "string" }

Update scrollbar(s) automatically when the amount and size of specific selectors changes.
Useful when you need to update the scrollbar(s) automatically, each time a type of element is added, removed or changes its size.
For example, setting updateOnSelectorChange: "ul li" will update scrollbars each time list-items inside the element are changed.
Setting the value to true, will update scrollbars each time any element is changed.
To disable (default) set to false.

advanced:{ extraDraggableSelectors: "string" }

Add extra selector(s) that’ll release scrollbar dragging upon mouseup, pointerup, touchend etc.
Example: extraDraggableSelectors: ".myClass, #myID"

advanced:{ releaseDraggableSelectors: "string" }

Add extra selector(s) that’ll allow scrollbar dragging upon mousemove/up, pointermove/up, touchend etc.
Example: releaseDraggableSelectors: ".myClass, #myID"

advanced:{ autoUpdateTimeout: integer }

Set the auto-update timeout in milliseconds.
Default timeout: 60

theme: "string"

Set the scrollbar theme.
View all ready-to-use themes
All themes are contained in plugin’s CSS file (jquery.mCustomScrollbar.css).
Default theme: "light"

callbacks:{onCreate: function(){}
}

A function to call when plugin markup is created.
Example:

callbacks:{onCreate:function(){console.log("Plugin markup generated");}
}

callbacks:{onInit: function(){}
}

A function to call when scrollbars have initialized (demo).
Example:

callbacks:{onInit:function(){console.log("Scrollbars initialized");}
}

callbacks:{onScrollStart: function(){}
}

A function to call when scrolling starts (demo).
Example:

callbacks:{onScrollStart:function(){console.log("Scrolling started...");}
}

callbacks:{onScroll: function(){}
}

A function to call when scrolling is completed (demo).
Example:

callbacks:{onScroll:function(){console.log("Content scrolled...");}
}

callbacks:{whileScrolling: function(){}
}

A function to call while scrolling is active (demo).
Example:

callbacks:{whileScrolling:function(){console.log("Scrolling...");}
}

callbacks:{onTotalScroll: function(){}
}

A function to call when scrolling is completed and content is scrolled all the way to the end (bottom/right) (demo).
Example:

callbacks:{onTotalScroll:function(){console.log("Scrolled to end of content.");}
}

callbacks:{onTotalScrollBack: function(){}
}

A function to call when scrolling is completed and content is scrolled back to the beginning (top/left) (demo).
Example:

callbacks:{onTotalScrollBack:function(){console.log("Scrolled back to the beginning of content.");}
}

callbacks:{onTotalScrollOffset: integer
}

Set an offset for the onTotalScroll option.
For example, setting onTotalScrollOffset: 100 will trigger the onTotalScroll callback 100 pixels before the end of scrolling is reached.

callbacks:{onTotalScrollBackOffset: integer
}

Set an offset for the onTotalScrollBack option.
For example, setting onTotalScrollBackOffset: 100 will trigger the onTotalScrollBack callback 100 pixels before the beginning of scrolling is reached.

callbacks:{alwaysTriggerOffsets: boolean
}

Set the behavior of calling onTotalScroll and onTotalScrollBack offsets.
By default, callback offsets will trigger repeatedly while content is scrolling within the offsets.
Set alwaysTriggerOffsets: false when you need to trigger onTotalScroll and onTotalScrollBack callbacks once, each time scroll end or beginning is reached.

callbacks:{onOverflowY: function(){}
}

A function to call when content becomes long enough and vertical scrollbar is added.
Example:

callbacks:{onOverflowY:function(){console.log("Vertical scrolling required");}
}

callbacks:{onOverflowX: function(){}
}

A function to call when content becomes wide enough and horizontal scrollbar is added.
Example:

callbacks:{onOverflowX:function(){console.log("Horizontal scrolling required");}
}

callbacks:{onOverflowYNone: function(){}
}

A function to call when content becomes short enough and vertical scrollbar is removed.
Example:

callbacks:{onOverflowYNone:function(){console.log("Vertical scrolling is not required");}
}

callbacks:{onOverflowXNone: function(){}
}

A function to call when content becomes narrow enough and horizontal scrollbar is removed.
Example:

callbacks:{onOverflowXNone:function(){console.log("Horizontal scrolling is not required");}
}

callbacks:{onBeforeUpdate: function(){}
}

A function to call right before scrollbar(s) are updated.
Example:

callbacks:{onBeforeUpdate:function(){console.log("Scrollbars will update");}
}

callbacks:{onUpdate: function(){}
}

A function to call when scrollbar(s) are updated.
Example:

callbacks:{onUpdate:function(){console.log("Scrollbars updated");}
}

callbacks:{onImageLoad: function(){}
}

A function to call each time an image inside the element is fully loaded and scrollbar(s) are updated.
Example:

callbacks:{onImageLoad:function(){console.log("Image loaded");}
}

callbacks:{onSelectorChange: function(){}
}

A function to call each time a type of element is added, removed or changes its size and scrollbar(s) are updated.
Example:

callbacks:{onSelectorChange:function(){console.log("Scrollbars updated");}
}

live: "string"

Enable or disable applying scrollbar(s) on all elements matching the current selector, now and in the future.
Set live: true when you need to add scrollbar(s) on elements that do not yet exist in the page. These could be elements added by other scripts or plugins after some action by the user takes place (e.g. lightbox markup may not exist untill the user clicks a link).
If you need at any time to disable or enable the live option, set live: "off" and "on" respectively.
You can also tell the script to disable live option after the first invocation by setting live: "once".

liveSelector: "string"

Set the matching set of elements (instead of the current selector) to add scrollbar(s), now and in the future.

Plugin methods

Ways to execute various plugin actions programmatically from within your script(s).

update

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

Call the update method to manually update existing scrollbars to accommodate new content or resized element(s). This method is by default called automatically by the script (via updateOnContentResize option) when the element itself, its content or scrollbar size changes.

view examples

scrollTo

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

Call the scrollTo method to programmatically scroll the content to the position parameter (demo).

position parameter

Position parameter can be:

"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; }