如果在使用过程中有任何问题，可以在GitCode提Issue，会及时跟进。issue地址：issues。

StickyItemDecoration — 粘性头部列表装饰器（HarmonyOS 版）

基于 https://github.com/oubowu/StickyItemDecoration 开发，适配鸿蒙版本。

StickyItemDecoration 是一个基于滚动事件驱动的粘性头部（Sticky Header）列表装饰器库。支持 List/Grid/WaterFlow 三种布局的粘性头部吸附效果、偏移动画、可见性回调、全宽适配和分割线配置。

环境要求

• DevEco Studio：5.0+（推荐最新正式版）
• compatibleSdkVersion：参考 ohos-hardemo 工程配置（API 12+）
• hvigor 版本：详见 ohos-hardemo 工程配置
• Node.js：详见 ohos-hardemo 工程配置

编译依赖

oh-package.json5

{
  "dependencies": {
    "sticky-item-decoration": "file:../library"
  }
}

该库纯 ArkTS 实现，无外部 ohpm 依赖。

快速开始 / 安装

方式一：本地 HAR 依赖（开发阶段）

从源码构建 HAR：

cd ohos-hardemo
hvigorw assembleHar --mode module -p module=library@default -p product=default --no-daemon

产物路径：ohos-hardemo/library/build/default/outputs/default/library.har

在目标工程的 oh-package.json5 中添加：

{
  "dependencies": {
    "sticky-item-decoration": "file:../path/to/library"
  }
}

方式二：ohpm 依赖（发布后）

{
  "dependencies": {
    "sticky-item-decoration": "^1.0.0"
  }
}

初始化和宿主接入

1. 创建控制器

import { StickyHeaderController, StickyHeadComponent } from 'sticky-item-decoration';

// 指定粘性头部类型标识
const STICKY_HEAD_TYPE = 0;
const controller = new StickyHeaderController(STICKY_HEAD_TYPE);

2. 在 UI 中使用

@Entry
@Component
struct MyListPage {
  @State stickyHeadPosition: number = -1;

  build() {
    Stack() {
      // 数据列表
      List() {
        ForEach(this.dataList, (item: ItemData, index: number) => {
          ListItem() {
            Text(item.name)
          }
          .onClick(() => {
            // 数据行点击
          })
        })
      }
      .onScrollIndex((firstIndex: number) => {
        controller.onScroll(firstIndex, (pos: number) => {
          return this.dataList[pos].type;
        });
        this.stickyHeadPosition = controller.currentStickyHeadPosition;
      })

      // 粘性头部覆盖层
      StickyHeadComponent({
        stickyHeadPosition: this.stickyHeadPosition,
        stickyHeadBuilder: (): void => { this.stickyHeadContent() },
        onStickyChange: (pos: number, visible: boolean) => {
          console.info(`Sticky head position: ${pos}, visible: ${visible}`);
        },
        onDataChange: (pos: number) => {
          // 粘性头部数据更新
        }
      })
    }
  }

  @Builder
  stickyHeadContent() {
    Text('粘性头部标题')
      .fontSize(16)
      .fontColor(Color.White)
      .backgroundColor('#aaaaff')
      .width('100%')
      .padding({ top: 10, bottom: 10, left: 16 })
  }
}

3. 控制方法

// 启用/禁用
controller.enableStickyHead(false);

// 复位位置缓存
controller.reset();

API 参考

核心控制器

类	方法/属性	说明
StickyHeaderController	constructor(type, listener?)	创建控制器，指定粘性头部类型标识
	onScroll(firstIndex, getItemViewType)	滚动事件入口，由宿主在 onScrollIndex 中调用
	enableStickyHead(enable)	启用/禁用粘性头部
	reset()	复位缓存的位置和偏移
	currentStickyHeadPosition	当前粘性头部位置（绑定用）
	scrollOffset	当前滚动偏移（绑定用）
	setOnStickyChangeListener(listener)	设置可见性变化回调
	setDataCallback(callback)	设置数据变更回调
	findStickyHeadPosition(from, getItemViewType)	递减查找粘性头部位置

UI 组件

组件	属性	说明
StickyHeadComponent	stickyHeadPosition（@Prop）	粘性头部位置绑定
	stickyHeadBuilder（@BuilderParam）	宿主自定义粘性头部渲染
	onStickyChange（回调）	位置/可见性变化通知
	onDataChange（回调）	数据变化通知
	animateOffset(offset)	驱动偏移动画

回调接口

接口	方法	说明
OnStickyChangeListener	onScrollable(offset)	粘性头部可滚动时回调
	onInVisible()	粘性头部不可见时回调
DataCallback	onDataChange(pos)	粘性头部位置变更回调

工具类

类	方法	说明
DividerHelper	drawTop(color, strokeWidth?, startMargin?, endMargin?)	顶部分割线配置
	drawBottom(...)	底部分割线配置
	drawLeft(...)	左侧分割线配置
	drawRight(...)	右侧分割线配置
	drawTopAlignItem(...)	顶部对齐分割线
	drawBottomAlignItem(...)	底部对齐分割线
	drawLeftAlignItem(...)	左侧对齐分割线
	drawRightAlignItem(...)	右侧对齐分割线
FullSpanUtil	isStickyHead(type, stickyHeadType)	判断是否为粘性头部
	getGridColumnStart/End(...)	Grid 全宽跨列适配
	getFlowRowStart/End(...)	WaterFlow 全宽跨行适配

模型类型

接口	字段	说明
StickyHeadConfig	stickyHeadType, enableStickyHead?, onStickyChangeListener?, dataCallback?	粘性头部配置参数
DividerConfig	color, strokeWidth, startMargin, endMargin	分割线配置参数

已支持能力

• List/Grid/WaterFlow 粘性头部吸附效果
• 自定义粘性头部 UI（@BuilderParam）
• 偏移动画（animateTo 驱动）
• 粘性头部可见性回调
• 启用/禁用控制
• Grid/WaterFlow 全宽跨列适配
• 8 方向分割线配置（水平分割线使用 List.divider()，垂直分割线由宿主实现）

未支持／裁剪能力

能力	类型	说明
RecyclerView.AdapterDataObserver 自动监听	裁剪	ArkUI 使用 @State 数据驱动模式，无需主动监听
findChildViewUnder 命中检测	延后	使用 scrollOffset + headHeight 范围判断替代
MarginLayoutParams 边距感知	延后	使用 List.divider().startMargin/endMargin 模拟

Demo 运行方式

1. 进入 ohos-hardemo 目录：

   cd ohos-hardemo
   

2. 安装依赖：

   ohpm install
   

3. 编译 HAP：

   hvigorw -e assembleHap --mode module -p product=default -p buildMode=debug --no-daemon
   

4. 产物路径：ohos-hardemo/entry/build/default/outputs/default/entry-default-unsigned.hap

5. 使用 hdc 安装至设备：

   hdc install ohos-hardemo/entry/build/default/outputs/default/entry-default-unsigned.hap
   

6. 应用安装后启动，首页展示 4 个 Demo 入口卡片：

   • 粘性头部 Demo：等效 Android MainActivity，展示完整粘性头部交互
   • 小粘性头 Demo：等效 Android SecondActivity，展示小型粘性头部模式
   • 分割线工具 Demo：DividerHelper 8 个方向分割线演示
   • 全宽适配 Demo：FullSpanUtil 配合 Grid 布局演示

如何贡献

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交修改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

开发要求

• 所有新代码须通过 assembleHar 编译
• 须包含对应的 Demo 页面展示
• 须通过代码审查（P0/P1=0）

开源许可

Apache-2.0

Copyright 2016 oubowu

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.