ustbhuangyi /better-scroll
:scroll: inspired by iscroll, and it supports more features and has a better scroll perfermance
★ 16,427⑂ 2,575👁 254⑃ 213● 1,160▤ 42
-1
Daily
16,427
stars
2,575
forks
254
watchers
213
prs
1,160
issues
42
releases
README
better-scroll
中文文档
1.x Docs
2.x Docs
2.x Demo
Note: 1.x is not maintained. please migrate your version as soon as possible
Install
bash
npm install better-scroll -S install 2.x,with full-featured plugin.
npm install @better-scroll/core only CoreScroll
js
import BetterScroll from 'better-scroll'
let bs = new BetterScroll('.wrapper', {
movable: true,
zoom: true
})
import BScroll from '@better-scroll/core'
let bs = new BScroll('.wrapper', {})
CDN
BetterScroll with full-featured plugin.
html
js
let wrapper = document.getElementById("wrapper")
let bs = BetterScroll.createBScroll(wrapper, {})
Only CoreScroll
html
js
let wrapper = document.getElementById("wrapper")
let bs = new BScroll(wrapper, {})
What is BetterScroll ?
BetterScroll is a plugin which is aimed at solving scrolling circumstances on the mobile side (PC supported already). The core is inspired by the implementation of iscroll, so the APIs of BetterScroll are compatible with iscroll on the whole. What's more, BetterScroll also extends some features and optimizes for performance based on iscroll.
BetterScroll is implemented with plain JavaScript, which means it's dependency free.
Getting started
The most common application scenario of BetterScroll is list scrolling. Let's see its HTML:
html
...
...
...
In the code above, BetterScroll is applied to the outer wrapper container, and the scrolling part is content element. Pay attention that BetterScroll handles the scroll of the first child element (content) of the container (wrapper) by default, which means other elements will be ignored. However, for BetterScroll v2.0.4, content can be specified through the specifiedIndexAsContent option. Please refer to the docs for details.
The simplest initialization code is as follow:
javascript
import BScroll from '@better-scroll/core'
let wrapper = document.querySelector('.wrapper')
let scroll = new BScroll(wrapper)
BetterScroll provides a class whose first parameter is a plain DOM object when instantiated. Certainly, BetterScroll inside would try to use querySelector to get the DOM object.
The principle of scrolling
Many developers have used BetterScroll, but the most common problem they have met is:
I have initiated BetterScroll, but the content can't scroll.
The phenomenon is 'the content can't scroll' and we need to figure out the root cause. Before that, let's take a look at the browser's scrolling principle: everyone can see the browser's scroll bar. When the height of the page content exceeds the viewport height, the vertical scroll bar will appear; When the width of page content exceeds the viewport width, the horizontal bar will appear. That is to say, when the viewport can't display all the content, the browser would guide the user to scroll the screen with scroll bar to see the rest of content.
The principle of BetterScroll is samed as the browser. We can feel about this more obviously using a pictuTop issues
#580IOS设备滑动时,手动按住停止时有抖动现象23 comments · 2018-06-12#658希望出一个 react版本的demo11 comments · 2018-09-13#1042文档无法访问6 comments · 2020-08-07#736[New Feature] 向上无限滚动6 comments · 2019-01-22#1165[New Feature] 无限滚动,fetch 数据返回resolve(false)后,后续有新的数据,如何再次触发 fetch ?5 comments · 2021-03-17#1224[New Feature] 希望能实现类似饿了么首页那样的多层嵌套滚动选项卡4 comments · 2021-07-09#895infinity不支持水平滚动4 comments · 2019-09-09#1376How can BetterScroll disable scrolling without affecting click events when click is enabled?3 comments · 2024-11-06
Latest release
v2.4.2 v2.4.2 2021-08-02BUG FIX - mouse-wheel: closed 1227