HarmonyOS Long List Rendering Solutions: ForEach, LazyForEach, CacheCount, and Component Reuse

Long lists are a common scenario in front‑end and client applications such as product waterfalls, often containing thousands of items; rendering performance is critical on iOS, Android, HarmonyOS and Web. HarmonyOS provides two loading modes: a one‑time ForEach that loads all data at once, and an on‑demand LazyForEach that loads data as needed.

ForEach loads the entire dataset, creates all component nodes, and builds the view tree, which leads to long initial load times and high memory usage when the data volume is large.

LazyForEach loads only the number of items that fit the visible area, creates component nodes on demand, destroys them when they leave the viewport, and optionally caches a configurable number of off‑screen items using CacheCount . This reduces start‑up time, memory peak, and improves energy efficiency.

CacheCount pre‑creates a limited number of off‑screen items to avoid the “white‑block” phenomenon during fast scrolling. Component reuse is achieved with the @Reusable annotation, which moves destroyed components and their JSView objects into a reuse pool identified by reuseId . When new items appear, the framework retrieves a component from the pool, updates it, and re‑adds it to the view tree, saving creation time.

The article then discusses migrating iOS/Android long‑list solutions to HarmonyOS using the ArkUI framework, identifying three main issues: excessive UI hierarchy, long cross‑language communication paths (JS ↔ C++ via NAPI), and a redundant second layout pass after Yoga layout.

To address these, two solution tracks are presented:

ArkTS version : leverages native LazyForEach, CacheCount, and @Reusable, synchronizes virtual DOM lifecycle with native UI, and applies optimizations such as stable keys, @ObjectLink/@Observed for partial updates, correct reuseId usage, avoiding unnecessary state updates, and limiting heavy calculations during scrolling.

C‑API version : uses ArkUI_NodeAdapter to manage child components, handling creation, recycling, and reuse manually, thus eliminating the extra UI hierarchy and cross‑language overhead.

Performance comparison (400‑item cart page) shows:

Scheme

ArkTS Create

ArkTS Reuse

C++ Reuse

Full display time

1.804 s

1.321 s

0.977 s

Frame drop rate

12.1 %

0 %

0 %

Peak memory

45.1 MB

42.3 MB

40.2 MB

The results confirm that LazyForEach, component reuse, CacheCount, and pre‑loading significantly improve performance, especially reducing stutter during scrolling, while simplifying UI hierarchy and avoiding cross‑language calls further enhances efficiency.

In summary, the article presents a comprehensive guide to HarmonyOS long‑list solutions, covering ArkTS and C++ implementations, key optimization techniques, and empirical performance data.