跳到主要内容

README

创建日期：2023-11-23 ｜ 最近更新：2023-11-23

仓库地址​

https://github.com/FL3NKEY/scroll-lock

Cross-browser JavaScript library to disable scrolling page

New features 2.0​

  • 更多 touch 事件处理的算法
  • 支持水平滚动
  • 支持嵌套的可滚动元素
  • 支持嵌套的 textarea 和 contenteditable
  • New API

安装​

npm install scroll-lock
# or
yarn add scroll-lock

//es6 import
import { disablePageScroll, enablePageScroll } from 'scroll-lock';

//or
import scrollLock from 'scroll-lock';
scrollLock.disablePageScroll();
//...

//require
const scrollLock = require('scroll-lock');
scrollLock.disablePageScroll();
//...
<script src="path/to/scroll-lock.min.js"></script>
<script>
  scrollLock.disablePageScroll();
  //...
</script>

当调用 disablePageScroll 时，会在 body 上添加一个 overflow:hidden 的样式，同时会在 body 上添加一个 data-scroll-lock-scrollable 的属性，用来标记当前页面是否被锁定。如果直接调用会导致所有的滚动都被禁用，所以需要传入一个参数来指定需要被禁用的元素。

scrollLock.disablePageScroll(document.querySelector('.my-scrollable-element'));
<div class="my-scrollable-element" data-scroll-lock-scrollable></div>

如果滚动元素中包含 textarea 或者 contenteditable，不用额外的处理也可以正常滚动

Live demo: https://fl3nkey.github.io/scroll-lock/demos/index.html#ex-inputs

填充滚动条​

当滚动条被隐藏，在一些浏览器中存在实际的宽度，这会导致页面抖动。当调用 disablePageScroll 时，会在 body 上添加一个 padding-right 的样式，用来填充滚动条的宽度，以防止页面抖动。如果你的页面中有自定义的滚动条，可以通过 paddingRight 参数来禁用这个特性。但是对 fixed 元素无效，此时你必须指定需要填充的元素。

import { addFillGapTarget, addFillGapSelector } from 'scroll-lock';

//selector
addFillGapSelector('.my-fill-gap-selector');

//element
const $fillGapElement = document.querySelector('.my-fill-gap-element');
addFillGapTarget($fillGapElement);

或者添加 data-scroll-lock-fill-gap 属性

<div class="my-fill-gap-element" data-scroll-lock-fill-gap></div>

Live demo: https://fl3nkey.github.io/scroll-lock/demos/index.html#ex-fill-gap

队列问题​

disablePageScroll 和 enablePageScroll 是通过计数器来实现的，所以可以多次调用，但是必须成对出现，否则会导致页面无法滚动。如果你需要在多个地方调用，可以使用 clearQueueScrollLocks 来清除队列。

import { disablePageScroll, clearQueueScrollLocks } from 'scroll-lock';

disablePageScroll();
disablePageScroll();
disablePageScroll();
disablePageScroll();

enablePageScroll();
console.log(getScrollState()); //false

clearQueueScrollLocks();
enablePageScroll();
console.log(getScrollState()); //true

API​

disablePageScroll(scrollableTarget)​

Hides the scroll bar and disables page scrolling.

  • scrollableTarget - (HTMLElement | NodeList | HTMLElement array) scrollable element
import { disablePageScroll } from 'scroll-lock';

const $scrollableElement = document.querySelector('.my-scrollable-element');
disablePageScroll($scrollableElement);

enablePageScroll(scrollableTarget)​

Shows the scroll bar and enables page scrolling.

  • scrollableTarget - (HTMLElement | NodeList | HTMLElement array) scrollable element
import { enablePageScroll } from 'scroll-lock';

const $scrollableElement = document.querySelector('.my-scrollable-element');
enablePageScroll($scrollableElement);

getScrollState()​

Returns the state of the page scroll bar.

import { disablePageScroll, getScrollState } from 'scroll-lock';

console.log(getScrollState()); //true
disablePageScroll();
console.log(getScrollState()); //false

clearQueueScrollLocks()​

Clears the queue value.

import { disablePageScroll, enablePageScroll, clearQueueScrollLocks, getScrollState } from 'scroll-lock';

disablePageScroll();
disablePageScroll();
disablePageScroll();
disablePageScroll();

enablePageScroll();
console.log(getScrollState()); //false

clearQueueScrollLocks();
enablePageScroll();
console.log(getScrollState()); //true

getPageScrollBarWidth(onlyExists)​

