sticky-headers-recyclerview

Introduction

sticky-headers-recyclerview is a ListView component with fixed group headers. This library is based on sticky-headers-recyclerview The original library is adapted to enable it to run on OpenHarmony, while retaining its existing usage and features.

Effect demonstration：

How to Install

   ohpm install @ohos/sticky-headers-recyclerview

For details about the OpenHarmony ohpm environment configuration, see OpenHarmony HAR.

How to Use

Import and use

import { RecyclerView, Stroke, TimeTable } from '@ohos/sticky-headers-recyclerview';

@Entry
@Component
struct HorizontalLayout {
 @State tableData: TimeTable[] = [
   {
     title: 'A',
     projects: ['Apple', 'Apartment', 'Airport', 'Animal', 'Artist', 'Antique']
   },
   {
     title: 'B',
     projects: ['Building', 'Bicycle', 'Banana', 'Bottle', 'Basket', 'Bridge']
   },
   {
     title: 'C',
     projects: ['Car', 'Computer', 'Camera', 'Castle', 'Candle', 'Clock']
   },
   {
     title: 'D',
     projects: ['Diamond', 'Desert', 'Dolphin', 'Dinosaur', 'Dragon', 'Drum']
   }
 ];
 @State linearLayout: Axis = Axis.Horizontal;
 @State listSpace: number = 100;
 @State strokeDivider: Stroke = { width: 10, color: 'red' };
 @State scrollBar: BarState = BarState.Off;

 @Builder
 headConstruction(text: string, index: number, direction: Axis) {
   Row() {
     Text(text)
       .width(direction == Axis.Vertical ? '100%' : 50)
       .height(direction == Axis.Vertical ? 50 : '100%')
       .fontSize(20)
       .backgroundColor(0xAABBCC)
       .padding(10)
       .onClick(() => {
         this.getUIContext().getPromptAction().showToast({
           message: `Index: ${index}, Current Direction: ${direction}, Current Group Data: ${JSON.stringify(this.tableData[index])}`,
           duration: 2000
         });
       })
   }
 }

 @Builder
 detailConstruction(project: string, index: number, superstratuItem: string, superstratumIndex: number,
   direction: Axis) {
   Text(project)
     .width(direction == Axis.Vertical ? '100%' : 100)
     .height(direction == Axis.Vertical ? 100 : '100%')
     .fontSize(20)
     .textAlign(TextAlign.Center)
     .backgroundColor(0xFFFFFF)
     .onClick(() => {
       this.getUIContext().getPromptAction().showToast({
         message: `Current Item: ${project}, Item Index: ${index}, Header Content: ${superstratuItem}, Header View Index: ${superstratumIndex}, Current Direction: ${direction.toString()}`,
         duration: 2000
       });
     })
 }

 build() {
   Column() {
     RecyclerView({
       // Bind data source
       tableData: this.tableData,
       // Pass header builder
       headConstruction: this.headConstruction,
       // Pass list item builder
       detailConstruction: this.detailConstruction,
       // Set to horizontal layout
       isListDirection: this.linearLayout,
       // Set list item spacing
       listSpace: this.listSpace,
       // Set divider style
       strokeDivider: this.strokeDivider,
       // Set scrollbar state
       scrollBar: this.scrollBar
     })
       .height('70%')
       .backgroundColor(0xDCDCDC)
   }
   .height('100%')
   .width('100%')
   .backgroundColor(0xF5F5F5)
   .padding(10)
 }
}

For details, see the implementation on the sample page of the open-source library.

Available APIs

Parameter Name	Type	Required	Description
tableData	TimeTable[]	Yes	A data structure used to define the grouping of a list with viscosity properties
headConstruction	@Builder	Yes	List header builder
detailConstruction	@Builder	Yes	List item details builder
isListDirection	Axis	Yes	List direction control
listSpace	number	No	List item spacing Controls the spacing between list items. Default: 0
strokeDivider	Stroke	No	Spacing line style configuration, default: width: 0, color: ''
scrollBar	BarState	No	Used to control the display state of the list scroll bar. Default: BarState.Off
isStackFromEnd	boolean	No	(api>=19) Whether to layout in reverse order, default value: false

TimeTable attribute specification：

Name	Type	Read Only	Required	Description
title	string	No	No	Group Title
projects	string[]	No	No	List of items within the group

Stroke attribute specification：

Name	Type	Read Only	Required	Description
width	number	No	No	Separator line width
color	string	No	No	Separator color

Explanation:

1. The source library provides the "StickyRecyclerHeadersTouchListener" for handling header click events. However, in OpenHarmony, since the headers are passed in from the outside, the outside needs to use the "onClick" event to obtain the information. The demo provides an example.
2. The source library implements the ItemVisibilityAdapter for implementing visibility control, which is designed to adapt to the pre-loading scenario of RecyclerView. It filters out the items that are pre-loaded but not visible, avoiding errors in header calculations. RecyclerView is a unique view for Android. OpenHarmony uses the List component to achieve this and does not involve visibility control.

Constraints

This project has been verified in the following version:

• DevEco Studio: 6.0.0 Release（6.0.0.858）, SDK: API20(6.0.0.47 SP16)

Directory Structure

|---- ohos_sticky-headers-recyclerview  
|     |---- entry    # Sample code
|     |---- library  # ohos_sticky-headers-recyclerview Library
|     |     |   └─src
|     |     |   │---└─main  
|     |     |   |----   └─ets
|     |     |   │----      └──components  # Default directory
|     |     |                 │----StickyHeadersRecyclerView.ets # Viscous head component
|     |     |   │----      └──model       # Model
|     |     |                 │----ViewModel.ets # Adhesive head interface
|     |     |---- index.ets  # External APIs
|     |---- README.md     # Readme    
|     |---- README_zh.md  # Readme  

How to Contribute

If you find any problem when using the project, submit an Issue or a PR.

License

This project is licensed under Apache License 2.0.