BetterScroll is a plugin which is aimed at solving scrolling circumstances on the mobile side (PC supported already).

Overview

better-scroll

npm version downloads Build Status Package Quality codecov.io Gitpod Ready-to-Code

中文文档

1.x Docs

2.x Docs

2.x Demo

Note: 1.x is not maintained. please migrate your version as soon as possible

Install

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

npm install @better-scroll/core # only CoreScroll
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.

">
<script src="https://unpkg.com/better-scroll@latest/dist/better-scroll.js">script>


<script src="https://unpkg.com/better-scroll@latest/dist/better-scroll.min.js">script>
let wrapper = document.getElementById("wrapper")
let bs = BetterScroll.createBScroll(wrapper, {})

Only CoreScroll

">
<script src="https://unpkg.com/@better-scroll/core@latest/dist/core.js">script>


<script src="https://unpkg.com/@better-scroll/core@latest/dist/core.min.js">script>
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:

  • ...
  • ...
  • ...

使用webpack打包,配置babel-loader,babelrc配置如下

{
	"presets": [
		"env"
	],
	"plugins": [
		"transform-runtime"
	]
}

打包后的文件中使用bscroll的地方提示:Uncaught (in promise) TypeError: BScroll is not a constructor。 调试跟踪到代码

var _betterScroll = __webpack_require__(277);

var BScroll = _interopRequireWildcard(_betterScroll);

function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }

处发现_betterScroll没有__esModule属性,所以BScroll实际上变成了{default:BScroll}。导致下面无法实际化 因为其它引用库的原因,我是没有办法使用 module:false的babel配置的。 我尝试了各种办法,但在不修改源码的基础上始终没有一个圆满的结果。 这是在我用

import * as BScroll from 'better-scroll';

的情况。而如果我换成

import BScroll from 'better-scroll';

写法的话,typescript会转换为amd格式的js代码

const better_scroll_1 = require("better-scroll");
const myscroll = new better_scroll_1.default();

引用的话,webpack打包是没有问题,但问题在于我开发的时候用的是amd方式加载的bscroll,在这种情况下使用就有问题了。 所以我做了一点修改,如果 @ustbhuangyi 认为有更好的办法,请指点。

