README

简约但完美的自定义滚动条插件

如果您想获取旧版本（<0.6.0）的信息，请参阅旧版文档。

为什么是 perfect-scrollbar？

我曾经在一个个人项目中工作，试图找到一个完美（完美）的 jQuery 滚动条插件。但是没有一个是完美的。这就是我决定自己制作一个的原因。

perfect-scrollbar 是简约但完美的（对我来说，也许对大多数开发者来说也是如此）滚动条插件，它可以使用 jQuery 或纯 JavaScript 与之协同工作。

我希望你喜欢它！

演示

在 GitHub Pages 上.

“完美”意味着什么？

完美意味着...

不应该对任何原始元素进行 css 变更。
滚动条不应该影响原始设计布局。
滚动条的设计应该是（几乎）完全可定制的。
如果容器或内容的大小发生变化，滚动条的大小和位置应该能够改变。
新功能！它应该能与纯 JavaScript 和主要工具（如 NPM 或 Browserify）协同工作。

那么 perfect-scrollbar 真的是“完美”吗？

perfect-scrollbar 有一些要求，但不会更改或添加原始元素的任何样式。
perfect-scrollbar 设计上没有宽度或高度。它固定在容器的右下角。
您可以更改滚动条的几乎所有 CSS 样式。滚动条设计不依赖于脚本。
perfect-scrollbar 支持一个“更新”函数。每次您需要更新滚动条的大小或位置时，只需更新即可。
此外，perfect-scrollbar 使用“scrollTop”和“scrollLeft”，而不是绝对定位或其他混乱的方式。
perfect-scrollbar 在基于 WebKit 和 Gecko 的浏览器上都完美支持 RTL。

很酷，不是吗？

安装

安装和使用 perfect-scrollbar 的最佳方式是使用 NPM。它在npm上注册为 perfect-scrollbar。

$ npm install perfect-scrollbar

您可以通过以下下载链接下载最新稳定版本这里。您也可以在发布中找到所有版本。

如果您想使用插件的开发版本，请使用未压缩的源文件。它们位于 src 目录中。开发版本可能是不稳定的，但一些已知的错误可能已被修复。

$ git clone https://github.com/noraesae/perfect-scrollbar.git
$ cd perfect-scrollbar/src
$ npm install
$ gulp # will lint and build the source code.

perfect-scrollbar 还有一个 Bower 包。它在perfect-scrollbar-bower 存储库中管理。插件注册为 perfect-scrollbar。

$ bower install perfect-scrollbar

您也可以从cdnjs 加载它。它注册为 jquery.perfect-scrollbar。

要求

为了使此插件“完美”，一些要求不可避免。但是，它们都非常简单，无需担心。

以下要求应满足。

容器必须具有“位置”CSS样式。

以下要求包含在基本CSS中，但请注意当您想要更改CSS文件时。

容器必须有一个'overflow:hidden' CSS样式。
滚动条的定位必须为'absolute'。
scrollbar-x必须有一个'bottom' CSS样式，而scrollbar-y必须有一个'right' CSS样式。

如何使用

首先，请检查容器元素是否符合要求。

<link rel='stylesheet' href='dist/css/perfect-scrollbar.css' />
<style>
  #container {
    position: relative;
    height: 100%; /* Or whatever you want (eg. 400px) */
  }
</style>

我建议使用NPM和CommonJS模块系统（如Browserify）来使用此插件。

var Ps = require('perfect-scrollbar');

或者您也可以像往常一样加载脚本文件。

<script src='dist/js/perfect-scrollbar.js'></script>

要初始化插件，请使用Ps.initialize。

var container = document.getElementById('container');
Ps.initialize(container);

它可以与可选参数一起初始化。

Ps.initialize(container, {
  wheelSpeed: 2,
  wheelPropagation: true,
  minScrollbarLength: 20
});

如果您的容器或内容大小发生变化，请调用update。

Ps.update(container);

如果您想销毁滚动条，请使用destroy。

Ps.destroy(container);

如果您想滚动到某个地方，只需使用scrollTop属性并更新。

container.scrollTop = 0;
Ps.update(container);

您也可以从源树中的examples目录中的代码中获取有关如何使用插件的信息。

jQuery

如您所知，perfect-scrollbar曾经是一个jQuery插件。现在它依然是。有一个jQuery适配器，插件可以使用与以前相同的方式进行使用。

我也建议在这里使用NPM和CommonJS，但这不是强制性的。

