# ScrollComponentSample

**Repository Path**: saraliusu/scroll-component-sample

## Basic Information

- **Project Name**: ScrollComponentSample
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 6
- **Created**: 2025-05-22
- **Last Updated**: 2025-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于ScrollComponent实现瀑布流页面

## 简介
本示例展示了使用ScrollComponent构建瀑布流页面，实现高性能无限滑动的场景，覆盖能力包括

- 支持瀑布流复杂页面的流畅无限滑动
- 默认懒加载
- 支持组件复用，解决滑动丢帧，提升滑动性能
- 支持复用池共享，满足跨页面跨父组件复用能力
- 支持预创建，减少冷启首次滑动丢帧，提升滑动性能
- 支持预加载，滑动过程提前加载数据，提升浏览体验

## 效果预览
![img.gif](screenshots/img.gif)

## 工程目录
```
├─entry/src/main/ets
├── model                               
|  ├── mock.ets
|  ├── ToolBarData.ets
|  ├── types.ets
├── pages                                   
|  ├── Index.ets
|  ├── StandardWaterFlowPage.ets       // 标准型复用
|  ├── WaterFlowPage.ets               // 组合型复用
|  └── SharedPoolPage.ets              // 共享复用池
```

## 功能说明
1. StandardWaterFlowPage.ets：实现了标准型组件复用和预创建能力，瀑布流页面自适应屏幕旋转；
2. WaterFlowPage.ets：通过组合型组件复用、预创建和预加载能力，实现了瀑布流下拉刷新和流畅上滑；
3. WaterFlowPage.ets和SharedPoolPage.ets：实现了跨页面复用池共享功能；


## 实现说明
> 下文介绍高效无限瀑布流页面渲染，关于Sample更多介绍查看[基于ScrollComponents之WaterFlow高性能滑动最佳实践](http://xxxxx)

### 1. 定义瀑布流视图管理类，注册item节点模板
HMWaterFlowManager是视图管理器，开发者根据业务需要自定义视图管理器类。
- 页面初始化时，开发者自定义子节点模板和组件绑定，即可实现复用能力
- 如果使用预创建节点，需在预创建前注册节点模板

```c
// src/main/ets/pages/StandardWaterFlowPage.ets

import { HMNodeItem, HMRecyclerView } from 'recyclerview';

/**
 * item模板
 * */
@Builder
function StandardGridImageContainer($$: ESObject) {
  GridImageView({blogItem: $$.blogItem})
}

// 1. 自定义视图管理器
class MyWaterFlowManager extends HMWaterFlowManager {
    onCreateNodeItem(index: number, data: BlogData) {
        // 3. 根据唯一标识获取复用节点，传递节点数据
        let node: HMNodeItem<Params> | null = this.dequeueReusableNodeByType('StandardGridImageContainer');
        node?.setData({ blogItem: data });
        return node;
    }
}

@Entry
@Component
export struct StandardWaterFlowPage {
    waterFlowView: MyWaterFlowManager = new MyWaterFlowManager();
    ...

    aboutToAppear(): void {
        ...
        this.initListener();
        // 2. 注册节点模板
        this.waterFlowView.registerNodeItem('StandardGridImageContainer', wrapBuilder(StandardGridImageContainer));
    }
    ...
}
```

### 2. WaterFlow组件初始化

```c
// src/main/ets/pages/StandardWaterFlowPage.ets

import { EVENTS } from 'recyclerview';

@Entry
@Component
export struct StandardWaterFlowPage {
    waterFlowView: MyWaterFlowManager = new MyWaterFlowManager();
    scroller: Scroller = new Scroller();
    ...

    aboutToAppear(): void {
        this.initListener();
    }

    initListener() {
        this.waterFlowView.listener.on(EVENTS.ON_CREATE_VIEW, (waterFlow: HMWaterFlowInterface) => {
          waterFlow({scroller: this.scroller})
            .width(CommonConstants.FULL_WIDTH)
            .height(CommonConstants.FULL_HEIGHT)
            .columnsTemplate(CommonConstants.WATER_FLOW_COLUMNS_TEMPLATE)
            .columnsGap(CommonConstants.COLUMNS_GAP)
            .rowsGap(CommonConstants.ROWS_GAP)
            .padding(CommonConstants.PADDING)
        })
    }
}
```

### 3. 设置数据源渲染组件
- ScrollComponent默认支持懒加载，使用setDataSource设置普通数组即可。开发者无需繁琐的定义类似lazyForEach的Datasource数据源
- HMRecyclerView组件占位，绑定视图容器实例即可渲染瀑布流列表
```c
// src/main/ets/pages/StandardWaterFlowPage.ets

import { HMRecyclerView } from 'recyclerview';

@Observed
class BlogData{
  id: number=-1
  images: string[] =[];
  imagePixelMap: image.PixelMap | undefined;
  ...
}

@Entry
@Component
export struct StandardWaterFlowPage {
    waterFlowView: MyWaterFlowManager = new MyWaterFlowManager();
    scroller: Scroller = new Scroller();
    @State data: BlogData[] = [];
    ...

    aboutToAppear(): void {
        ...
        this.initListener();
        // 1. setDataSource设置瀑布流数据
        this.waterFlowView.setDataSource(data);
    }

    build() {
        Column() {
            ...
            // 2. 绑定视图容器实例
            HMRecyclerView({
                viewManager: this.waterFlowView
            })
        }
    }
}
```

# ScrollComponents简介


# 简介

# FAQ
[查看详情](http://xxxxx)

# 原理介绍


# 开源协议

本项目基于 [Apache License 2.0](./LICENSE) ，请自由地享受和参与开源。