title: scroll-view 可滚动视图区域 header: develop nav: component sidebar: view_scroll-view

webUrl: https://qft12m.smartapps.cn/component/scroll-view/scroll-view

解释：可滚动视图区域，可实现横向滚动和竖向滚动。使用竖向滚动时，需要给定一个固定高度，可以通过css来设置height。

属性说明

属性名 类型 默认值 必填 说明
scroll-x Boolean false 否 允许横向滚动
scroll-y Boolean false 否 允许纵向滚动
upper-threshold Number | String 50 否 距顶部/左边多远时（单位 px），触发 scrolltoupper 事件
lower-threshold Number | String 50 否 距底部/右边多远时（单位 px），触发 scrolltolower 事件
scroll-top Number | String 否 设置竖向滚动条位置。要动态设置滚动条位置，用法scroll-top="{= scrollTop =}"
scroll-left Number | String 否 设置横向滚动条位置。要动态设置滚动条位置，用法scroll-left="{= scrollLeft =}"
scroll-into-view String 否 值应为某子元素 id（id 不能以数字开头）,设置滚动方向后，按方向滚动到该元素，动态设置用法scroll-into-view="{= scrollIntoView =}"。
scroll-with-animation Boolean false 否 在设置滚动条位置时使用动画过渡
enable-back-to-top Boolean false 否 ios点击顶部导航栏、安卓双击标题栏时，滚动条返回顶部，只支持竖向
bindscrolltoupper EventHandle 否 滚动到顶部/左边，会触发 scrolltoupper 事件
bindscrolltolower EventHandle 否 滚动到底部/右边，会触发 scrolltolower 事件
bindscroll EventHandle 否 滚动时触发， event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY}

示例

在开发者工具中预览效果

扫码体验

webUrl: https://qft12m.smartapps.cn/component/scroll-view/scroll-view - 图1 请使用百度APP扫码

代码示例 1：纵向滚动

:::codeTab

  1. <view class="wrap">
  2.     <view class="card-area">
  3.         <view class="top-description">纵向滚动</view>
  4.         <scroll-view
  5.             class="scroll-view"
  6.             scroll-y
  7.             upper-threshold="1"
  8.             lower-threshold="1"
  9.             scroll-top="{= scrollTop =}"
  10.             scroll-into-view="{= scrollIntoView =}"
  11.             scroll-with-animation="true"
  12.             enable-back-to-top="true"
  13.             bindscrolltoupper="upper"
  14.             bindscrolltolower="lower"
  15.             bindscroll="scroll">
  16.             <view id="one" class="color-a">A</view>
  17.             <view id="two" class="color-b">B</view>
  18.             <view id="three"  class="color-c">C</view>
  19.         </scroll-view>  
  20.         <view class="page-section-btns">
  21.             <view class="next" bindtap="tap">下一页</view>
  22.             <view bindtap="tapMove">滚动</view>
  23.             <view class="scrollToTop" bindtap="scrollToTop">回顶部</view>
  24.         </view>
  25.     </view>
  26. </view>
  1. const order = ['one', 'two', 'three'];
  2. Page({
  3.     data: {
  4.         scrollIntoView: 'one',
  5.         scrollTop: 0,
  6.         scrollLeft: 0
  7.     },
  8.     upper() {
  9.         swan.showToast({
  10.             title: '到顶了',
  11.             icon: 'none'
  12.         });
  13.     },
  15.     lower() {
  16.         swan.showToast({
  17.             title: '到底了',
  18.             icon: 'none'
  19.         });
  20.     },
  22.     scroll(e) {
  23.         console.log('获取滚动事件的详细信息e.detail：', e.detail);
  24.         this.setData({
  25.             scrollTop: e.detail.scrollTop
  26.         })
  27.     },
  29.     scrollToTop(e) {
  30.         console.log(e);
  31.         this.setData({
  32.             scrollTop: 0,
  33.         });
  34.     },
  35.     tap(e) {
  36.         for (let i = 0; i < order.length; ++i) {
  37.             if (order[i] === this.data.scrollIntoView) {
  38.                 const next = (i + 1) % order.length;
  39.                 this.setData({
  40.                     scrollIntoView: order[next],
  41.                     scrollTop: next * 500,
  42.                 });
  43.                 break;
  44.             }
  45.         }
  46.     },
  47.     tapMove() {
  48.         this.setData({
  49.             scrollTop: this.data.scrollTop + 10,
  50.         });
  51.     }
  52. });

