ustbhuangyi/better-scroll


scroll inspired by iscroll, and it supports more features and has a better scroll perfermance

https://better-scroll.github.io/docs/en-US/

License: MIT

Language: TypeScript

Keywords: better-performance, ios, iscroll, mobile-web, more-features, vue


better-scroll

npm version npm next Version downloads Build Status Package Quality codecov.io

中文文档

1.x Docs

2.x Docs

Note: The following code is the syntax of 2.x.

Install

npm install better-scroll -S # install 1.x
npm install better-scroll@next -S # install 2.x,with full-featured plugin.

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:

<div class="wrapper">
  <ul class="content">
    <li>...</li>
    <li>...</li>
    ...
  </ul>
  <!-- you can put some other DOMs here, it won't affect the scrolling
</div>

In the code above, BetterScroll is applied to the outer wrapper container, and the scrolling part is content element. Pay attention that BetterScroll only handles the scroll of the first child element (content) of the container (wrapper), which means other elements will be ignored.

The simplest initialization code is as follow:

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 picture:

布局

The green part is the wrapper, also known as the parent container, which has fixed height. The yellow part is the content, which is the first child element of the parent container and whose height would grow with the size of its content. Then, when the height of the content doesn't exceed the height of the parent container, the content would not scroll. Once exceeded, the content can be scrolled. That is the principle of BetterScroll.

Plugins

Enhance the ability of BetterScroll core scroll through plugins, such as

import BScroll from '@better-scroll/core'
import PullUp from '@better-scroll/pull-up'

let bs = new BScroll('.wrapper', {
  pullUpLoad: true
})

Please see for details, Plugins.

Using BetterScroll with MVVM frameworks

I wrote an article When BetterScroll meets Vue (in Chinese). I also hope that developers can contribute to share the experience of using BetterScroll with other frameworks.

A fantastic mobile ui lib implement by Vue: cube-ui

Using BetterScroll in the real project

If you want to learn how to use BetterScroll in the real project,you can learn my two practical courses(in Chinese)。

High imitating starvation takeout practical course base on Vue.js

Project demo address

QR Code

Music App advanced practical course base on Vue.js

Project demo address

QR Code

Project Statistics

Sourcerank 18
Repository Size 12.1 MB
Stars 10,376
Forks 2,154
Watchers 254
Open issues 44
Dependencies 1,710
Contributors 24
Tags 59
Created
Last updated
Last pushed

Top Contributors See all

HuangYi JiZhi Candy.J Amy tank0317 doly mood hu0950 LinGuang taoqf cloudstone wind-stone 王宏宇 Amy hezf XRene MondoGao David Lee KentonYu 郭世伟 薛定谔的猫

Packages Referencing this Repo

@better-scroll/nested-scroll
make your nested scrolls reconciliation
Latest release 2.0.0-beta.2 - Updated - 10.4K stars
@better-scroll/infinity
The ability to inject a infinity load for BetterScroll.
Latest release 2.0.0-beta.2 - Updated - 10.4K stars
@better-scroll/wheel
a BetterScroll plugin to imitate IOS Picker
Latest release 2.0.0-beta.2 - Updated - 10.4K stars
@better-scroll/mouse-wheel
support for MouseWheel in PC
Latest release 2.0.0-beta.2 - Updated - 10.4K stars
@better-scroll/scroll-bar
scrollbar is used to BetterScroll, which behaves like browser scrollbar
Latest release 2.0.0-beta.2 - Updated - 10.4K stars
@better-scroll/zoom
a BetterScroll plugin to enlarge or narrow
Latest release 2.0.0-beta.2 - Updated - 10.4K stars
@better-scroll/shared-utils
shared-utils for BetterScroll
Latest release 2.0.0-beta.2 - Updated - 10.4K stars
@better-scroll/core
Minimalistic core scrolling for BetterScroll, it is pure and tiny
Latest release 2.0.0-beta.2 - Updated - 10.4K stars
@dfeidao/bscroll
inspired by iscroll, and it has a better scroll perfermance
Latest release 1.0.1 - Published - 10.4K stars
better-scroll-touch-panel
inspired by iscroll, and it has a better scroll perfermance
Latest release 1.13.5 - Published - 10.4K stars
@feidao-factory/bscroll
inspired by iscroll, and it has a better scroll perfermance
Latest release 1.0.0 - Published - 10.4K stars
better-scroll
Full-featured BetterScroll
Latest release 2.0.0-beta.2 - Updated - 10.4K stars
@better-scroll/slide
a carousel effect triggered by BetterScroll
Latest release 2.0.0-beta.2 - Updated - 10.4K stars
@better-scroll/observe-dom
Dynamic recalculating container's size for BetterScroll
Latest release 2.0.0-beta.2 - Updated - 10.4K stars
@better-scroll/pull-down
pull down to refresh, behave likes App list refreshing
Latest release 2.0.0-beta.2 - Updated - 10.4K stars
@better-scroll/pull-up
pull up to load more data
Latest release 2.0.0-beta.2 - Updated - 10.4K stars

Recent Tags See all

v2.0.0-beta.2 August 28, 2019
v2.0.0-beta.1 August 28, 2019
v2.0.0-beta.0 August 26, 2019
v2.0.0-beta.0 August 26, 2019
v2.0.0-alpha.20 July 15, 2019
v2.0.0-alpha.19 July 09, 2019
v2.0.0-alpha.19 July 09, 2019
v2.0.0-alpha.18 July 04, 2019
v2.0.0-alpha.17 July 04, 2019
v2.0.0-alpha.16 July 01, 2019
v2.0.0-alpha.15 June 19, 2019
v2.0.0-alpha.14 June 13, 2019
v2.0.0-alpha.13 June 10, 2019
v2.0.0-alpha.12 June 02, 2019
v2.0.0-alpha.11 June 02, 2019

Interesting Forks See all

jinzaifeng/better-scroll
inspired by iscroll, and it has a better scroll perfermance
JavaScript - Updated - 2 stars
wangrui9217/better-scroll
scroll inspired by iscroll, and it supports more features and has a better scroll perfermance
JavaScript - MIT - Updated - 1 stars
xuCindy/better-scroll
scroll inspired by iscroll, and it supports more features and has a better scroll perfermance
JavaScript - MIT - Updated - 1 stars
liujingen/better-scroll
inspired by iscroll, and it has a better scroll perfermance
JavaScript - Updated - 1 stars
davy-gan/better-scroll
inspired by iscroll, and it has a better scroll perfermance
JavaScript - Last pushed - 1 stars

Something wrong with this page? Make a suggestion

Last synced: 2019-08-28 05:49:49 UTC

Login to resync this repository