Mastering Long List Performance in Rax: Scroll, Recycle, and Advanced Techniques

Introduction

Rax offers many long‑list components, and choosing the right one greatly impacts performance. This article reviews the list capabilities in Rax 0.5 and provides practical guidance for developers.

How to Enable Page Scrolling

Native pages (iOS UITableView, Android RecyclerView) require a scroll container. For full‑screen scrolling, a common pattern is to use a

<View style={{position:'position', top:0, bottom:0, width:750}}></View>

. When dynamic heights are needed, the dom.getComponentRect('viewport', callback) method can retrieve the viewport height.

let dom = require('@weex-module/dom');
 dom.getComponentRect('viewport', e => {
   console.log(e.result, e.size);
 });

With this, the page can scroll freely, supporting pull‑to‑refresh and load‑more features.

Available List Components and Their Capabilities

rax‑scrollview – recommended for horizontal scrolling.

Weex implementation: slider, supports vertical and horizontal scrolling.

Cannot recycle cells; performance degrades with large content.

rax‑recyclerview – the most common high‑performance option; Weex implementation: list (no horizontal scrolling).

Provides significant performance improvements and smooth scrolling.

rax‑listview – similar to React Native's ListView.

rax‑waterfall – recommended for waterfall layouts; extends ListView capabilities.

Core Long‑List Features

onEndReached

Triggered when the list reaches the bottom, similar to Weex's loadmore. If the cell count does not change, the event will not fire again, preventing duplicate loads. To reset the scroll position after tab switches, use this.refs.list.resetScroll();.

this.refs.list.resetScroll();

refresh

Pull‑to‑refresh is native on the web; on Weex it is implemented via the RefreshControl component, which must be the first child of the list.

appear

The onAppear (or Appear) event fires when an element becomes visible. It must be bound inside a scroll container; excessive use can affect scroll performance.

onScroll

Use onScroll for real‑time updates, but avoid heavy setState calls. For smoother animations, prefer BindingX bindings.

binding.bind({
  eventType: 'scroll',
  anchor: 'list',
  props: [{
    element: 'image',
    property: 'transform.translateY',
    expression: 'image_origin'
  }]
}, function(e) {});

Page Organization Patterns

Simple Scrollable Page

<View style={{position:'position', top:0, bottom:0, width:750}}>
  <RecyclerView />
</View>

Fixed Header/Footer

<View style={{position:'position', top:0, bottom:0, width:750}}>
  <View style={{height:80}} />
  <RecyclerView />
</View>

Sticky Header

Use RecyclerView.Header (not yet supported on web in Rax 0.5) or apply position:fixed styles and duplicate the header outside the list.

<View style={{position:'position', top:0, bottom:0, width:750}}>
  <RecyclerView>
    <RecyclerView.Header />
  </RecyclerView>
</View>

Horizontal Swipe Between Pages

<View style={{width:750, position:'absolute', top:0, bottom:0}}>
  <Tab ... />
  <TabController ...>
    <TabPanel><SamplePage index="0" /></TabPanel>
    <TabPanel><SamplePage index="1" /></TabPanel>
    <TabPanel><SamplePage index="2" /></TabPanel>
  </TabController>
</View>

Nested Scrolling (Parallax)

<View style={{width:750, position:'absolute', top:0, bottom:0}}>
  <Parallax>header</Parallax>
  <Tab ... />
  <TabController ...>
    ...
  </TabController>
</View>

Long‑List Usage Tips

Horizontal & Vertical Nesting

Horizontal containers (e.g., Slider, TabHeader) cannot recycle cells; long horizontal content may cause performance issues.

Gesture Conflicts

Vertical gestures may interfere with scrolling; prefer using onScroll or BindingX's scroll method. Horizontal gestures can clash with tab‑swipe; using a native slider for horizontal scrolling avoids conflicts.

Elevator Jump (Floor Navigation)

On Weex, use dom.scrollToElement; on web, use anchor links or calculate distances and call scrollTo.

Module Order Guarantee

Assign a unique key to each cell and to modules that return multiple cells to prevent ordering issues.

Parallax Scrolling

Implemented via Weex's parallax tag or BindingX.

Web vs. Weex List Differences (Rax 0.5)

Pull‑to‑refresh: native on web, only Weex has RefreshControl.

Sticky header: not available on web.

Elevator navigation: web uses anchors; Weex uses scrollToElement.

Cell recycling: absent on web.

Appear event: native on Weex, simulated on web based on visibility.

Performance Considerations

Avoid ScrollView for very long lists; prefer RecyclerView with cell recycling.

Split cells into fine‑grained components.

Limit images per cell and keep cell structure consistent.

Do not set cellRecycle=false as it disables recycling.

Waterfall headers lack recycling; keep them short.

Limit nesting depth to ≤15.

Replace off‑screen videos with images.

Avoid recreating inline functions in onClick handlers; use stable references.

Implement shouldComponentUpdate to prevent unnecessary re‑renders.

Check for frequent setState calls that cause memory spikes and jank.

Image credit: https://unsplash.com/photos/V7gVxlUE5aY By @Toa Heftiba