Returns the width of the scroll bar.

  • onlyExists

  • (Boolean) only if scroll bar is exists < br > Default value: false

import { getPageScrollBarWidth } from 'scroll-lock';

document.body.style.overflow = 'scroll';
console.log(getPageScrollBarWidth()); //Number
disablePageScroll();
console.log(getPageScrollBarWidth(true)); //Number
document.body.style.overflow = 'hidden';
console.log(getPageScrollBarWidth()); //Number
console.log(getPageScrollBarWidth(true)); //0

getCurrentPageScrollBarWidth()​

Returns the width of the scroll bar to specific moment.

import { disablePageScroll, getCurrentPageScrollBarWidth } from 'scroll-lock';

console.log(getCurrentPageScrollBarWidth()); //Number
disablePageScroll();
console.log(getCurrentPageScrollBarWidth()); //0

addScrollableSelector(scrollableSelector)​

Makes elements with this selector scrollable.

  • scrollableSelector - (String | String array) scrollable selector < br > Initial value: ['[data-scroll-lock-scrollable]']
import { disablePageScroll, addScrollableSelector } from 'scroll-lock';

addScrollableSelector('.my-scrollable-selector');
disablePageScroll();

removeScrollableSelector(scrollableSelector)​

Makes elements with this selector not scrollable.

  • scrollableSelector - (String | String array) scrollable selector
import { removeScrollableSelector } from 'scroll-lock';

removeScrollableSelector('.my-scrollable-selector');

addScrollableTarget(scrollableTarget)​

Makes the element scrollable.

  • scrollableSelector - (HTMLElement | NodeList | HTMLElement array) scrollable element
import { disablePageScroll, addScrollableTarget } from 'scroll-lock';

const $scrollableElement = document.querySelector('.my-scrollable-element');
addScrollableTarget($scrollableElement);
disablePageScroll();

removeScrollableTarget(scrollableTarget)​

Makes the element not scrollable.

  • scrollableSelector - (HTMLElement | NodeList | HTMLElement array) scrollable element
import { removeScrollableTarget } from 'scroll-lock';

const $scrollableElement = document.querySelector('.my-scrollable-element');
removeScrollableTarget($scrollableElement);

addLockableSelector(lockableSelector)​

Makes elements with this selector lockable.

  • lockableSelector - (String | String array) lockable selector < br > Initial value: ['[data-scroll-lock-lockable]']
import { disablePageScroll, addLockableSelector } from 'scroll-lock';

addLockableSelector('.my-lockable-selector');
disablePageScroll();

addLockableTarget(lockableTarget)​

Makes the element lockable.

  • lockableTarget - (HTMLElement | NodeList | HTMLElement array) lockable element
import { disablePageScroll, addLockableTarget } from 'scroll-lock';

const $lockableElement = document.querySelector('.my-lockable-element');
addLockableTarget($lockableElement);
disablePageScroll();

addFillGapSelector(fillGapSelector)​

Fills the gap with elements with this selector.

  • fillGapSelector - (String | String array) a fill gap selector < br > Initial value: ['body', '[data-scroll-lock-fill-gap]']
import { addFillGapSelector } from 'scroll-lock';

addFillGapSelector('.my-fill-gap-selector');

removeFillGapSelector(fillGapSelector)​

Returns the gap for elements with this selector.

  • fillGapSelector - (String | String array) a fill gap selector
import { removeFillGapSelector } from 'scroll-lock';

removeFillGapSelector('.my-fill-gap-selector');

addFillGapTarget(fillGapTarget)​

Fills the gap at the element.

  • fillGapTarget - (HTMLElement | NodeList | HTMLElement array) a fill gap element
import { addFillGapTarget } from 'scroll-lock';

const $fillGapElement = document.querySelector('.my-fill-gap-element');
addScrollableTarget($fillGapElement);

removeFillGapTarget(fillGapTarget)​

Returns the gap at the element.

  • fillGapTarget - (HTMLElement | NodeList | HTMLElement array) a fill gap element
import { removeFillGapTarget } from 'scroll-lock';

const $fillGapElement = document.querySelector('.my-fill-gap-element');
removeFillGapTarget($fillGapElement);

setFillGapMethod(fillGapMethod)​

Changes the method of filling the gap. < br >

  • fillGapMethod - (String: 'padding', 'margin', 'width', 'max-width', 'none') gap-filling method < br > Default value: padding
import { setFillGapMethod } from 'scroll-lock';

setFillGapMethod('margin');

refillGaps()​

Recalculates filled gaps.

import { refillGaps } from 'scroll-lock';

refillGaps();

See also​