ScrollView 滚动视图 | AIUI | Rokid

scroll-view 组件是一个可滚动的视图容器,允许用户在内容超出可视区域时滚动查看。

ScrollView 滚动视图

scroll-view 组件是一个可滚动的视图容器,允许用户在内容超出可视区域时滚动查看。

使用方法

<scroll-view class="scroll-container" scroll-y="true">
  <view class="item">项目 1</view>
  <view class="item">项目 2</view>
  <view class="item">项目 3</view>
  <!-- 更多项目 -->
</scroll-view>

约束横向滚动区域

scroll-x 只启用横向溢出处理,不会替容器指定宽度。通常父级的默认拉伸布局会让 scroll-view 占满可用宽度;如果父级使用 align-items: flex-start 等非拉伸布局,宽度为 auto 的滚动容器可能随内容展开,因而没有可滚动的可视区域。

下面的完整 .ink 页面通过 width: 100% 将横向滚动区域限制在父级可用宽度内:

<script setup>
const items = Array.from({ length: 8 }, (_, index) => ({
  id: index + 1,
  label: `项目 ${index + 1}`
}));

export default {
  data: { items }
};
</script>

<page>
  <view class="page">
    <scroll-view class="gallery" scroll-x="true">
      <view class="track">
        <view class="item" ink:for="{{ items }}" ink:key="id">
          {{ item.label }}
        </view>
      </view>
    </scroll-view>
  </view>
</page>

<style>
.page {
  flex-direction: column;
  align-items: flex-start;
  padding: 20px;
}

.gallery {
  width: 100%;
  height: 88px;
  overflow: hidden;
}

.track {
  display: flex;
  flex-direction: row;
  width: 1324px;
  height: 88px;
}

.item {
  width: 144px;
  height: 64px;
  margin-right: 12px;
  background-color: #60a5fa;
  flex-shrink: 0;
}
</style>

这里的关键不是必须写出某个固定像素宽度,而是让 scroll-view 获得一个小于内容宽度的确定可视宽度。父级已经能够约束并拉伸子项时,可以不重复声明 width。

属性

属性类型默认值描述
scroll-xBooleanfalse允许横向滚动。
scroll-yBooleanfalse允许纵向滚动。
scroll-topNumber-设置竖向滚动条位置。
scroll-leftNumber-设置横向滚动条位置。
scroll-into-viewString-滚动到该 ID 对应的元素位置。
auto-scrollBooleanfalse启用自动滚动。
scroll-speedNumber25.0自动滚动的速度。
scroll-directionStringvertical自动滚动的方向 (vertical 或 horizontal)。

监听滚动

使用 bindscroll 监听滚动位置变化,使用 bindscrollend 监听一次滚动结束:

<scroll-view
  class="scroll-container"
  scroll-y="true"
  bindscroll="handleScroll"
  bindscrollend="handleScrollEnd"
>
  <!-- 列表内容 -->
</scroll-view>
export default {
  handleScroll(event) {
    console.log('当前位置', event.detail.scrollTop);
  },

  handleScrollEnd(event) {
    console.log('最终位置', event.detail.scrollTop);
  }
};

无论滚动由用户操作还是代码触发,监听函数收到的事件类型和数据结构都相同,事件中不包含滚动来源。只有滚动位置实际发生变化时才会派发 scroll;当前滚动序列结束时会派发一次 scrollend。用户手势和平滑滚动可能连续派发多个 scroll,而代码触发的立即滚动会同步依次派发一次 scroll 和一次 scrollend。

event.detail 包含以下字段:

字段类型说明
scrollTop / scrollLeftNumber事件派发时的纵向或横向滚动位置
scrollWidth / scrollHeightNumber可滚动内容的宽度或高度
clientWidth / clientHeightNumber当前可视区域的宽度或高度
scrollBottomNumber距离内容底部的剩余距离
isAtBottomBoolean是否已经滚动到底部

功能特性

  • 支持横向和纵向滚动。
  • 支持触摸和鼠标拖拽手势。
  • 支持鼠标滚轮滚动。
  • 支持自定义速度和方向的自动滚动。