ScrollView | AIUI | Rokid

The scroll-view component is a scrollable view container that allows users to scroll when the content exceeds the visible area.

ScrollView

The scroll-view component is a scrollable view container that allows users to scroll when the content exceeds the visible area.

Usage

<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>

Constrain the Horizontal Scroll Area

scroll-x enables horizontal overflow handling; it does not assign a width to the container. A parent's default stretch layout usually makes scroll-view fill the available width. If the parent uses a non-stretch layout such as align-items: flex-start, however, an auto-width scroll container can expand to fit its content and leave no scrollable viewport.

This complete .ink page uses width: 100% to constrain the horizontal scroll area to the width available from its parent:

<script setup>
const items = Array.from({ length: 8 }, (_, index) => ({
  id: index + 1,
  label: `Item ${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>

The important part is not a particular fixed pixel width. The scroll-view needs a definite viewport width smaller than its content. If the parent already constrains and stretches its children, you do not need to repeat the width declaration.

Properties

PropertyTypeDefaultDescription
scroll-xBooleanfalseEnables horizontal scrolling.
scroll-yBooleanfalseEnables vertical scrolling.
scroll-topNumber-Sets the vertical scroll position.
scroll-leftNumber-Sets the horizontal scroll position.
scroll-into-viewString-Scrolls to the position of the element with the corresponding ID.
auto-scrollBooleanfalseEnables automatic scrolling.
scroll-speedNumber25.0The speed of automatic scrolling.
scroll-directionStringverticalThe direction of automatic scrolling (vertical or horizontal).

Listen for Scrolling

Use bindscroll to observe scroll position changes and bindscrollend to observe the end of a scrolling sequence:

<scroll-view
  class="scroll-container"
  scroll-y="true"
  bindscroll="handleScroll"
  bindscrollend="handleScrollEnd"
>
  <!-- List content -->
</scroll-view>
export default {
  handleScroll(event) {
    console.log('Current position', event.detail.scrollTop);
  },

  handleScrollEnd(event) {
    console.log('Final position', event.detail.scrollTop);
  }
};

Whether scrolling comes from user input or code, handlers receive the same event types and data shape, and the event does not identify its source. A scroll event is dispatched only when the scroll position actually changes, and one scrollend event is dispatched when the current scrolling sequence ends. User gestures and smooth scrolling can dispatch multiple scroll events, while an immediate code-triggered scroll synchronously dispatches one scroll event followed by one scrollend event.

event.detail contains these fields:

FieldTypeDescription
scrollTop / scrollLeftNumberVertical or horizontal scroll position when the event is dispatched
scrollWidth / scrollHeightNumberWidth or height of the scrollable content
clientWidth / clientHeightNumberWidth or height of the visible area
scrollBottomNumberRemaining vertical distance to the bottom
isAtBottomBooleanWhether the entity is at the bottom

Features

  • Supports both horizontal and vertical scrolling.
  • Supports touch and mouse drag gestures.
  • Supports mouse wheel scrolling.
  • Supports automatic scrolling with custom speed and direction.