:::

代码示例 2：横向滚动

:::codeTab

  1. <view class="wrap">
  2.     <view class="card-area">
  3.         <view class="top-description">横向滚动</view>
  4.         <scroll-view
  5.             class="scroll-view"
  6.             scroll-x
  7.             bindscrolltoupper="toLeft"
  8.             bindscrolltolower="toRight"
  9.             scroll-left="{= scrollLeft =}"
  10.             upper-threshold="1"
  11.             lower-threshold="1"
  12.             bindscroll="scroll">
  13.             <view id="four" class="color-a row-view">A</view>
  14.             <view id="five" class="color-b row-view">B</view>
  15.             <view id="six" class="color-c row-view">C</view>
  16.         </scroll-view>
  17.     </view>
  18. </view>
  1. Page({
  2.     data: {
  3.         scrollLeft: 0
  4.     },
  6.     toLeft() {
  7.         swan.showToast({
  8.             title: '到最左边了',
  9.             icon: 'none'
  10.         });
  11.     },
  12.     toRight() {
  13.         swan.showToast({
  14.             title: '到最右边了',
  15.             icon: 'none'
  16.         });
  17.     },
  18.     scroll(e) {
  19.         console.log('获取滚动事件的详细信息e.detail：');
  20.         console.dir(e.detail);
  21.         this.setData({
  22.             scrollTop: e.detail.scrollTop
  23.         })
  24.     }
  25. });

:::

Bug & Tip

  • Tip：请勿在 scroll-view 中使用 textarea、map、canvas、video 组件；更多请看原生组件说明。
  • Tip：scroll-into-view 的优先级低于 scroll-top、scroll-left。
  • Bug：在滚动 scroll-view 时会阻止页面回弹，所以在 scroll-view 中滚动，是无法触发 onPullDownRefresh。
  • Tip：若要使用下拉刷新，请使用页面的滚动，而不是 scroll-view。
  • Tip：scroll-into-view、scroll-top、scroll-left 需要在页面数据高度（或宽度）撑开时生效，若有异步加载数据，请在数据渲染完成时，重新动态赋值，才可生效。
  • Tip：在设置 scroll-view 组件 height 属性不是内容可视区总高度时，使用 swan.pageScrollTo() API 无法生效。

参考示例

参考示例 1： 横向滚动套纵向滚动常用业务场景

在开发者工具中预览效果

:::codeTab

  1. <view class="wrap">
  2.      <view class="card-area">
  3.         <view class="top-description border-bottom">推荐列表</view>
  4.         <scroll-view
  5.             scroll-x
  6.             class="scroll-view"
  7.         >
  8.             <view class="flex">
  9.                 <scroll-view class="item" scroll-y s-for="item in list">
  10.                     <image class="image" src="{{item.src}}"></image>
  11.                     <view class="introduce">{{item.description}}</view>
  12.                 </scroll-view>
  13.             </view>
  14.         </scroll-view>
  15.     </view>
  16. </view>

:::

参考示例 2: 隐藏scroll-view的滚动条

在开发者工具中预览效果

:::codeTab

  1. /* 添加此属性隐藏scroll-view的滚动条 */
  2. ::-webkit-scrollbar {
  3.     width: 0;
  4.     height: 0;
  5.     color: transparent;
  6. }

:::

参考示例 3: 竖向锚点示例

在开发者工具中预览效果

