PowerScrollView: A High‑Performance Flow Layout Solution for Flutter

In Xianyu’s main business scenarios, Flutter is used for most pages, and flow‑type layouts (search, product details, etc.) are the most common. As business iterates quickly and becomes more complex, the requirements for capability and performance of flow layouts increase dramatically.

Typical capabilities such as card exposure, scroll anchors, and waterfall layouts can no longer be satisfied by Flutter’s native widgets or existing open‑source solutions. Moreover, list scrolling smoothness degrades as the data and UI become more complex.

To address these problems, the team designed a generic page‑layout solution for flow scenarios called PowerScrollView . Before the design, native scrolling containers (iOS UICollectionView and Android RecyclerView) were studied. Their section‑based concepts inspired the architecture, but a direct port to Flutter was impossible, so a hybrid design combining native ideas with Flutter’s features was created.

PowerScrollView is built on top of CustomScrollView and composes multiple Sliver widgets. Each list consists of several Sections, each with a header (optional sticky), content, and footer. The content supports list, grid, waterfall, and custom layouts. Headers and footers map to SliverBox , content maps to SliverList or SliverGrid , and a custom SliverWaterfall is added for waterfall layouts. Refresh and load‑more slivers are inserted at the top and bottom.

The solution is divided into four parts: a data‑source manager (handles Section initialization and CRUD), a controller (manages refresh, load‑more, and scroll‑to actions), event callbacks (exposes only needed callbacks), and refresh configuration (provides both standard and custom refresh widgets).

Key Features

Automatic Exposure : Exposure logic is moved out of the build method. Each cell is wrapped in a custom StatefulElement that records mount/unmount events and registers itself via an InheritedWidget . During scrolling, only elements currently in the viewport are checked, avoiding exposure of off‑screen buffer items. A sampling rate parameter limits how often exposure checks run, and size changes from 0 to non‑zero trigger a one‑time exposure.

Scroll‑to‑Index : When the target index is already in the viewport or buffer, the element is located and scrolled into view. If not, the system determines the scroll direction, performs a fast jump, and recursively continues until the target appears, handling cases where animation may be coarse.

Performance Optimizations

Full list rebuilds cause jank. The refresh process of a Viewport involves rebuilding every sliver’s element and relayout of all slivers. By controlling SliverMultiBoxAdaptorElement ’s child widget and element caches, the team implements fine‑grained local refresh for insert, delete, and load‑more operations, avoiding unnecessary rebuilds.

For LoadMore , widget caches are cleared, null widgets are filtered, and only the affected sliver is marked dirty. For Delete , child widget‑index mappings are updated, and the corresponding element is deactivated without rebuilding the whole viewport. Insert follows a similar pattern.

Element reuse is achieved by overriding collectGarbage to capture deactivated elements into a pool and reuse them later, similar to iOS UITableView/UICollectionView and Android RecyclerView.

Frame‑by‑Frame Rendering

When a frame has too many cells to build, placeholder widgets are rendered first, and the actual heavy cells are built in subsequent frames. This “sharding” reduces peak frame time, lowers dropped‑frame counts, and improves perceived smoothness, especially on high‑end devices. However, on low‑end phones, extremely complex cells may still cause jank.

Real‑World Adoption

PowerScrollView has been deployed across multiple core pages of Xianyu, providing rich capabilities, good performance, and low integration cost. The solution still faces challenges on low‑end devices and in highly complex waterfall layouts, which are future research directions. Further work includes deeper engine‑level reuse improvements and integration with dynamic templates for end‑to‑end page construction.