nested-scroll-view

Nested scroll view component, supports nested scrolling and sticky header

Example

<view class="page-body">
<nested-scroll-view
 style="height: 100vh; width: 100%;"
 scroll-y="true"
 scroll-top="{{scrollTop}}"
 scroll-into-view="{{scrollIntoView}}"
 upper-threshold="50"
 lower-threshold="50"
 show-scrollbar="true"
 scroll-with-animation="true"
 bindscroll="onScroll"
 bindscrollstart="onScrollStart"
 bindscrollend="onScrollEnd"
 bindscrolltoupper="onScrollToUpper"
 bindscrolltolower="onScrollToLower"
>
  <nested-scroll-header>
    <sticky-header offset-top="0">
      <view class="header">Sticky Header</view>
    </sticky-header>
  </nested-scroll-header>
  <nested-scroll-header>
    <view class="header">Unsticky Header</view>
  </nested-scroll-header>
  <nested-scroll-body>
    <nested-scroll-view scroll-y="true" style="height: calc(100vh - 100px); width: 100%;">
      <!-- Your content here -->
      <view class="nested-scroll-item" id="nested-item-1">1</view>
      <view class="nested-scroll-item" id="nested-item-2">2</view>
    </nested-scroll-view>
  </nested-scroll-body>
</nested-scroll-view>
<button
  bindtap="onScrollToTop"
  style="position: fixed; bottom: 20px; left: 20px;"
>
  Scroll to Top
</button>
<button
 bindtap="onScrollToView"
 style="position: fixed; bottom: 20px; right: 20px;"
>
  Scroll to View
</button>
</view>

Example

Page({
  data: {
    scrollTop: 0,
    scrollIntoView: '',
    upperThreshold: 50,
    lowerThreshold: 50,
    enhanced: true,
    showScrollbar: true,
    scrollWithAnimation: true,
 },
 onScroll(e) {
  console.log('Scroll event:', e.detail);
 },
 onScrollStart(e) {
   console.log('Scroll start event:', e.detail);
 },
 onScrollEnd(e) {
   console.log('Scroll end event:', e.detail);
 },
 onScrollToUpper(e) {
   console.log('Scrolled to upper threshold:', e.detail);
 },
 onScrollToLower(e) {
   console.log('Scrolled to lower threshold:', e.detail);
 },
 onScrollToView(e) {
   this.setData({
     scrollIntoView: 'nested-item-1', // Change to the ID of the element you want to scroll to
   })
 },
 onScrollToTop() {
  this.setData({
    scrollTop: 0,
  })
 }
})

Props

Name	Type	Description	Default
`scroll-y`	`boolean`	Allow vertical scrolling, currently only supports vertical scrolling	`false`
`scroll-top`	`string` \| `number`	Set vertical scroll bar position
`scroll-into-view`	`string`	The value should be the ID of a child element (ID cannot start with a number). Set which direction to scroll, then scroll to the element in which direction
`upper-threshold`	`string` \| `number`	When it is far from the top, the scrolltupper event is triggered	`50`
`lower-threshold`	`string` \| `number`	When it is far from the bottom, the scrollcolor event is triggered	`50`
`enhanced`	`boolean`	Enable the scroll view enhancement feature. After enabling, you can operate scroll view through ScrollViewContext	`false`
`show-scrollbar`	`boolean`	Enabled when enhanced:true, control the scrollbar show/hide	`true`
`scroll-with-animation`	`boolean`	Use animation transitions when setting scroll bar position	`false`
`active`	`boolean`	Set horizontal scroll bar position	`true`
`refresher-enabled`	`boolean`	Enable pull-down refresh. Only takes effect on the root `nested-scroll-view` (not inside a `nested-scroll-body`)	`false`
`refresher-threshold`	`number`	Pull distance (px) needed to trigger a refresh. Only used with `refresher-default-style="none"`; any default style pins it to 55px, same as `scroll-view`	`45`
`refresher-default-style`	`string`	Refresher indicator, same options as `scroll-view`: `black`, `white`, `none`, `binance`	`black`
`refresher-background`	`string`	Refresher area background	`#FFF`
`refresher-triggered`	`boolean`	Whether the refresher is refreshing. Set it back to `false` to restore	`false`

Events

Name	Description
`bindscroll`	`bindscroll` Triggered when scrolling, Arguments `event: detail: Object` — The detail event object`Object{ scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY }`
`bindscrollstart`	`bindscrollstart` Triggered when scroll start, support msv >= 4.36.0 Arguments `event: detail: Object` — The detail event object`Object{ scrollLeft, scrollTop, scrollHeight, scrollWidth }`
`bindscrollend`	`bindscrollend` Triggered when scroll end, support msv >= 4.36.0 Arguments `event: detail: Object` — The detail event object`Object{ scrollLeft, scrollTop, scrollHeight, scrollWidth }`
`bindscrolltoupper`	`bindscrolltoupper` Scroll to the top/Triggered on the left
`bindscrolltolower`	`bindscrolltolower` Scroll to the bottom/Triggered on the right
`bindrefresherpulling`	`bindrefresherpulling` Triggered while pulling down, `detail: { dy }`
`bindrefresherrefresh`	`bindrefresherrefresh` Triggered when released beyond the threshold, `detail: { dy }`
`bindrefresherrestore`	`bindrefresherrestore` Triggered when the refresher is restored after refreshing, `detail: { dy }`
`bindrefresherabort`	`bindrefresherabort` Triggered when released before reaching the threshold, `detail: { dy }`

Pull-down refresh

The root nested-scroll-view supports the same pull-down refresher as scroll-view: the same refresher-* props and bindrefresher* events, and the same refresher-default-style options. With none, the built-in indicator is hidden so the page can draw its own (for example a block at the top of the content that is pulled down with it); bindrefresherpulling reports the pull distance in detail.dy. Inner views (inside a nested-scroll-body) ignore refresher-enabled; a downward pull at their top is handed to the root.

<nested-scroll-view
  scroll-y
  refresher-enabled="{{true}}"
  refresher-triggered="{{refreshing}}"
  refresher-default-style="binance"
  bindrefresherrefresh="onRefresherRefresh"
>
  <nested-scroll-header>…</nested-scroll-header>
  <nested-scroll-body>…</nested-scroll-body>
</nested-scroll-view>

nested-scroll-view

Props​

Events​

Pull-down refresh​

Props

Events

Pull-down refresh