Optimizing Long List Rendering on HarmonyOS: ArkTS and C++ Solutions

Long lists are a common scenario in front‑end and client applications such as product waterfalls, often containing thousands of items, making rendering performance critical on iOS, Android, HarmonyOS, and Web. Roma, a cross‑platform framework, explores practical implementations and optimizations, transitioning from an ArkTS + C++ architecture to a pure C++ architecture.

1. HarmonyOS Long List Solutions and Principles

HarmonyOS provides two data loading and rendering approaches for containers like List, WaterFlow, and Grid: a one‑time loading method ( ForEach ) and an on‑demand loading method ( LazyForEach ).

1.1 One‑time Loading (ForEach)

ForEach loads the entire data set at once and iterates through it to render all items. This approach creates every component node and builds the component tree, which becomes extremely time‑consuming and memory‑intensive when the data volume is large, leading to long page load times and possible crashes under high load.

Image source: HarmonyOS official website.

1.2 On‑Demand Loading (LazyForEach)

LazyForEach loads data and renders components only as needed based on the number of items that can fit in the visible area. When a component scrolls out of view, the framework destroys it to free memory; when it scrolls back in, the component is recreated and mounted.

Image source: HarmonyOS official website.

LazyForEach reduces initial load time and memory peak, improving energy efficiency and user experience. HarmonyOS further offers two optimization techniques: CacheCount (list item caching) and @Reusable (component reuse).

2.1 CacheCount

When only lazy loading is used, fast scrolling may cause a “white block” because data cannot be loaded in time. Setting the cachedCount attribute caches a configurable number of off‑screen items, so that when they become visible only rendering is needed, greatly improving scroll smoothness.

Image source: HarmonyOS official website.

2.2 Component Reuse (@Reusable)

When a component leaves the visible area, the framework destroys it to reduce memory usage. If the component is marked @Reusable , it is placed into a reuse cache (identified by reuseId ) instead of being destroyed. When a new item appears, the framework retrieves a cached component, updates it, and mounts it, saving creation time.

Image source: HarmonyOS official website.

2. Dynamic Long List Solution

Building on HarmonyOS’s built‑in mechanisms, the article discusses a dynamic long‑list approach that mirrors the three‑layer architecture of JavaScript virtual DOM, native component tree, and native render tree. The solution involves migrating iOS/Android strategies to HarmonyOS, addressing three main problems:

Excessive UI hierarchy due to wrapper components.

Long cross‑language communication paths (JS ↔ C++ via NAPI).

Redundant second layout pass after Yoga layout.

After consulting Huawei experts, the team decided to support both an ArkTS version and a C‑API version, with the ArkTS version slated for Q3 release.

3. ArkTS Version Solution

The ArkTS solution relies on LazyForEach, CacheCount, and @Reusable, synchronizing virtual DOM lifecycle with native UI events. Key optimization points include:

Avoid changing the key of visible + cached items to prevent UI “flash” during updates; use @Observed and @ObjectLink for fine‑grained data binding.

Update only the visible + cached range when data changes; keep keys stable outside this range.

Ensure correct reuseId usage (string type) for effective component reuse.

Prefer @Builder over custom @Component to reduce nesting levels.

Use AttributeUpdater for property updates and avoid heavy calculations during scrolling.

Reuse Types Table

Reuse Type

Description

Reuse Idea

Standard

Components have identical layout

Standard reuse

Limited Variation

Components differ slightly, limited types

Use reuseId or separate custom components

Composite

Many variations sharing common sub‑components

Convert to Builder for internal reuse

Global

Reusable across different parents, not suitable for Builder

Use BuilderNode as a global pool

Nested

Child components of reusable components also differ

Reduce to the four standard types

Non‑Reusable

Components vary greatly, no regular pattern

Avoid reuse

4. C‑API Version Solution

The C‑API approach tackles the UI hierarchy and cross‑language communication issues by implementing a custom lazy‑loading mechanism using ArkUI_NodeAdapter , which manages child components through event callbacks for creation, recycling, reuse, and deletion.

5. Performance Comparison

Using a complex JR APP shopping‑cart page with 400 items, three implementations were benchmarked:

Scheme

ArkTS Create

ArkTS Reuse

C++ Reuse

Full display time

1s 804ms

1s 321ms

977ms

Frame drop rate

12.1%

0.0%

0.0%

Peak memory

45.1 MB

42.3 MB

40.2 MB

The results show that LazyForEach, component reuse, cacheCount, and pre‑loading significantly improve performance, reduce stutter, and lower memory consumption.

Conclusion

The article presented HarmonyOS long‑list rendering principles, detailed ArkTS and C++ implementations, key optimization techniques, and performance analysis, demonstrating how a combination of lazy loading, caching, and component reuse can deliver a smooth user experience for massive list data.

If you found this helpful, please like and bookmark the article for future reference.

Dynamic long‑list rendering involves JavaScript, C++, iOS, Android, Java, HarmonyOS, Vue, Node, Webpack, Shell, and many other technologies. Feel free to comment for deeper discussions or suggestions.