# GridScrollComponent

**Repository Path**: chu183/GridScrollComponent

## Basic Information

- **Project Name**: GridScrollComponent
- **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-08-21
- **Last Updated**: 2025-08-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Implementing Grid Pages Based on ScrollComponents

## Overview

This sample demonstrates how to use ScrollComponents to build grid pages for the following scenarios:

- Reuse of grid cell components and cross-page component
- Accelerated first-screen rendering of grids
- Grid data processing: pull-down-to-refresh, pull-up-to-load, and long-press-to-delete
- Setting grid arrangement modes
- Displaying data in grids
- Setting row and column spacing in grids
- Scrollable grid layouts
- Controlling grid scroll positions
- Nested grid scrolling
- Dragging grid cells
- Adaptive grids and adaptive columns
- Setting grid cell heights based on the tallest cell in the current row
- Setting edge fading to grids
- Setting grid cell styles

## Preview

<img src="./screenshots/img_en.png" width = "40%" alt="image"/>

## Project Directory

```
entry/src/main/ets 
├──common 
|  ├──constants 
|  |  └──CommonConstants.ets           // Common constants. 
|  └──utils            
|     ├──Logger.ets                    // Log class. 
|     └──Utils.ets                     // Utility class. 
├──entryability 
|  └──GridAbility.ets                  // Application entry. 
├──model 
|  ├──mock.ets                         // Mock data. 
|  ├──types.ets                        // Data model. 
|  ├──PhotoModel.ets                   // Image data. 
|  ├──WorkModel.ets                    // Work data. 
|  ├──UserInfoModel.ets                // User information. 
|  ├──NumberModel.ets                  // Number data. 
|  └──WordModel.ets                    // Text data. 
├──view 
|  ├──PhotoGridComponent.ets           // Photo grid view. 
|  ├──WorkComponent.ets                // Work grid view. 
|  ├──WorkHeadComponent.ets            // Work page header view. 
|  ├──CardGridComponent.ets            // Card grid view. 
|  ├──NumberGridComponent.ets          // Number grid view. 
|  └──WordGridComponent.ets            // Word grid view. 
├──viewModel 
|  ├──PhotoGridViewModel.ets           // Photo grid page view model. 
|  ├──WorkGridViewModel.ets            // Work grid page view model. 
|  ├──CardGridViewModel.ets            // Card grid page view model. 
|  ├──NumberGridViewModel.ets          // Number grid page view model. 
|  └──WordGridViewModel.ets            // Word grid page view model. 
└──pages 
   ├──Index.ets                        // Navigation page. 
   ├──PhotoGridPage.ets                // Photo grid page. 
   ├──WorkGridPage.ets                 // Work grid page. 
   ├──CardGridPage.ets                 // Card grid page. 
   ├──NumberGridPage.ets               // Number grid page. 
   └──WordGridPage.ets                 // Word grid page.
```

## Constraints
- The number of rows and columns occupied by a child component cannot be set.
- Pinch gesture recognition is not supported.

## Permission
- The `ohos.permission.INTERNET` permission is required for downloading network resources.

## Description

1. PhotoGridPage.ets: Implements the reuse of components with the same grid cell structure and grid arrangement mode setting.
2. WorkGridPage.ets: Implements component reuse for cells with heterogeneous structures, cross-page grid reuse with PhotoGridPage.ets, pull-down-to-refresh, pull-up-to-load, dragging cells, nested scrolling, and edge-fading effects.
3. CardGridPage.ets: Implements component reuse with splittable combination of substructures within grid cells, accelerated first-screen rendering, data display, row and column spacing setting, scrollable layout, cell-style setting, and long-press-to-delete cell.
4. NumberGridPage.ets: Implements grid adaptive scenario.
5. WordGridPage.ets: Implements the grid adaptive column scenario and the scenario where grid cell heights are set based on the tallest cell in the current row.

## How to Implement