opened by taoqf 25
  • better scroll默认会加pointer-events 属性,如何不加该属性?

    better scroll默认会加pointer-events 属性,如何不加该属性?

    黄老师:

    better-scroll 默认会给滑动组件加pointer-events属性,我看cube-ui 的滑动就不会加该属性 加上该属性会在高频率滑动后 有时添加的属性还为pointer-events:none 导致内部无法点击

    我用的是better-scroll2 的slider组件 来做滑动答题页面,快速滑动后有时会出现点击不了。 最终发现是pointer-events:none 这个属性导致的无法点击。

    希望能手动控制pointer-events 这个属性

    bug 
    opened by wuyi123321 23
  • BS2.0中disableMouse配置为false,出现触屏无法滚动的问题(目的是兼容平板可触屏亦可鼠标控制)

    BS2.0中disableMouse配置为false,出现触屏无法滚动的问题(目的是兼容平板可触屏亦可鼠标控制)

    在1.0中,因为要兼容平板电脑使用鼠标点击,所以将disableMouse设置为false(如果不设置false,平板将无法用鼠标进行点击),移动端PC端平板端均可正常使用。

    但是在迁移2.0的时候将disableMouse设置为false,无论真机、浏览器或平板,触屏均无法滚动!(touch可点击无法滚动,滚轮可点击可滚动)

    discussion 
    opened by MmmMMMmmmyang 22
  • 苹果机,快速滚动一段距离,然后手在屏幕顿一下(此时滚动会停止),把手拿开,滚动会重新出现

    苹果机,快速滚动一段距离,然后手在屏幕顿一下(此时滚动会停止),把手拿开,滚动会重新出现

    Version

    2.0.1

    Reproduction link

    http://ustbhuangyi.com/music/#/recommend

    Steps to reproduce

    注意:机型iphone8p,os13.6

    1. 手移动到滚动区,快速移动;
    2. 手停在屏幕上,顿一下;
    3. 手拿开(此时滚动就会发生)

    What is expected?

    当手停住的时候,由于跟随性,滚动会停止,当手拿开以后,滚动也不应该再出现

    What is actually happening?

    试5次肯定就会出现

    opened by feiying-tf 21
  • 嵌套滚动在iOS14失效

    嵌套滚动在iOS14失效

    opened by silhouettesia 19
  • iOS 13.4 下 bounce 存在异常

    iOS 13.4 下 bounce 存在异常

    Version

    1.15.2

    Reproduction link

    http://ustbhuangyi.com/music/#/recommend

    Steps to reproduce

    快速滑动,当触发bounce时,你会看到 list 大跳一下,请参考你们官方播放器 demo (http://ustbhuangyi.com/music/#/recommend)

    What is expected?

    正常弹回

    What is actually happening?

    bounce渲染异常


    我本地能复现,并不是官方 demo 个例

    opened by imzxj 14
  • 当触发pullingDown初始化后,pullingUp事件不会被监听了....

    当触发pullingDown初始化后,pullingUp事件不会被监听了....

    Version

    1.13.0

    Reproduction link

    https://codesandbox.io/s/n04o7m9qr0

    Steps to reproduce

    当监听到时最后一页后不可上拉加载更多,然后执行下拉刷新,重置,以上逻辑都没问题,但是当重置后pullUpLoad事件则不执行了(因为我这里做了判断如果有下一页就执行数据请求方法,没有则什么都不执行,但是这个事件监听不执行了)

    What is expected?

    pullingUp继续监听

    What is actually happening?

    pullingUp无法监听了

    opened by Hideer 13
  • 使用 pullup 插件时触发 pullingUp 事件的时机存在问题

    使用 pullup 插件时触发 pullingUp 事件的时机存在问题

    Version

    2.1.4

    Reproduction link

    https://codesandbox.io/s/intelligent-proskuriakova-kqb8q?file=/src/App.vue&resolutionWidth=320&resolutionHeight=675

    Steps to reproduce

    在使用 pullup 插件后,pullingUp 事件的执行时间存在问题:

    1. 官方文档中对于 pullup 插件的 options 的阈值 threshold 默认值标注不正确,在翻阅源码后发现 threshold 默认值为 0
    private handleOptions(userOptions: PullUpLoadOptions = {}) {
      userOptions = (userOptions === true ? {} : userOptions) as Partial<
        PullUpLoadConfig
      >
      const defaultOptions: PullUpLoadConfig = {
        threshold: 0,  // 默认值
      }
      this.options = extend(defaultOptions, userOptions)
    
      this.scroll.options.probeType = Probe.Realtime
    }
    
    1. 源码中对于 pullingUp 事件的执行时间计算存在问题。按照插件的设计逻辑,我们应该将 maxScrollY 与 threshold 做减法运算,得出的结果与 position.y 比较才能实现当用户上拉超过 threshold 阈值时触发 pullingUp 事件,而源码中是将两者做了加法运算,导致用户上拉到距离底部 threshold 阈值时就已经触发了 pullingUp 事件:
    private checkPullUp(pos: { x: number; y: number }) {
      const { threshold } = this.options
    
    + //! 问题代码
      if (
        this.scroll.movingDirectionY === Direction.Positive &&
    -   pos.y <= this.scroll.maxScrollY + threshold
    +   pos.y <= this.scroll.maxScrollY - threshold
      ) {
        this.pulling = true
        // must reset pulling after scrollEnd
        this.scroll.once(this.scroll.eventTypes.scrollEnd, () => {
          this.pulling = false
        })
        this.unwatch()
        this.scroll.trigger(PULL_UP_HOOKS_NAME)
      }
    }
    

    正确的逻辑是否应该是上面这样的?

    What is expected?

    在正确的时机触发 pullingUp 事件,即用户上拉超过阈值时才触发。

    What is actually happening?

    不能在正确的时机触发 pullingUp 事件,在用户上拉未达到阈值时就已经触发了。

    opened by wjq990112 12
  • [New Feature] 能否实现下拉刷新时Dom复用 就像iscroll 支持的那样

    [New Feature] 能否实现下拉刷新时Dom复用 就像iscroll 支持的那样

    What problem does this feature solve?

    iscroll是支持无限滚动的,在滚动过程中会复用之前的Dom。像这个网址一样:http://lab.cubiq.org/iscroll5/demos/infinite/

    不知道better-scroll是否支持这样的功能,还麻烦提供较为详细的使用文档

    What does the proposed API look like?

    infinite: true

    enhancement discussion 
    opened by mrKylinZhou 12
  • better scroll里的元素无法触发原生的click事件

    better scroll里的元素无法触发原生的click事件

    • 重现链接: https://codepen.io/leonz/pen/OjoWrG

    • 复现步骤;

    1. 点击test区域,会弹出alert框
    document.querySelector('.test').addEventListener('click', _ => {alert(123)})
    
    1. 用手机打开页面,或者用chrome调试环境模拟一个手机环境(别忘记刷新下页面) 此时点击test区域,click事件不会触发,alert也就无法弹出。touchstart, touchend依然能触发。

    2. 不初始化Better scroll则没有问题

        this.$scroll = new BScroll(this.el)
    
    • BScroll: 1.2.2

    • 出现问题的机型、操作系统、宿主环境、浏览器信息。 所有手机环境都有问题

    • 问题分析 BScroll.prototype._start和BScroll.prototype.__end在默认情况下都会有走进e.preventDefault()的逻辑。touchstart和touchend的默认浏览器行为都被禁止了。在手机上click时间就是通过这2个事件来模拟的,default行为禁止了,就导致手机上的click事件无法被触发。scroll-wrapper内部的元素被touch后, touchstart和touchend的event都会冒泡到scroll-wrapper,然后都被禁用了默认行为, @所以better-scroll里的所有元素(除了preventDefaultException以外)在手机上都无法触发click事件

      BScroll.prototype._start = function (e) {
        if (this.options.preventDefault && !preventDefaultException(e.target, this.options.preventDefaultException)) {
          e.preventDefault();
        }
      }
    
    • workaround 把BScroll.prototype._start和BScroll.prototype.__end这2个函数里的preventDefault删除,问题就解决了。我没有细看其他代码了,所以不敢乱改。
    opened by njleonzhang 11
  • better-scroll滚动完全阻止了浏览器默认的滚动事件。

    better-scroll滚动完全阻止了浏览器默认的滚动事件。

    Version

    2.4.2

    Reproduction link

    http://192.168.0.100:8080

    Steps to reproduce

    设置better-scroll的元素高度为100vh,则100vh顶部的内容永远无法滚动下来

    What is expected?

    如果better-scroll滚动区域是从0位置开始往下拉,希望能放开浏览器默认的滚动事件,这样可以让100vh顶部的内容滚动下来。

    What is actually happening?

    现在无法滚动

    opened by hexiaokang 0
  • 关于BScroll在wheel options下,无法触发click的问题。请问有什么解决办法吗

    关于BScroll在wheel options下,无法触发click的问题。请问有什么解决办法吗

    opened by cdg9527 1
  • PC端,同时使用better-scroll和Vue.Draggable时,拖动元素后(松开鼠标左键),发现还会一直触发滚动事件,请解决

    PC端,同时使用better-scroll和Vue.Draggable时,拖动元素后(松开鼠标左键),发现还会一直触发滚动事件,请解决

    Version

    2.3.1

    Reproduction link

    https://codesandbox.io/s/vuedraggable-betterscroll-test-jv5951

    Steps to reproduce

    1. 同时使用Vue.Draggable和better-scroll
    2. 拖拽li元素进行排序
    3. 松开鼠标左键

    (可以打开codesandbox查看效果)

    What is expected?

    移动鼠标,不会触发滚动

    What is actually happening?

    移动鼠标,会触发滚动


    此时单击左键,滚动停止,但是无法继续拖拽li元素。必须再次单击左键后,才能继续拖拽,这个问题也请一并看下。

    opened by kaizige10 0
  • Releases(v2.4.2)
    • v2.4.2(Aug 2, 2021)

    • v2.4.1(Jun 24, 2021)

    • v2.4.0(Jun 23, 2021)

    • v2.3.1(May 8, 2021)

    • v2.3.0(Apr 19, 2021)

      Bug Fixes

      • slide: close #1168

      Features

      • core: add quadrant option to close #857
      • slide: add startPageXIndex and startPageYIndex to close #1175
      Source code(tar.gz)
      Source code(zip)
    • v2.2.1(Mar 4, 2021)

    • v2.1.4(Jan 24, 2021)

    • v2.1.3(Jan 21, 2021)

    • v2.1.1(Jan 4, 2021)

    • v2.1.0(Jan 4, 2021)

      Bug Fixes

      • core: don't dispatch 'scroll' or 'scrollEnd' event when content DOM is not moved
      • wheel: add restorePosition api, wheelIndexChanged event, close #1103
      • nested-scroll: refactor nested-scroll, support multi-nested scroll, close #964 #1086

      Features

      • probeType: unify the definition, see details
      • observe-image: new plugin to detect img load or not and call refresh method
      • slide: support dynamic pages, and slidePageChanged event
      • core: change offsetHeight to clientHeight for wrapper element size calculation, set directionLockThreshold to 0
      Source code(tar.gz)
      Source code(zip)
    • v2.0.6(Nov 29, 2020)

      Bug Fixes

      • core: window.getComputedStyle will resolve wrong transform value when use CSS transition, so a invalid position will be filtered when dispatching scroll event
      • slide: proxy pausePlay and startPlay methods to bs instance
      Source code(tar.gz)
      Source code(zip)
    • v2.0.5(Oct 20, 2020)

    • v2.0.4(Sep 21, 2020)

      Features

      • core: support dynamic content, add specifiedIndexAsContent option and contentChanged event
      • plugins: all plugins support dynamic content
      Source code(tar.gz)
      Source code(zip)
    • v2.0.3(Sep 9, 2020)

      Bug Fixes

      • core: should dispatch scrollEnd event while useTransition is true at some scenes, should sync pressed keys to custom click although bs dispatch click event by itself, close #1060 #981
      Source code(tar.gz)
      Source code(zip)
    • v2.0.2(Sep 2, 2020)

    • v2.0.1(Aug 27, 2020)

    • v2.0.0(Aug 27, 2020)

      Bug Fixes

      • slide: fix refresh hooks when window resized, close #1037
      • slide: fix pointer-events not reset, close #989
      • pullup & mouse-wheel: fix not trigger hook, close #881 #805
      • slide & mouse-wheel: fix jumpy, close #733
      • mouse-wheel: should respect disable() API, close #1025

      Features

      • core: narrow down bad ios version judgment, optimize init logic
      • movable: new plugin, see details
      • slide: support dynamically adding slidePage when initialised in loop or unloop mode
      • slide: v1's snap option is renamed to slide in v2
      • zoom: provide zoomTo API and add some options, add more precise hooks, expose scale when zooming
      • mouse-wheel: integrated well with wheel,pulldown,pullup plugins
      • pull-down: allow triggering pullingDown when content's size is small
      • pull-up: allow triggering pullingDown when content's size is small
      • observe-dom: remove dependencies of pull-down judgment
      Source code(tar.gz)
      Source code(zip)
    • v1.15.0(Mar 13, 2019)

    • v1.14.0(Jan 21, 2019)

    • v1.13.0(Sep 27, 2018)

      1. Remove internal type declaration since @types/better-scroll is ready, see https://github.com/DefinitelyTyped/DefinitelyTyped/pull/28053
      2. Optimize the scroll performance when move slowly.
      3. Add destroy handler of the infinity scroll.
      Source code(tar.gz)
      Source code(zip)
    • v1.12.0(Jun 6, 2018)

      Improvements

      Support Infinity Scroll, close issue #557 Support double click. Support zoomTo API.

      BugFix

      Fix a bug that stopPropagation option is not working on the mouse-wheel close issue #575. Fix a bug that mouse-wheel trigger scrollEnd two times when using transition.

      Source code(tar.gz)
      Source code(zip)
    • v1.11.1(May 10, 2018)

    • v1.10.3(May 7, 2018)

      Improvements

      Optimize pull down refresh feature. Optimize scrollbar and do not display when contents are not exceeded. Optimize auto blur feature, close issue #540 & #542 .

      Source code(tar.gz)
      Source code(zip)
    • v1.10.0(Apr 20, 2018)

      Improvements

      Support any side bounce instead of all sides. Support ease effect of mouse-wheel, close issue #516

      BugFix

      Fix the bug that using mouse-wheel in PC can not pull up load, close issue #522 .

      Source code(tar.gz)
      Source code(zip)
    • v1.9.0(Mar 23, 2018)

      Improvements

      Support vertical snap loop, close issue #489. Support stopPropagation config, close issue #492. Add some APIs: openPullDownclosePullDownopenPullUpclosePullUp, see document for more details.

      BugFix

      Avoid bugs caused by calling 'finishPullDown' many times , close issue #470.

      Source code(tar.gz)
      Source code(zip)
    • v1.8.4(Mar 7, 2018)

      Improvements

      Add max swipe bounce distance limit for better performance, close issue #478

      BugFix

      Fix a bug of Android 4.3, close issue #450 Fix a bug that can not preventDefault if set the option click to true, close issue #470

      Source code(tar.gz)
      Source code(zip)
    • v1.8.1(Feb 11, 2018)

    • v1.8.0(Jan 16, 2018)

    • v1.7.0(Jan 2, 2018)

      Improvements

      • Add snap easing config, close issue #407.
      • Add 'autoBlur' option, it will auto blur the active Element before scroll start.

      BugFix

      • Fix a bug that when the 'pullingUp' event triggered and immediately call 'finishPullUp' method will cause 'pullingUp' event never triggered again.
      • Fix a bug that button 'click' event will triggered twice if set click option to true.
      Source code(tar.gz)
      Source code(zip)
    • v1.6.3(Dec 25, 2017)

    Owner
    HuangYi
    Web Frontend Architect
    HuangYi
    Smooth scrolling for the web

    iScroll, smooth scrolling for the web iScroll is a high performance, small footprint, dependency free, multi-platform javascript scroller. It works on

    Matteo Spinelli 12.9k Jan 4, 2023
    Stellar.js - Parallax scrolling made easy

    Stellar.js PLEASE NOTE: This project is no longer maintained. If parallax scrolling is something you care about, please apply to become a contributor

    Mark Dalgleish 4.6k Dec 10, 2022
    Dragscroll is a micro library for drag-n-drop scrolling style

    Dragscroll is a micro JavaScript library (910 bytes minified) which enables scrolling via holding the mouse button ("drag and drop" or "click and hold" style, online demo). It has no dependencies and is written in vanilla JavaScript (which means it works anywhere).

    Dmitry Prokashev 1.1k Dec 21, 2022
    🛤 Detection of elements in viewport & smooth scrolling with parallax.

    Locomotive Scroll Detection of elements in viewport & smooth scrolling with parallax effects. Installation ⚠️ Scroll-hijacking is a controversial prac

    Locomotive 5.9k Dec 31, 2022
    Create an Apple-like one page scroller website (iPhone 5S website) with One Page Scroll plugin

    #One Page Scroll 1.3.1 by Pete R. Create an Apple-like one page scroll website (iPhone 5S website) with One Page Scroll plugin Created by Pete R., Fou

    Pete R. 9.6k Dec 31, 2022
    jQuery plugin for creating interactive parallax effect

    jquery.parallax What does jquery.parallax do? jquery.parallax turns nodes into absolutely positioned layers that move in response to the mouse. Depend

    stephband 1.1k Nov 25, 2022
    fullPage plugin by Alvaro Trigo. Create full screen pages fast and simple

    fullPage.js English | Español | Français | Pусский | 中文 | 한국어 Available for Vue, React and Angular. | 7Kb gziped | Created by @imac2 Demo online | Cod

    Álvaro 34.3k Jan 4, 2023
    Largetable - jQuery plugin to scroll in/maximize large tables

    largetable jQuery plugin to scroll in/maximize large tables Usage Install with npm: $ npm install largetable Then include largetable files in the HTM

    Edinum 1 Feb 3, 2021
    Scroll-stash - A JavaScript plugin to help preserve an element's scroll position.

    scroll-stash A JavaScript plugin to help preserve an element's scroll position. CodePen Example Installation npm install scroll-stash JavaScript Impo

    Sebastian Nitu 5 Sep 5, 2022
    ⚡️The Fullstack React Framework — built on Next.js

    The Fullstack React Framework "Zero-API" Data Layer — Built on Next.js — Inspired by Ruby on Rails Read the Documentation “Zero-API” data layer lets y

    ⚡️Blitz 12.5k Jan 4, 2023
    This is an application that entered the market with a mobile application in real life. We wrote the backend side with node.js and the mobile side with flutter.

    HAUSE TAXI API Get Started Must be installed on your computer Git Node Firebase Database Config You should read this easy documentation Firebase-Fires

    Muhammet Çokyaman 4 Nov 4, 2021
    Shikhar 4 Oct 9, 2022
    A social media platform aimed to capture the essence of all popular, existing social media platforms

    Social Fuel Reimagining Social Media, step by step ?? About A social media platform aimed to capture the essence of all popular, existing social media

    HariHaran 6 Feb 12, 2022
    This a programming training app, aimed to help OMRI's students learng the magic world of programming.

    OMRI App (fe-omri-app) This a programming training app, aimed to help OMRI's students learng the magic world of programming. Install the dependencies

    OMRI Tech 2 Nov 19, 2022
    An easy-to-use JavaScript library aimed at making it easier to draw on SVG elements.

    svg-pen-sketch An easy-to-use JavaScript library aimed at making it easier to draw on SVG elements when using a digital pen (such as the Surface Pen).

    Kevin Desousa 8 Jul 27, 2022
    A project aimed at consuming the Where is ISS? api to track the current position of International Space Station.

    ISS Tracker This project aims to create a website which tracks the live position of the Internation Space Station using this API. Issues: Call the api

    Microsoft Learn Student Chapter, TIET 4 Oct 21, 2022
    This plugin allows side-by-side notetaking with videos. Annotate your notes with timestamps to directly control the video and remember where each note comes from.

    Obsidian Timestamp Notes Use Case Hello Obsidian users! Like all of you, I love using Obsidian for taking notes. My usual workflow is a video in my br

    null 74 Jan 2, 2023
    This Plugin is For Logseq. If you're using wide monitors, you can place journals, linked references, and journal queries side by side.

    Logseq Column-Layout Plugin Journals, linked references, and journal queries can be placed side by side if the minimum screen width is "1850px" or mor

    YU 14 Dec 14, 2022
    A modest JavaScript framework for the HTML you already have

    Stimulus A modest JavaScript framework for the HTML you already have Stimulus is a JavaScript framework with modest ambitions. It doesn't seek to take

    Hotwire 11.7k Dec 29, 2022
    Modern browsers already had a vivid player for video

    Modern browsers already had a vivid player for video. However, web developers and designers still want to custom their own style player for different situations. Sounds like web component will do a lot favor for this purpose. With <msc-ez-video /> support, customize control panel will become a piece of cake. <msc-ez-video /> adopts CSS custom properties, developers could style them as they want.

    Paul 1 Dec 29, 2021