:::codeTab

  1. <view class='scroll-box' style='height:{{ht}}px;'>
  2.     <scroll-view scroll-y class='menu-tab' scroll-into-view="{{toView}}" scroll-with-animation="true">
  3.         <view s-for="{{tabList}}" s-key="">
  4.             <view class='item-tab {{item.checked ? "item-act":""}}' id="t{{index}}" data-index="{{index}}" bindtap='intoTab'>{{item.title}}</view>
  5.         </view>
  6.     </scroll-view>
  8.     <scroll-view scroll-y style='height:{{ht}}px;'
  9.     scroll-with-animation="true"
  10.     bindscrolltoupper="upper"
  11.     bindscrolltolower="lower"
  12.     bindscroll="scrollRight"
  13.     scroll-into-view="{{toViewRt}}">
  14.         <view s-for="{{contList}}" s-key="">
  15.             <view class='cont-box' id="t{{index}}" style='height:{{ht}}px;'>{{item.cont}}</view>
  16.         </view>
  17.     </scroll-view>
  18. </view>
  1. var app = getApp();
  3. Page({
  4.     data: {
  5.         current: 0, 
  6.         // 左侧菜单
  7.         tabList: [
  8.             { title: 'tab1', checked: true },
  9.             { title: 'tab2', checked: false },
  10.             { title: 'tab3', checked: false },
  11.             { title: 'tab4', checked: false },
  12.             { title: 'tab5', checked: false },
  13.             { title: 'tab6', checked: false }
  14.         ],
  15.         // 右侧内容
  16.         contList: [
  17.             { cont: 'tab1'},
  18.             { cont: 'tab2'},
  19.             { cont: 'tab3'},
  20.             { cont: 'tab4'},
  21.             { cont: 'tab5'},
  22.             { cont: 'tab6'}
  23.         ],
  24.     },
  26.     // 循环切换
  27.     forTab(index) {
  28.         let lens = this.data.tabList.length;
  29.         let _id = 't' + index;
  30.         for (let i = 0; i < lens; i++) {
  31.         this.data.tabList[i]['checked'] = false;
  32.     }
  33.     this.data.tabList[index]['checked'] = true;
  34.         this.setData({
  35.             tabList: this.data.tabList,
  36.             toView: _id,
  37.             current: index
  38.         });
  39.     },
  41.     // 点击左侧菜单栏
  42.     intoTab(e) {
  43.         let lens = this.data.tabList.length;
  44.         let _index = e.currentTarget.dataset.index;
  45.         this.forTab(_index);
  46.         let _id = 't' + _index;
  47.         this.setData({
  48.             toViewRt: _id
  49.         });
  50.     },
  52.     // 滚动右侧菜单
  53.     scrollRight(e) {
  54.         //console.log(e)
  55.         let _top = e.detail.scrollTop;
  56.         let progress = parseInt(_top / this.data.ht); // 计算出 当前的下标
  57.         if (progress > this.data.current) { // 向上拉动屏幕
  59.         this.setData({ current: progress });
  60.         this.forTab(this.data.current);
  61.     } else if (progress == this.data.current) {
  62.         return false;
  63.     } else { // 向下拉动屏幕
  64.         this.setData({
  65.             current: progress == 0 ? 0 : progress--
  66.         });
  67.             this.forTab(progress);
  68.         }
  69.     },
  71.     onLoad: function (options) {
  72.         console.log(this.data.tabList)
  73.         // 框架尺寸设置
  74.         swan.getSystemInfo({
  75.             success: (options) => {
  76.                 var wd = options.screenWidth; // 页面宽度
  77.                 var ht = options.windowHeight; // 页面高度
  78.                 this.setData({ wd: wd, ht: ht })
  79.             }
  80.         });
  81.     },
  83.     onShow: function () {
  84.         // 初始化状态
  85.         this.setData({
  86.             toView: 't' + this.data.current,
  87.             toViewRt: 't' + this.data.current
  88.         })
  89.     }
  90. })

:::