1. Define the grid view manager class and register child node templates. GridManager is the base class of the grid view manager, which can be extended by customizing the GridViewManager based on service requirements.
    ```arkts
    // entry\src\main\ets\view\WordCellComponent.ets 
    
    @Component 
    export default struct WordCell { 
      @State word: WordViewModel = new WordViewModel(); 
    
      // Component reuse requires implementing the aboutToReuse function. 
      aboutToReuse(params: Record<string, ESObject>) { 
        let input = params as WordCellData; 
        this.word = input.word; 
      } 
    
      build() { 
        Text(this.word.value) 
      } 
    }
    ```
    ```arkts
    // entry\src\main\ets\view\WordGridComponent.ets 
    
    import { GridManager, NodeItem, RecyclerView } from "@hadss/scroll_components"; 
    import WordCell from "./WordCellComponent"; 
    
    @Component 
    export default struct WordGridComponent { 
      // Grid view manager instance. 
      gridViewManager: GridViewManger = new GridViewManger({ defaultNodeItem: 'word', context: this.getUIContext() }); 
    
      aboutToAppear(): void { 
        // Register node templates and establish a mapping between the identifier and the builder function. 
        this.gridViewManager.registerNodeItem('word', wrapBuilder(buildWordCell)); 
      } 
    } 
    
    // Extend a custom view manager. 
    class GridViewManger extends GridManager { 
    
      // Obtain the reusable node by unique identifier and pass node data. 
      onWillCreateItem(index: number, data: WordViewModel) { 
        let node: NodeItem<WordCellData> | null = this.dequeueReusableNodeByType('word'); 
        node.setData({ word: data }) 
        return node; 
      } 
    } 
    
    @Builder 
    function buildWordCell(data: ESObject) { 
      WordCell({ word: data.data }) 
    }
    ```
2. Grid component initialization
   ```arkts
   // entry\src\main\ets\view\WordGridComponent.ets 
   
   aboutToAppear(): void { 
     this.gridViewManager.setViewStyle() 
       .alignItems(GridItemAlignment.STRETCH); 
   
     this.gridViewManager.setViewStyle() 
       .columnsTemplate('repeat(auto-fill, 70)') 
       .columnsGap(5) 
       .rowsGap(5); 
   }
   ```
3. Set the data source for component rendering
    ```arkts
    // entry\src\main\ets\view\WordGridComponent.ets 
    
    @Component 
    export default struct WordGridComponent { 
      gridViewManager: GridViewManger = new GridViewManger({ defaultNodeItem: 'word', context: this.getUIContext() }); 
      viewModel: WordGridViewModel = new WordGridViewModel(this.gridViewManager); 
    
      aboutToAppear(): void { 
        // viewModel data loading. 
        this.viewModel.loadData(); 
      } 
    
      build() { 
        Column() { 
          // Render view component. 
          RecyclerView({ 
            viewManager: this.gridViewManager 
          }) 
        } 
        .width('100%') 
      } 
    }
    ```
    ```arkts
    // entry\src\main\ets\viewModel\WordGridViewModel.ets 
    
    async loadData() { 
      setTimeout(() => { 
        for (let index = 0; index < 15; index++) { 
          // Simulate request data. 
          let model: WordModel = new WordModel(); 
          model.value = `N ${index}`; 
          let viewModel: WordViewModel = new WordViewModel(); 
          viewModel.updateModel(model); 
          this.data.push(viewModel); 
        } 
        // Set the data source. 
        this.gridViewManager?.setDataSource(this.data); 
      }, 100); 
    }
    ```

## Introduction to ScrollComponents

As a high-performance scrolling solution, ScrollComponents helps you achieve smoother scrolling experiences in complex page scenarios such as long lists and waterfalls.

Its underlying system uses a custom reuse pool to address efficiency issues under complex scenarios, offering higher reuse efficiency compared to the native Reusable.

You can achieve high-performance scrolling with minimal code, without needing to handle the complexities of component reuse pool management or other performance optimization interactions.

## Features
- Smooth scrolling for grid pages.
- Lazy loading by default.
- Component reuse, which prevents frame drops during scrolling and improves scrolling performance.
- Reused pool sharing, which enables component reuse across pages and parent components.
- Pre-creation, which reduces initial frame drops upon cold startup and improves scrolling performance.
- Preloading, which loads data in advance during scrolling to improve browsing experience.

## FAQs

[View Details](https://gitcode.com/openharmony-sig/scroll_components/blob/master/docs/FAQ.md)

## Principles

[View Details](https://gitcode.com/openharmony-sig/scroll_components/blob/master/README.md#%E5%8E%9F%E7%90%86%E4%BB%8B%E7%BB%8D)

## Repositories Involved

[scroll_components](https://gitcode.com/openharmony-sig/scroll_components/tree/master)