# Options
BetterScroll supports rich options configuration, you can pass them in the second parameter when initializing, for example:
import BScroll from '@better-scroll/core'
let scroll = new BScroll('.wrapper',{
scrollY: true,
click: true
})
This implements a list of vertical clickable scrolling effects. so let's list the parameters supported by BetterScroll.
# startX
- Type:
number
- Default:
0
- Details: Initialize the postion in the horizontal axis direction.
# startY
- Type:
number
- Default:
0
- Details: Initialize the postion in the vertical axis direction.
# scrollX
- Type:
boolean
- Default:
false
- Usage: When set to true, horizontal scrolling would be enabled
- Note: This configuration is invalid when setting eventPassthrough to 'horizontal'.
# scrollY
- Type:
boolean
- Default:
true
- Usage: When set to true, vertical scrolling would be enabled
- Note: This configuration is invalid when setting eventPassthrough to 'vertical'.
# freeScroll
- Type:
boolean
- Default:
false
- Usage: By default, because human fingers cannot perform absolute vertical or horizontal movement, there will be horizontal and vertical offsets during a finger operation. The internal default will abandon the smaller offset direction , Keep scrolling in the other direction. But in some scenes, we need to calculate the horizontal and vertical finger offset distances at the same time, instead of only calculating the direction with a larger offset. At this time, we only need to set
freeScroll
to true. - Note: This configuration is invalid when eventPassthrough isn't set to empty.
- Examples
// finger startpoint -> e1: { pageX: 120, pageY: 120 }
// finger endpoint -> e2: { pageX: 121, pageY: 140 }
// offsetX: e2.pageX - e1.pageX = 1
// offsetY: e2.pageY - e1.pageY = 20
// if freeScroll is false, due to offsetY > offsetX + directionLockThreshold
// offsetX is fixed to be 0, only calculate offsetY, thus do a vertical scroll!
# directionLockThreshold
- Type:
number
- Default:
5
- Usage: when
freeScroll
is false, we need to lock the scrolling only in one direction, we calculate the numerical difference between the absolute values of horizontal axis and vertical axis' scrolling distance at the initialization time of scrolling. When the value of the numerical difference is greater thandirectionLockThreshold
, the lock direction can be determined. - Note: If eventPassthrough is set,
directionLockThreshold
is invalid and will always be 0.
# eventPassthrough
- Type:
string
- Default:
''
- Optional value:
vertical | horizontal
- Usage: Sometimes we want to preserve native vertical scroll but being able to add an horizontal BetterScroll (maybe a carousel). Set this to 'vertical' and the BetterScroll area will react to horizontal swipes only. Vertical swipes will naturally scroll the whole page. Contrarily, set this to 'horizontal' when you want to keep natural horizontal scroll.
- Note: The setting of
eventPassthrough
will cause some other settings to be invalid, be careful when using it.
# click
- Type:
boolean
- Default:
false
- Usage: To override the native scrolling BetterScroll has to inhibit some default browser behaviors, such as mouse clicks. If you want your application to respond to the click event you have to explicitly set this option to
true
. And then BetterScroll will add a private attribute called_constructed
to the dispatched event whose value is true.
# dblclick
- Type:
boolean | Object
- Default:
false
- Usage: Send dblclick event. When configured to true, by default the two times click delay is 300 ms. If configured to an object, the
delay
can be modified.
dblclick: {
delay: 300
}
# tap
- Type:
string
- Default:
''
- Details: Since BetterScroll will block the native click event, we can set tap to 'tap', which will dispatch a tap event when the region is clicked. You can listen to it as if it were listening to native events.
# bounce
- Type:
boolean | Object
- Default:
true
- Details: When the content element meets the boundary it performs a small bounce animation. Setting this to true will enable the animation.
bounce: {
top: true,
bottom: true,
left: true,
right: true
}
bounce
can support the effect of closing the back of some edges. You can set the key
of the corresponding side to false
.
TIP
If you want to conveniently set all edges to true or false, you only need to set bounce
to true or false.
# bounceTime
- Type:
number
- Default: Default:
800
(ms, modification is not recommended) - Details: Set the duration in millisecond of the bounce animation.
# momentum
- Type:
boolean
- Default:
true
- Usage: If setted to true, you can turn on the momentum animation when the user quickly flicks on screen.
# momentumLimitTime
- Type:
number
- Default:
300
(ms) - Usage: Only when the time of the user's flicking on screen is lower than
momentumLimitTime
resulting in the momentum animation.
# momentumLimitDistance
- Type:
number
- Default:
15
(px) - Usage: Only when the distance of the user's flicking on screen is greater than
momentumLimitTime
resulting in the momentum animation.
# swipeTime
- Type:
number
- Default:
2500
(ms) - Usage: Set the duration in millisecond of the momentum animation.
# swipeBounceTime
- Type:
number
- Default:
500
(ms) - Usage: Set the entire bounce animation time when the content element meets the boundary in the case of running a momentum animation.
# deceleration
- Type:
number
- Default:
0.0015
- Usage: Represent the deceleration of the momentum animation.
# flickLimitTime
- Type:
number
- Default:
200
- Usage: Sometimes we want to cpture the user's flick action (slide a short distance in a short time). Only when the time of the user slide on screen is shorter than
flickLimitTime
, it is considered as a flick action.
# flickLimitDistance
- Type:
number
- Default:
100
- Usage: Only when the distance of the user slide on screen is shorter than
flickLimitDistance
, it is considered as a flick action
# resizePolling
- Type:
number
- Default:
60
(ms) - Usage: When you resize the window BetterScroll has to recalculate elements position and dimension. This might be a pretty daunting task for the poor little fella. To give it some rest the polling is set to 60 milliseconds and it is reasonable value.
# probeType
- Type:
number
- Default:
0
- Optional Value:
1 | 2 | 3
- Usage: Deciding whether to dispatch the scroll event, this has an impact on the performance of the page, especially in the mode where
useTransition
is true.
// There are two scenarios for dispatching scroll:
// 1. The finger acts on the scrolling area (content DOM),
// 2. Invoke the scrollTo method or trigger the momentum scroll animation (in fact, the implementation is still Invoking the scrollTo method)
// For the v2.1.0, the probeType has been unified
// The probeType is:
// 0, scroll event will not be dispatched at any time,
// 1, and only when the finger is moving on the scroll area, a scroll event is dispatched every momentumLimitTime milliseconds.
// 2, and only when the finger is moving on the scroll area, a scroll event is dispatched all the time.
// 3, scroll events are dispatched at any time, including invoking scrollTo or triggering momentum
# preventDefault
- Type:
boolean
- Default:
true
- Usage: Whether or not to
preventDefault()
when events are fired. This should be lefttrue
unless you really know what you are doing.
# preventDefaultException
- Type: Object
- Default:
{ tagName: /^(INPUT|TEXTAREA|BUTTON|SELECT|AUDIO)$/ }
- Usage: BetterScroll will inhibit the native scrolling and meanwhile inhibit some native components' default behaviours. In this situation, we can't 'preventDefault' on these elements, so we can configure 'preventDefaultException'. Default
{tagName: /^(INPUT|TEXTAREA|BUTTON|SELECT|AUDIO)$/}
represents that default behaviours of elements with tagnames like 'input', 'textarea', 'button', 'select', 'audio' will not be inhibited - Note: This is a pretty powerful option. Its key is the attribute value of DOM elements, the corresponding value can be a regular expression. For example, if we want to configure the element whose class name is 'test', then the configuration is
{className:/(^|\s)test(\s|$)/}
.
# tagException
- Type:
Object
- Default:
{ tagName: /^TEXTAREA$/ }
- Usage: If BetterScroll nests form elements such as
textarea
, the user's expectation should be that sliding textarea should not cause bs scrolling. If the manipulated DOM (eg:textarea tag) hits the configured rule,bs
won't scroll. - Note: This is a pretty powerful option. Its key is the attribute value of DOM elements, the corresponding value can be a regular expression. For example, if we want to configure the element whose class name is 'test', then the configuration is
{className:/(^|\s)test(\s|$)/}
.
# HWCompositing
- Type:
boolean
- Default:
true
- Usage: This option tries to put the content element on the hardware layer by appending
translateZ(1px)
to the transform CSS property. This greatly increases performance especially on mobile and achieve a good scrolling effect. - Note: Only browsers that support enabling hardware acceleration has the effect.
# useTransition
- Type:
boolean
- Default:
true
- Usage: Whether to use CSS3 transition animation. If setted to false, the engine will use
requestAnimationFrame
to do animation.
# bindToWrapper
- Type:
boolean
- Default:
false
- Usage: The
touchmove
event is normally bound to the document and not the scroll wrapper. When you move the cursor out of the wrapper the scrolling keeps going(only works in PC). This is usually what you want, but you can also bind the move event to wrapper itself. Doing so as soon as the cursor leaves the wrapper the scroll stops. - Note: For the mobile, even if the touchmove event is bound to the wrapper, the wrapper can still be moved if the finger leaves the wrapper.
# disableMouse
- Type:
boolean
- Default: get the result by current browser environment
- Usage: When in mobile environment (supporting touch event), disableMouse will be
true
and mouse event will not be listened. While in PC environment, disableMouse will befalse
and mouse event will be listened.
# disableTouch
- Type:
boolean
- Default: get the result by current browser environment
- Usage: When in mobile environment (supporting touch event),
disableTouch
will befalse
and touch event will be listened. While in PC environment,disableMouse
will betrue
and touch event will not be listened. We suggest not modifying this unless you konw what you are doing.
WARNING
Considering some specific scenarios of the user, such as the tablet needs to support the touch event, the tablet with mouse has to support the mouse event, In other words, if you need to listen to the touch and mouse events at the same time, then the instantiation of BetterScroll needs to be configured as follows:
let bs = new BScroll('.wrapper', {
disableMouse: false,
disableTouch: false
})
Due to the different bottom-level implementation logic of different devices and different browser environments, BetterScroll's internal calculations of whether to listen to touch
or mouse
events may make wrong judgment, so you can solve this type of problem according to the above option configuration.
# autoBlur
- Type:
boolean
- Default:
true
- Usage: It will auto blur the active element(input、textarea) before scroll start.
# stopPropagation
- Type:
boolean
- Default:
false
- Usage: Whether stop event propagation. It is often used in nested scroll scenes.
# bindToTarget
- Type:
boolean
- Default:
false
- Usage: Bind touch or mouse events to the
content
element instead of the containerwrapper
, which is mostly used in movable.
# autoEndDistance
- Type:
number
- Default:
5
- Usage: When the finger operation is crazy, the
touchend
event may not be triggered when sliding out of the viewport, so the function of autoEndDistance is to automatically call the touchend event when the finger is about to leave the current viewport. When the default distance is 5px from the boundary, the scrolling ends.
# outOfBoundaryDampingFactor
- Type:
number
- Default:
1 / 3
- Usage: When out of boundary, the damping behavior is performed. The smaller the damping factor, the greater the resistance. Value range: [0, 1].
# specifiedIndexAsContent 2.0.4
- Type:
number
- Default:
0
- Usage: Specify the child element corresponding to the index of the
wrapper
as thecontent
. By default, BetterScroll uses the first child element of thewrapper
as the content.
<div class="wrapper">
<div class="content1">
<div class="conten1-item">1.1</div>
<div class="conten1-item">1.2</div>
</div>
<div class="content2">
<div class="conten2-item">2.1</div>
<div class="conten2-item">2.2</div>
</div>
</div>
// For the above DOM structure, when BetterScroll version <= 2.0.3, only div.content1 is used as content
// When the version is >= 2.0.4, content can be specified through 'specifiedIndexAsContent'
let bs = new BScroll('.wrapper', {
specifiedIndexAsContent: 1 // use div.content2 as BetterScroll's content
})
# quadrant 2.3.0
- Type:
1 | 2 | 3 | 4
- Default:
1
- Usage: When the ancestor elements of BetterScroll's wrapper DOM are forced to rotate by CSS, the original displacements in the x and y directions need to perform a certain transformation to ensure a reasonable interaction.
<style>
/* wrapper's parent DOM rotated*/
.container {
transform: rotate(90deg);
}
</style>
<div class="container">
<div class="wrapper">
<div class="content">
<div class="content-item">1.1</div>
<div class="content-item">1.2</div>
</div>
</div>
</div>
let bs = new BScroll('.wrapper', {
quadrant: 2
})
- When the rotation angle of the parent element or ancestor element of the
wrapper
is (315, 45], the quadrant can keep the default value; - When the rotation angle of the parent element or ancestor element of the
wrapper
is (45, 135],Especially 90 degrees, the quadrant must be2
; - When the rotation angle of the parent element or ancestor element of the
wrapper
is (135, 225],Especially 180 degrees, the quadrant must be3
; - When the rotation angle of the parent element or ancestor element of the
wrapper
is (225, 315],Especially 270 degrees, the quadrant must be4
; - When the rotation angle is special, such as 30 degrees or 200 degrees, you may not be satisfied with the built-in transformation logic. You can customize your own transformation logic through the
coordinateTransformation
hook.
let bs = new BScroll('.wrapper', {
quadrant: 1 // default value
})
bs.scroller.actions.hooks.on(
bs.scroller.actions.hooks.eventTypes.coordinateTransformation,
(transformateDeltaData) => {
// get user finger moved distance
const originDeltaX = transformateDeltaData.deltaX
const originDeltaY = transformateDeltaData.deltaY
// apply transformation
transformateDeltaData.deltaX = originDeltaY
transformateDeltaData.deltaY = originDeltaX
// transformateDeltaData.deltaX will be used as content DOM style's translateX
// transformateDeltaData.deltaY will be used as content DOM style's translateY
}
)
For example: Use CSS to flip the horizontal scrolling BetterScroll.
← base-scroll API →