How to Supercharge Long List Rendering on HarmonyOS with LazyForEach and Reuse

HarmonyOS Long List Solutions Overview

Long lists are common in front‑end and client applications; rendering thousands of items efficiently is critical on iOS, Android, HarmonyOS and Web. Roma, a cross‑platform framework, adopts ArkTS + C++ and faces challenges that are addressed in this article.

1. HarmonyOS List Loading Strategies

1.1 ForEach (eager loading)

ForEach loads the entire data set and creates all component nodes at once. This leads to long initial rendering time and high memory usage, especially with large lists.

1.2 LazyForEach (on‑demand loading)

LazyForEach loads only the items that fit in the visible area plus a configurable cache. Components are created on demand, destroyed when they leave the viewport, and recreated when they re‑enter, reducing both start‑up time and memory peak.

Additional optimizations include CacheCount (pre‑caching off‑screen items) and the @Reusable annotation for component reuse.

1.2.1 CacheCount

Setting cachedCount caches a number of items outside the visible area, preventing “white‑block” flashes during fast scrolling.

1.2.2 Component Reuse (@Reusable)

Components marked @Reusable are moved to a reuse pool when removed from the tree. When a new item appears, the framework pulls a component from the appropriate pool, updates it, and re‑adds it, saving creation time.

2. Dynamic Long‑List Solution

Porting iOS/Android solutions to HarmonyOS revealed three main issues: excessive UI hierarchy, long cross‑language communication, and a redundant second layout pass. The team decided to support both an ArkTS version and a C‑API version.

2.1 ArkTS Solution

The ArkTS approach relies on LazyForEach + CacheCount + @Reusable, synchronising virtual DOM operations with native UI events. Key optimisation points include:

Avoid changing the key of visible items; use @Observed and @ObjectLink for partial updates.

Update only the visible + cacheCount range after data changes.

Ensure correct reuseId (string) for effective component reuse.

Prefer @Builder over custom components to reduce nesting.

Use AttributeUpdater for property updates and minimise state‑variable refreshes.

2.2 C‑API Solution

The C‑API version tackles UI hierarchy and cross‑language overhead by implementing a custom lazy‑loading mechanism using ArkUI_NodeAdapter to manage child components and handle creation, recycling and deletion in event callbacks.

3. Performance Comparison

Tests on a complex shopping‑cart page with 400 items show that the C++ reuse implementation achieves the fastest full‑display time (977 ms) and the lowest memory usage (40.2 MB), while LazyForEach with cache and reuse eliminates frame drops.

Conclusion

The article demonstrates HarmonyOS long‑list rendering techniques, including ArkTS and C++ implementations, key optimisation details and performance results, providing a practical guide for developers facing large‑scale list challenges.