var $ = require('jquery');
require('perfect-scrollbar/jquery')($);

当然，您可以直接导入一个构建好的脚本。

<script src='dist/js/perfect-scrollbar.jquery.js'></script>

导入后，您可以使用插件的方式与通常一样。

$('#container').perfectScrollbar();          // Initialize
$('#container').perfectScrollbar({ ... });   // with options
$('#container').perfectScrollbar('update');  // Update
$('#container').perfectScrollbar('destroy'); // Destroy

RequireJS使用

对于RequireJS加载器，无需编写shim，只需导入两个库

require.config({
  paths: {
    perfectScrollbarJQuery: '.../perfect-scrollbar.jquery',
    perfectScrollbar: '.../perfect-scrollbar',
  }
  ...
})

并在您的应用程序初始化器中加载perfectScrollbar。

# for vanilla JS:
window.Ps = require('perfectScrollbar');

# for jQuery:
require('perfectScrollbarJQuery');

AngularJS + RequireJS使用

在上述require.config设置下，在您的应用程序模块定义的开始处，您可以有以下代码

define([
  'angular',
  'perfectScrollbar',
  'perfectScrollbarJquery'
],
function (angular) {
  var myApp = angular.module('myApp', [])
  .run(function() {
    window.Ps = require('perfectScrollbar');
    require('perfectScrollbarJQuery');
  })
  return myApp;
});

并在控制器中初始化perfectScrollbar。

# by vanilla JS:
var container = document.getElementById('imgLoader');
Ps.initialize(container);
Ps.update(container);

# or by jQuery:
var imgLoader = $("#imgLoader")
imgLoader.perfectScrollbar();

可选参数

perfect-scrollbar支持可选参数。

wheelSpeed

应用于鼠标滚轮事件的滚动速度。
默认值：1

wheelPropagation

如果此选项为true，当滚动到边缘时，鼠标滚轮事件将被传播到父元素。
默认值：false

swipePropagation

如果此选项为true，当滚动到边缘时，触摸滚动将被传播到父元素。
默认值：true

minScrollbarLength

当设置为整数值时，滚动条的滑块部分不会缩小到该像素数以下。
默认值：null

maxScrollbarLength

当设置为整数值时，滚动条的滑块部分不会扩大到该像素数以上。
默认值：null

useBothWheelAxes

当设置为true时，并且只有一个（垂直或水平）滚动条可见时，垂直和水平滚动都会影响滚动条。
默认值：false

useKeyboard

当设置为true时，滚动可以使用键盘上的箭头键。只有当鼠标光标悬停在元素上时，元素才会滚动。
默认值：true

suppressScrollX

当设置为true时，X轴上的滚动条将不可用，无论内容宽度如何。
默认值：false

suppressScrollY

当设置为true时，Y轴上的滚动条将不可用，无论内容高度如何。
默认值：false

scrollXMarginOffset

内容宽度可以超过容器宽度多少像素而不启用X轴滚动条。允许一些“弹性空间”或“偏移量”，以便X轴滚动条不会因为几像素而启用。
默认值：0

scrollYMarginOffset

内容高度可以超过容器高度多少像素而不启用Y轴滚动条。允许一些“弹性空间”或“偏移量”，以便Y轴滚动条不会因为几像素而启用。
默认值：0

stopPropagationOnClick

当设置为false时，当点击轨道时，点击事件将被允许传播。
默认值：true

贡献

在做出任何贡献之前，请阅读贡献中的wiki。

我非常欢迎贡献！当...时，请随意分叉并提交pull请求！

您有一个非常好的想法来改进这个插件！
您发现了一个bug！
您擅长英语，可以帮助我改正英语上的错误！

关于IE的问题，请参考IE支持。

IE支持

该插件可以在IE9及以上版本的IE中运行（尽管效果不是很好）。

不会接受用于修复IE8及以下版本问题的补丁。

当需要支持旧版本的IE时，请分叉项目并亲自制作补丁。

帮助台

如果您有任何改进此项目的想法或使用过程中遇到的问题，请随时上传一个问题。

对于常见问题，有一个常见问题解答（FAQ）页面。在提交问题之前，请检查该页面。

许可证

特此授予，任何获得此软件及其相关文档副本（“软件”）的人，免费使用该软件的权利，不受限制，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本的权利，以及允许向软件提供的人这样做，前提是遵守以下条件

ingenious / perfect-scrollbar

维护者

详细信息