#<scroll-view>

Basic scrolling component supporting both horizontal and vertical scrolling. When its content area is larger than its visible area, it allows users to scroll to reveal more content.

#Usage

#Horizontal and Vertical Scrolling

<scroll-view> supports both horizontal and vertical scrolling, implemented through the scroll-orientation properties. <scroll-view> always uses the linear layout, and the layout direction is determined by the scroll-orientation attributes.

scroll-viewsrc/base/App.tsx

Code

Preview

#Scroll Events

Use event callbacks such as bindscroll, bindscrolltoupper, and bindscrolltolower to monitor changes in scroll progress.

scroll-viewsrc/event/index.tsx

Code

Preview

#Sticky Capability

As a child node of <scroll-view>, you can set the sticky attribute making the child node remain at a certain distance from the top of the <scroll-view> and not continue scrolling with the content.

scroll-viewsrc/sticky/index.tsx

Code

Preview

<scroll-view> scroll-y>
  <view> // do anything you want
  {...}
  </view>
</scroll-view>

#Attributes

#bounces

// @defaultValue: true
bounces?: boolean;

Enable bounce effect

#enable-scroll

// @defaultValue: true
'enable-scroll'?: boolean;

Enable dragging

#initial-scroll-offset

// @defaultValue: 0
'initial-scroll-offset'?: number;

Initial scroll position, only effective once, in PX

#initial-scroll-to-index

// @defaultValue: 0
'initial-scroll-to-index'?: number;

Scroll to specified child node on first screen, only effective once. All direct child nodes must be flatten=false.

#lower-threshold

// @defaultValue: 0
'lower-threshold'?: number;

Set upper threshold to bindscrolltoupper event.

#scroll-bar-enable

// @defaultValue: true
'scroll-bar-enable'?: boolean;

Enable scrollbar

#scroll-orientation

// @defaultValue: 'vertical'
'scroll-orientation'?: 'vertical' | 'horizontal';

Replacement of scroll-x and scroll-y

#upper-threshold

// @defaultValue: 0
'upper-threshold'?: number;

Set upper threshold to bindscrolltoupper event.

#Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

#bindcontentsizechanged

bindcontentsizechanged = (e: ContentSizeChangedEvent) => {};

This event is triggered when the scrollview's content size changed.

#bindscroll

bindscroll = (e: ScrollEvent) => {};

This event is triggered when the scrollview is scrolling.

#bindscrollend

bindscrollend = (e: ScrollEndEvent) => {};

This event is triggered when the scrollview's scroll ended.

#bindscrolltolower

bindscrolltolower = (e: ScrollToLowerEvent) => {};

This event is triggered when the lower/right edge of the scrolling area intersects with the visible area defined by the lowerThreshold.

#bindscrolltoupper

bindscrolltoupper = (e: ScrollToUpperEvent) => {};

This event is triggered when the upper/left edge of the scrolling area intersects with the visible area defined by the upperThreshold.

#Methods

Frontend can invoke component methods via the SelectorQuery API.

#autoScroll

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'autoScroll',
      params: {
        /**
         * The distance of each second's scrolling, which supports positive and negative values. The unit of distance can be "px", "rpx", "ppx", or null (for iOS, the value must be greater than 1/screen.scale px).
         * @Android
         * @iOS
         * @Harmony
         * @PC
         */
        rate: number;
        /**
         * Start/stop automatic scrolling.
         * @Android
         * @iOS
         * @Harmony
         * @PC
         */
        start: boolean;
      };
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

Automatic scrolling

#getScrollInfo

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'getScrollInfo',
      success: Callback<{
        /**
         * Total scrollable range along orientation, in PX
         * @Android
         * @iOS
         * @Harmony
         * @PC
         */
        scrollRange: number;
        /**
         * Content offset on X-axis, in PX
         * @Android
         * @iOS
         * @Harmony
         * @PC
         */
        scrollX: number;
        /**
         * Content offset on Y-axis, in PX
         * @Android
         * @iOS
         * @Harmony
         * @PC
         */
        scrollY: number;
      }>;
      fail: function (res) {},
    })
    .exec();

Get scroll info

#scrollBy

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'scrollBy',
      params: {
        /**
         * Offset to scroll
         */
        offset?: number;
      };
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

Scroll by specified offset

#scrollTo

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'scrollTo',
      params: {
        /**
         * Target item index
         * @defaultValue 0
         */
        index?: number;
        /**
         * Offset relative to target node
         */
        offset?: number;
        /**
         * Enable scroll animation
         */
        smooth?: boolean;
      };
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

Scroll to specified position

#Performance Optimization Suggestions

<scroll-view> creates all of its child nodes at once, potentially causing severe first-screen load times. Use exposure events to drive it to create only visible child nodes.

<scroll-view> lacks any reuse mechanism. If content is too extensive, it may consume an exceptionally large amount of memory, possibly causing OOM and other stability problems.

For data exceeding three screens, use <list> to optimize performance, or simulate <VisualizedList> logic based on exposure events.

#Compatibility