scroll-view

Introduction

A scrollable view area. When using vertical scrolling, scroll-view needs to have a fixed height defined by setting the height CSS property. The length unit for component properties defaults to pixels (px).

Property Description

Property Name	Type	Default Value	Required	Description	Minimum Version
scroll-x	Boolean	FALSE	No	Allows horizontal scrolling	2.2.0
scroll-y	Boolean	FALSE	No	Allows vertical scrolling	2.2.0
upper-threshold	Number	50	No	Distance from top / left when scrolltoupper event is triggered	2.2.0
lower-threshold	Number	50	No	Distance from bottom / right when scrolltolower event is triggered	2.2.0
scroll-top	Number	-	No	Sets position of vertical scroll bar	2.2.0
scroll-left	Number	-	No	Sets position of horizontal scroll bar	2.2.0
scroll-into-view	String	-	No	Scrolls to child element in set direction	2.2.0
scroll-with-animation	Boolean	FALSE	No	Uses animation transition when setting scroll bar position	2.2.0
scroll-animation-duration	Number	200	No	Duration of animation transition when setting scroll bar position	2.2.0
refresher-enabled	Boolean	FALSE	No	Enables pull-to-refresh functionality	2.2.0
refresh-state	Boolean	FALSE	No	Sets current pull-to-refresh state	2.2.0
refresher-threshold	Number	50	No	Sets custom pull-to-refresh threshold	2.2.0
pulling-refresh-text	String	Pulling	No	Sets custom text for pull-to-refresh pulling process	2.2.0
loosing-refresh-text	String	Loosing	No	Sets custom text for pull-to-refresh releasing process	2.2.0
loading-refresh-text	String	Loading	No	Sets custom text for pull-to-refresh loading process	2.2.0
success-refresh-text	String	Success	No	Sets custom text for pull-to-refresh success	2.2.0
refresh-duration	Number	300	No	Sets custom pull-to-refresh animation transition duration	2.2.0
scrolltoupper	EventHandle	-	No	Triggered when scrolled to top / left	2.2.0
scrolltolower	EventHandle	-	No	Triggered when scrolled to bottom / right	2.2.0
onscroll	EventHandle	-	No	Triggered when scrolling	2.2.0
refresh	EventHandle	-	No	Triggered when pull-to-refresh	2.2.0
strict-mode	Boolean	TRUE	No	Determines whether scrolltoupper and scrolltolower events judge the direction of hand sliding	3.3.1
scroll-refresh-enabled	Boolean	FALSE	No	Enables pull-up refresh function	3.3.1
loadmore-enabled	Boolean	FALSE	No	Enables pull-up load more function (recommended to open when there is no more content at the bottom, to avoid conflicts during scrolling)	3.5.1
loadmore-state	Boolean	FALSE	No	Sets the current pull-up load state (true indicates that pull-up loading has been triggered, false indicates that pull-up loading has not been triggered). It can be used with the loadmore event to control the closing of pull-up loading	3.5.1
loadmore-threshold	Number	50	No	Sets custom pull-up load threshold	3.5.1
bottom-pulling-refresh-text	String	Pulling	No	Sets custom text for pull-up load pulling process	3.5.1
bottom-loosing-refresh-text	String	Loosing	No	Sets custom text for pull-up load releasing process	3.5.1
bottom-loading-refresh-text	String	Loading	No	Sets custom text for pull-up load loading process	3.5.1
bottom-success-refresh-text	String	Success	No	Sets custom text for pull-up load success	3.5.1
loadmore-duration	Number	300	No	Sets custom pull-up load animation transition duration	3.5.1
loadmore	EventHandle		No	Triggered when pull-up to refresh. After triggering, it needs to be manually closed with loadmore-state	3.5.1

Examples

Example 1: Vertical Scroll

<view class="page-section mt16">
  <view class="page-section-title">
    <text>Vertical Scroll</text>
  </view>
  <view class="page-section-spacing">
    <scroll-view
      style="height: 300px"
      :scroll-y="true"
      :scroll-top="scrollTop"
      :scroll-into-view="scrollIntoView"
      :scroll-with-animation="true"
      :scroll-animation-duration="120"
      :refresh-state="freshY"
      :refresher-enabled="true"
      loosing-refresh-text="Release to trigger pull-down refresh"
      bind:refresh="refreshY"
      bind:scrolltoupper="scrolltoupperY"
      bind:scrolltolower="scrolltolowerY"
      bind:onscroll="handleScrollY"
    >
      <template v-slot:pulling>
        <h1>Custom Pulling</h1>
      </template>
      <view id="demo1" class="scroll-view-item demo-text-1">A</view>
      <view id="demo2" class="scroll-view-item demo-text-2">B</view>
      <view id="demo3" class="scroll-view-item demo-text-3">C</view>
      <view id="demo4" class="scroll-view-item demo-text-1">A</view>
      <view id="demo5" class="scroll-view-item demo-text-2">B</view>
      <view id="demo6" class="scroll-view-item demo-text-3">C</view>
    </scroll-view>
  </view>
  <view class="mt12">
    <button bind:tap="toNextY">to NextY</button>
    <button class="ml12" bind:tap="tapMove">tap move</button>
    <button class="ml12" bind:tap="scrollToDemo">scroll to demo3</button>
  </view>
</view>

Page({
  data: {
    freshY: false,
    scrollTop: 0,
    scrollIntoView: '',
  },

  refreshY() {
    this.setData({
      freshY: true,
    });
    setTimeout(() => {
      this.setData({
        freshY: false,
      });
    }, 1000);
  },
  handleScrollY(data) {
    console.log('handleScrollY', data);
  },
  scrolltoupperY() {
    dlt.showToast('scrolltoupperY');
  },
  scrolltolowerY() {
    dlt.showToast('scrolltolowerY');
  },

  toNextY() {
    const top = this.data.scrollTop;
    const step = Math.floor(top / 150);
    const next = (step + 1) * 150;

    this.setData({
      scrollTop: next > 750 ? 0 : next,
    });
  },

  tapMove() {
    this.setData({
      scrollTop: this.data.scrollTop + 20 > 750 ? 0 : this.data.scrollTop + 20,
    });
  },

  scrollToDemo() {
    this.setData({
      scrollIntoView: 'demo3',
    });
    setTimeout(() => {
      this.setData({
        scrollIntoView: '',
      });
    }, 300);
  },
});

.scroll-view-item {
  height: 300px;
  font-size: 18px;
  color: #ffffff;
  display: flex;
  position: relative;
  align-items: center;
  justify-content: center;
  position: relative;
  z-index: 1000;
}
.demo-text-1 {
  background-color: #1aad19;
}
.demo-text-2 {
  background-color: #2782d7;
}
.demo-text-3 {
  background-color: #f1f1f1;
  color: #353535;
}

Example 2: Horizontal Scroll

<view class="page-section mt16">
  <view class="page-section-title">
    <text>Horizontal Scroll</text>
  </view>
  <view class="page-section-spacing">
    <scroll-view
      class="scroll-view_H"
      :scroll-x="true"
      bind:refresh="refreshX"
      :refresh-state="freshX"
      bind:scrolltoupper="scrolltoupperX"
      bind:scrolltolower="scrolltolowerX"
    >
      <view id="demox1" class="scroll-view-item_H demo-text-1">A</view>
      <view id="demox2" class="scroll-view-item_H demo-text-2">B</view>
      <view id="demox3" class="scroll-view-item_H demo-text-3">C</view>
    </scroll-view>
  </view>
</view>