输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
RelativeContainer
CustomDialogController
animateTo
CTRL+K
文档管理中心

HarmonyOS

输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
RelativeContainer
CustomDialogController
animateTo
CTRL+K
FAQ

滚动与滑动组件实现吸顶效果

更新时间: 2026-06-26 09:07
本文导读

问题现象

在HarmonyOS中，如何使用不同的滚动与滑动组件，实现标题吸顶效果？

背景知识

吸顶效果是网页开发中的一种常见交互设计，指当用户滚动页面时，某个元素（如导航栏、标题栏、工具栏等）会固定在浏览器窗口的顶部（或其他指定位置），保持始终可见，不会随着页面滚动而消失。在开发过程中，吸顶效果通常用于需要保持关键元素始终可见的场景，以提升用户体验和操作效率。

在HarmonyOS中有多种实现吸顶效果的方案，以及不同的吸顶效果，不同方案及其需要了解的知识如下：

  • Tabs：通过页签进行内容视图切换的容器组件，每个页签对应一个内容视图。
  • nestedScroll：设置前后两个方向的嵌套滚动模式，实现与父组件的滚动联动。
  • List：列表包含一系列相同宽度的列表项。适合连续、多行呈现同类数据，例如图片和文本。
  • sticky：配合ListItemGroup组件使用，设置ListItemGroup中header是否要吸顶或footer是否要吸底。sticky属性可以设置为StickyStyle.Header|StickyStyle.Footer以同时支持header吸顶和footer吸底。

解决方案

本文主要介绍实现普通吸顶效果、单标题滚动嵌套吸顶效果和多标题滚动嵌套吸顶效果的方案。

  • 普通吸顶效果
    • 方案一：通过Tabs组件的tabBar属性实现吸顶效果。可以自定义实现Tabs效果。
      示例代码如下：
      收起
      自动换行
      深色代码主题
      复制
      1. @Entry
      2. @Component
      3. export struct CommonSolutionOne {
      4.   subsController: TabsController = new TabsController();
      5.   @State arr: string[] = ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14', '15'];
      6. 

      7.   build() {
      8.     Tabs({ barPosition: BarPosition.Start, controller: this.subsController }) {
      9.       TabContent() {
      10.         List({ space: 10 }) {
      11.           ForEach(this.arr, (item: number) => {
      12.             ListItem() {
      13.               Row() {
      14.                 Text('item' + item)
      15.                   .fontSize(16)
      16.                   .height(72)
      17.                   .fontColor(Color.Black);
      18.               }
      19.               .width('100%')
      20.               .height(72)
      21.               .justifyContent(FlexAlign.Center);
      22.             }
      23.             .borderRadius(15)
      24.             .backgroundColor('#F1F3F5');
      25.           }, (item: string) => item);
      26.         }
      27.         .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      28.         .padding({ left: 10, right: 10 })
      29.         .width('100%')
      30.         .height('100%')
      31.         .scrollBar(BarState.Off);
      32.       }
      33.       .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      34.       .tabBar('关注')
      35.       .backgroundColor('#ffffff');
      36. 

      37.       TabContent() {
      38.         Text('推荐');
      39.       }
      40.       .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      41.       .tabBar('推荐')
      42.       .backgroundColor('#ffffff');
      43.     }
      44.     .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      45.     .backgroundColor('#ffffff');
      46.   }
      47. }

      实现效果如下：

    • 方案二：自定义标题的吸顶实现。若要实现Tabs页面切换效果，需要自定义页面切换逻辑。
      参考上文中方案一，示例代码如下：
      收起
      自动换行
      深色代码主题
      复制
      1. @Entry
      2. @Component
      3. export struct CommonSolutionTwo {
      4.   subsController: TabsController = new TabsController();
      5.   @State arr: string[] = ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14', '15'];
      6. 

      7.   build() {
      8.     Column() {
      9.       Row() {
      10.         // 吸顶标题
      11.         Text('自定义占位标题')
      12.           .width('100%')
      13.           .height(60)
      14.           .textAlign(TextAlign.Center)
      15.           .backgroundColor('#66666666');
      16.       };
      17. 

      18.       List({ space: 10 }) {
      19.         ForEach(this.arr, (item: number) => {
      20.           ListItem() {
      21.             Row() {
      22.               Text('item' + item)
      23.                 .fontSize(16)
      24.                 .height(72)
      25.                 .fontColor(Color.Black);
      26.             }
      27.             .width('100%')
      28.             .height(72)
      29.             .justifyContent(FlexAlign.Center);
      30.           }
      31.           .borderRadius(15)
      32.           .backgroundColor('#F1F3F5');
      33.         }, (item: string) => item);
      34.       }
      35.       .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      36.       .padding({ left: 10, right: 10 })
      37.       .width('100%')
      38.       .scrollBar(BarState.Off)
      39.       .layoutWeight(1); // 更换List组件height属性，高度限制以layoutWeight(1)的形式自动填充父组件高度
      40.     }
      41.     .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      42.     .width('100%')
      43.     .height('100%') // 普通吸顶效果时，滚动组件的父组件可以不设置高度，但是滚动嵌套吸顶时一定要设置高度限制为100%
      44.     .backgroundColor('#ffffff');
      45.   }
      46. }

      实现效果如下：

  • 单标题滚动嵌套吸顶效果
    • 方案一： 通过nestedScroll属性，实现吸顶效果。由于nestedScroll属性是滚动与滑动组件的通用属性，理论上在滚动组件嵌套的过程中，支持该属性的滚动组件都可以实现吸顶效果。以Tabs组件为例，示例代码如下：
      收起
      自动换行
      深色代码主题
      复制
      1. @Entry
      2. @Component
      3. struct SingleTitleSolutionOne {
      4.   subsController: TabsController = new TabsController();
      5.   @State arr: string[] = ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14', '15'];
      6. 

      7.   build() {
      8.     Scroll() {
      9.       Column() {
      10.         Column() {
      11.           Text('自定义占位标题')
      12.             .fontSize(30)
      13.             .width('100%')
      14.             .height(200)
      15.             .backgroundColor('#66666666')
      16.             .textAlign(TextAlign.Center);
      17.         }
      18.         .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      19. 

      20.         Tabs({ barPosition: BarPosition.Start, controller: this.subsController }) {
      21.           TabContent() {
      22.             List({ space: 10 }) {
      23.               ForEach(this.arr, (item: number) => {
      24.                 ListItem() {
      25.                   Row() {
      26.                     Text('item' + item)
      27.                       .fontSize(16)
      28.                       .height(72)
      29.                       .fontColor(Color.Black);
      30.                   }
      31.                   .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      32.                   .width('100%')
      33.                   .height(72)
      34.                   .justifyContent(FlexAlign.Center);
      35.                 }
      36.                 .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      37.                 .borderRadius(15)
      38.                 .backgroundColor('#F1F3F5');
      39.               }, (item: string) => item);
      40.             }
      41.             .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      42.             .padding({ left: 10, right: 10 })
      43.             .width('100%')
      44.             .height('100%')
      45.             .scrollBar(BarState.Off)
      46.             .nestedScroll({
      47.               scrollForward: NestedScrollMode.PARENT_FIRST, // 向上滚动PARENT_FIRST：父组件先滚动，父组件滚动到边缘以后自身滚动。
      48.               scrollBackward: NestedScrollMode.SELF_FIRST // 向下滚动SELF_FIRST：自身先滚动，自身滚动到边缘以后父组件滚动。
      49.             });
      50.           }
      51.           .clip(false)
      52.           .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      53.           .tabBar('关注')
      54.           .backgroundColor('#ffffff');
      55. 

      56.           TabContent() {
      57.             Text('推荐');
      58.           }
      59.           .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      60.           .tabBar('推荐')
      61.           .backgroundColor('#ffffff');
      62.         }
      63.         .clip(false)
      64.         .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      65.         .backgroundColor('#ffffff');
      66.       }
      67.       .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      68.       .width('100%');
      69.     }
      70.     .clip(false)
      71.     .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      72.     .edgeEffect(EdgeEffect.Spring)
      73.     .friction(0.6)
      74.     .backgroundColor('#ffffff')
      75.     .scrollBar(BarState.Off)
      76.     .width('100%')
      77.     .height('100%');
      78.   }
      79. }

      效果预览：

      说明

      自定义标题的实现方式，此处主要讲解滚动组件嵌套实现方式。若是想要以自定义标题实现滚动嵌套吸顶效果，滚动组件的父组件一定要设置高度限制为100%，若不设置高度限制，父组件自适应高度会导致吸顶失效，可详见下文中“多标题滚动嵌套吸顶效果”的方案一，其内第一个标题为自定义标题，及其父组件高度注释。

    • 方案二： 由于Waterflow布局本身不支持吸顶，如需使用Waterflow布局实现吸顶效果，可以在滚动组件上通过Stack叠加一个组件实现，示例代码如下：
      收起
      自动换行
      深色代码主题
      复制
      1. // 瀑布流布局项数据模型（用于描述每个子项的布局属性)
      2. export class WaterFlowItemModel {
      3.   fullWidth: boolean = false;
      4.   stickyTop: number | undefined = undefined;
      5.   height: number = 0;
      6.   width: number = 0;
      7.   bgColor: string = '#f0f0f0';
      8. }
      9. 

      10. // 瀑布流数据源实现类
      11. export class WaterFlowDataSource implements IDataSource {
      12.   private dataArray: WaterFlowItemModel[] = [];
      13.   private listeners: DataChangeListener[] = [];
      14. 

      15.   constructor() {
      16.     this.dataArray = [];
      17.     // 生成10个瀑布流测试数据项
      18.     for (let i = 0; i < 10; i++) {
      19.       const model = new WaterFlowItemModel();
      20.       model.fullWidth = i % 5 === 4;
      21.       model.height = 120;
      22.       model.bgColor = '#f0f0f0';
      23.       this.dataArray.push(model);
      24.     }
      25.   }
      26. 

      27.   // 获取数据总量
      28.   totalCount(): number {
      29.     return this.dataArray.length;
      30.   }
      31. 

      32.   // 根据索引获取单个数据项
      33.   getData(index: number) {
      34.     return this.dataArray[index];
      35.   }
      36. 

      37.   // 注册数据变更监听器
      38.   registerDataChangeListener(listener: DataChangeListener) {
      39.     if (this.listeners.indexOf(listener) < 0) {
      40.       this.listeners.push(listener);
      41.     }
      42.   }
      43. 

      44.   // 移除已注册的数据变更监听器
      45.   unregisterDataChangeListener(listener: DataChangeListener) {
      46.     const pos = this.listeners.indexOf(listener);
      47.     if (pos >= 0) {
      48.       this.listeners.splice(pos, 1);
      49.     }
      50.   }
      51. }
      52. 

      53. @Entry
      54. @Component
      55. struct SingleTitleSolutionTwo {
      56.   scroller: Scroller = new Scroller();
      57.   datasource: WaterFlowDataSource = new WaterFlowDataSource();
      58.   @State scrollOffset: number = 0;
      59. 

      60.   build() {
      61.     Stack({ alignContent: Alignment.TopStart }) {
      62.       WaterFlow({ scroller: this.scroller }) {
      63.         LazyForEach(this.datasource, (item: WaterFlowItemModel, index) => {
      64.           FlowItem() {
      65.             // 当索引不为1，展示当前索引值
      66.             if (index !== 1) {
      67.               Text(`${index}`);
      68.             }
      69.           }
      70.           .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      71.           .margin({ right:20,bottom:12,left:19 })
      72.           .borderRadius(15)
      73.           .onClick(() => {
      74.             console.info('onClick ---- ', index);
      75.           })
      76.           .width('90%')
      77.           .height(item.height)
      78.           // .backgroundColor(index === 1 ? '#00000000' : Color.White);
      79.           .backgroundColor('#F1F3F5')
      80.         }, (key: string) => key);
      81.       }
      82.       .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      83.       .edgeEffect(EdgeEffect.Spring)
      84.       .onWillScroll((offset: number) => {
      85.         this.scrollOffset = this.scroller.currentOffset().yOffset + offset;
      86.       })
      87.       .width('100%')
      88.       .height('100%')
      89.       .backgroundColor('#ffffff');
      90. 

      91.       // 在索引为1的WaterFlowItem上方叠加一个组件
      92.       Stack() {
      93.         Text('自定义占位标题')
      94.           .width('100%')
      95.           .height(this.datasource.getData(1).height)
      96.           .fontColor(Color.White)
      97.           .backgroundColor('#66666666')
      98.           .fontSize(17)
      99.           .textAlign(TextAlign.Center);
      100.       }
      101.       .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      102.       .hitTestBehavior(HitTestMode.Transparent)
      103.       .position({ x: 0, y: this.scrollOffset >= 120 ? 0 : 120 - this.scrollOffset });
      104. 

      105.     }
      106.     .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      107.     .width('100%')
      108.     .height('100%')
      109.     .clip(true);
      110.   }
      111. }

      实现效果如下：

  • 多标题滚动嵌套吸顶效果
    • 方案一：通过nestedScroll属性对滚动组件多次滚动嵌套，参考单标题滚动嵌套吸顶效果，示例代码如下：
      收起
      自动换行
      深色代码主题
      复制
      1. @Entry
      2. @Component
      3. struct MultipleTitleSolutionOne {
      4.   subsController: TabsController = new TabsController();
      5.   @State arr: string[] = ['1', '2', '3'];
      6.   @State arr1: string[] = ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14', '15'];
      7. 

      8.   build() {
      9.     Scroll() {
      10.       Column() {
      11.         Column() {
      12.           Text('自定义占位标题')
      13.             .fontSize(30)
      14.             .width('100%')
      15.             .height(200)
      16.             .backgroundColor('#66666666')
      17.             .textAlign(TextAlign.Center);
      18.         };
      19. 

      20.         Column() {
      21.           Row() {
      22.             Text('自定义占位标题') // 自定义实现标题吸顶，依旧采用Tabs组件也适用
      23.               .fontSize(16)
      24.               .height(60)
      25.               .width('100%')
      26.               .textAlign(TextAlign.Center);
      27.           }.backgroundColor('#6dbab8b8')
      28. 

      29.           Scroll() {
      30.             Column() {
      31.               ForEach(this.arr, (item: number) => {
      32.                 Row() {
      33.                   Text('item' + item)
      34.                     .fontSize(16)
      35.                     .height(72)
      36.                     .fontColor(Color.Black);
      37.                 }
      38.                 .width('100%')
      39.                 .height(72)
      40.                 .borderRadius(15)
      41.                 .margin({
      42.                   bottom: 10
      43.                 })
      44.                 .justifyContent(FlexAlign.Center);
      45.               }, (item: string) => item);
      46. 

      47.               Tabs({ barPosition: BarPosition.Start, controller: this.subsController }) {
      48.                 TabContent() {
      49.                   List({ space: 10 }) {
      50.                     ForEach(this.arr1, (item: number) => {
      51.                       ListItem() {
      52.                         Row() {
      53.                           Text('item' + item)
      54.                             .fontSize(16)
      55.                             .height(72)
      56.                             .fontColor(Color.Black);
      57.                         }
      58.                         .width('100%')
      59.                         .height(72)
      60.                         .justifyContent(FlexAlign.Center);
      61.                       }
      62.                       .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      63.                       .borderRadius(15)
      64.                       .backgroundColor(Color.White);
      65.                     }, (item: string) => item);
      66.                   }
      67.                   .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      68.                   .padding({ left: 10, right: 10 })
      69.                   .width('100%')
      70.                   .height('100%')
      71.                   .scrollBar(BarState.Off)
      72.                   .nestedScroll({
      73.                     scrollForward: NestedScrollMode.PARENT_FIRST, // 向上滚动PARENT_FIRST：父组件先滚动，父组件滚动到边缘以后自身滚动。
      74.                     scrollBackward: NestedScrollMode.SELF_FIRST // 向下滚动SELF_FIRST：自身先滚动，自身滚动到边缘以后父组件滚动。
      75.                   });
      76.                 }
      77.                 .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      78.                 .tabBar('关注')
      79.                 .backgroundColor('#F1F3F5');
      80. 

      81.                 TabContent() {
      82.                   Text('推荐');
      83.                 }
      84.                 .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      85.                 .tabBar('推荐')
      86.                 .backgroundColor('#F1F3F5');
      87.               }
      88.               .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      89.               .backgroundColor('#6dbab8b8');
      90.             }
      91.             .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      92.             .backgroundColor(Color.White)
      93.             .width('100%');
      94.           }
      95.           .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      96.           .width('100%')
      97.           .layoutWeight(1)
      98.           .scrollBar(BarState.Off)
      99.           .nestedScroll({
      100.             scrollForward: NestedScrollMode.PARENT_FIRST, // 向上滚动PARENT_FIRST：父组件先滚动，父组件滚动到边缘以后自身滚动。
      101.             scrollBackward: NestedScrollMode.SELF_FIRST // 向下滚动SELF_FIRST：自身先滚动，自身滚动到边缘以后父组件滚动。
      102.           });
      103.         }
      104.         .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      105.         .height('100%') // 由于是自定义的标题，所以容纳标题和列表的父组件一定要设置高度为100%
      106.         .backgroundColor('#6dbab8b8');
      107.       }
      108.       .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      109.       .width('100%');
      110.     }
      111.     .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      112.     .edgeEffect(EdgeEffect.Spring)
      113.     .friction(0.6)
      114.     .backgroundColor(Color.White)
      115.     .scrollBar(BarState.Off)
      116.     .width('100%')
      117.     .height('100%');
      118.   }
      119. }

      实现效果如下：

    • 方案二：通过List组件的sticky属性，实现吸顶效果。

      常见场景一：header吸顶和footer吸底，该方案仅适用于List组件，具体实施方案参考官方示例：吸顶/吸底。

      常见场景二：多标题多tab菜单吸顶时，实现滑动时自动切换tab栏。通过onDidScroll方法，监听滚动事件，根据滚动偏移量动态计算当前处于哪个区域，再根据当前区块切换标题内容。示例代码如下：

      收起
      自动换行
      深色代码主题
      复制
      1. @Entry
      2. @Component
      3. struct MultipleTitleSolutionOnePlus {
      4.   @State data1: string[] = ['标题1', '标题2', '标题3', '标题4'];
      5.   @State data2: string[] = ['1', '2', '3', '4'];
      6.   @State selectIndex1: number = 0;
      7.   private listController: ListScroller = new ListScroller();
      8. 

      9.   @Builder
      10.   topBuilder1() {
      11.     Row() {
      12.       ForEach(this.data1, (item: string, index: number) => {
      13.         Text(item)
      14.           .fontColor(index == this.selectIndex1 ? Color.Blue : '#000')
      15.           .fontSize(index == this.selectIndex1 ? 20 : 16)
      16.           .fontWeight(index == this.selectIndex1 ? 500 : 400)
      17.           .onClick(() => {
      18.             this.listController.scrollToItemInGroup(0, index, true);
      19.           });
      20.       });
      21.     }
      22.     .backgroundColor(0xAABBCC)
      23.     .height(60)
      24.     .width('100%')
      25.     .justifyContent(FlexAlign.SpaceAround);
      26.   }
      27. 

      28.   @Builder
      29.   topBuilder2() {
      30.     Row() {
      31.       Text('第二组吸顶')
      32.         .padding(5)
      33.         .textAlign(TextAlign.Center);
      34.     }
      35.     .backgroundColor(0xAABBCC)
      36.     .justifyContent(FlexAlign.SpaceAround)
      37.     .height(60)
      38.     .width('100%');
      39.   }
      40. 

      41.   build() {
      42.     Column() {
      43.       List({ space: 10, scroller: this.listController }) {
      44.         ListItemGroup({ header: this.topBuilder1, space: 10 }) {
      45.           ForEach(this.data1, (item: string) => {
      46.             ListItem() {
      47.               Text(item)
      48.                 .width('90%')
      49.                 .height(200)
      50.                 .backgroundColor('#f1f3f5')
      51.                 .borderRadius(10)
      52.                 .textAlign(TextAlign.Center);
      53.             };
      54.           });
      55.         };
      56. 

      57.         ListItemGroup() {
      58.           ListItem() {
      59.             Text('其他内容')
      60.               .width('90%')
      61.               .height(400)
      62.               .backgroundColor('#f1f3f5')
      63.               .borderRadius(10)
      64.               .fontSize(16)
      65.               .textAlign(TextAlign.Center);
      66.           };
      67.         };
      68. 

      69.         ListItemGroup({ header: this.topBuilder2, space: 10 }) {
      70.           ForEach(this.data2, (item: string) => {
      71.             ListItem() {
      72.               Text(item)
      73.                 .width('90%')
      74.                 .height(200)
      75.                 .backgroundColor('#f1f3f5')
      76.                 .borderRadius(10)
      77.                 .textAlign(TextAlign.Center);
      78.             };
      79.           });
      80.         };
      81.       }
      82.       .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
      83.       .onDidScroll(() => {
      84.         let currentOffset = this.listController.currentOffset().yOffset;
      85.         this.selectIndex1 = Math.floor(currentOffset / 200);
      86.       })
      87.       .scrollBar(BarState.Off)
      88.       .sticky(StickyStyle.Header)
      89.       .alignListItem(ListItemAlign.Center);
      90.     };
      91.   }
      92. }

      实现效果如下：

      • 二级标题滚动嵌套吸顶效果

        第一层吸顶用Scroll嵌套List实现，第二层是利用ListItemGroup的sticky属性实现，示例代码如下：

        收起
        自动换行
        深色代码主题
        复制
        1. @Entry
        2. @Component
        3. struct MultipleTitleSolutionTwo {
        4.   private timeTable: TimeTable[] = [
        5.     {
        6.       title: 'Header2-0',
        7.       projects: ['内容1']
        8.     },
        9.     {
        10.       title: 'Header2-1',
        11.       projects: ['内容2']
        12.     },
        13.     {
        14.       title: 'Header2-2',
        15.       projects: ['内容3']
        16.     }
        17.   ];
        18. 

        19.   @Builder
        20.   itemHead(text: string, index: number) {
        21.     if (index === 0) {
        22.       Text().height(0);
        23.     } else {
        24.       Text(text)
        25.         .width('100%')
        26.         .textAlign(TextAlign.Center)
        27.         .fontColor(Color.Black)
        28.         .height(index === 1 ? 100 : 200)
        29.         .backgroundColor('#d1d1d6');
        30.     }
        31.   }
        32. 

        33.   build() {
        34.     Scroll() {
        35.       Column() {
        36.         Text('自定义占位标题')
        37.           .width('100%')
        38.           .height(200)
        39.           .backgroundColor('#66666666')
        40.           .textAlign(TextAlign.Center);
        41.         Column() {
        42.           // 第一层吸顶效果主要是通过设置nestedScroll属性以及父组件设置高度100%实现
        43.           Text('Header1')
        44.             .width('100%')
        45.             .height(100)
        46.             .backgroundColor('#4d666666')
        47.             .textAlign(TextAlign.Center)
        48.             .fontColor(Color.Black);
        49.           List() {
        50.             ForEach(this.timeTable, (item: TimeTable, index) => {
        51.               ListItemGroup({ header: this.itemHead(item.title, index) }) {
        52.                 ForEach(item.projects, (project: string) => {
        53.                   ListItem() {
        54.                     Text(project)
        55.                       .width('100%')
        56.                       .height(800)
        57.                       .fontSize(20)
        58.                       .textAlign(TextAlign.Center)
        59.                       .backgroundColor('#FFFFFF');
        60.                   }
        61.                 }, (item: string) => item);
        62.               }.clip(false);
        63.             });
        64.           }
        65.           .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
        66.           .sticky(StickyStyle.Header)
        67.           .scrollBar(BarState.Off)
        68.           .width('100%')
        69.           .height('calc(100% - 100vp)')
        70.           .backgroundColor('#ffffff')
        71.           .edgeEffect(EdgeEffect.Spring)
        72.           .nestedScroll({
        73.             scrollForward: NestedScrollMode.PARENT_FIRST,
        74.             scrollBackward: NestedScrollMode.SELF_FIRST
        75.           });
        76.         }.clip(false).expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM]).height('100%')
        77.       }.expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
        78.     }
        79.     .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
        80.     .clip(false)
        81.     .edgeEffect(EdgeEffect.Spring)
        82.     .friction(0.6)
        83.     .backgroundColor(Color.White)
        84.     .scrollBar(BarState.Off)
        85.     .width('100%')
        86.     .height('100%');
        87.   }
        88. }
        89. 

        90. interface TimeTable {
        91.   title: string;
        92.   projects: string[];
        93. }

        实现效果如下：

      • 动态控制二级标题滚动嵌套吸顶效果：

        在List组件onDidScroll方法里判断索引为2的组件滚动偏移量，动态调整Header1的position属性和List组件的contentStartOffset属性，示例代码如下：

        收起
        自动换行
        深色代码主题
        复制
        1. @Entry
        2. @Component
        3. struct MultipleTitleSolutionTwoDynamic {
        4.   @State header1Position: number = 0;
        5.   @State listStartOffset: number = 100;
        6.   private scroller = new Scroller();
        7.   private timeTable: TimeTableDynamic[] = [
        8.     {
        9.       title: 'Header2-0',
        10.       projects: ['内容1']
        11.     },
        12.     {
        13.       title: 'Header2-1',
        14.       projects: ['内容2']
        15.     },
        16.     {
        17.       title: 'Header2-2',
        18.       projects: ['内容3']
        19.     }
        20.   ];
        21. 

        22.   @Builder
        23.   itemHead(text: string, index: number) {
        24.     if (index === 0) {
        25.       Text().height(0);
        26.     } else {
        27.       Text(text)
        28.         .width('100%')
        29.         .textAlign(TextAlign.Center)
        30.         .fontColor(Color.Black)
        31.         .height(index === 1 ? 100 : 200)
        32.         .backgroundColor('#d1d1d6');
        33.     }
        34.   }
        35. 

        36.   build() {
        37.     Scroll() {
        38.       Column() {
        39.         Text('二级标题滚动嵌套吸顶')
        40.           .width('100%')
        41.           .height(200)
        42.           .backgroundColor('#66666666')
        43.           .textAlign(TextAlign.Center);
        44.         Column() {
        45.           // 第一层吸顶效果主要是通过设置nestedScroll属性以及父组件设置高度100%实现
        46.           Text('Header1')
        47.             .width('100%')
        48.             .height(100)
        49.             .backgroundColor('#4d666666')
        50.             .textAlign(TextAlign.Center)
        51.             .fontColor(Color.Black)
        52.             .position({ y: this.header1Position })
        53.             .zIndex(10);
        54.           List({ scroller: this.scroller }) {
        55.             ForEach(this.timeTable, (item: TimeTableDynamic, index) => {
        56.               ListItemGroup({ header: this.itemHead(item.title, index) }) {
        57.                 ForEach(item.projects, (project: string) => {
        58.                   ListItem() {
        59.                     Text(project)
        60.                       .width('100%')
        61.                       .height(800)
        62.                       .fontSize(20)
        63.                       .textAlign(TextAlign.Center)
        64.                       .backgroundColor('#ffffff');
        65.                   }.expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM]);
        66.                 }, (item: string) => item);
        67.               };
        68.             });
        69.           }
        70.           .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
        71.           .sticky(StickyStyle.Header)
        72.           .scrollBar(BarState.Off)
        73.           .width('100%')
        74.           .height('100%')
        75.           .backgroundColor('#ffffff')
        76.           .edgeEffect(EdgeEffect.Spring)
        77.           .contentStartOffset(this.listStartOffset)
        78.           .nestedScroll({
        79.             scrollForward: NestedScrollMode.PARENT_FIRST,
        80.             scrollBackward: NestedScrollMode.SELF_FIRST
        81.           })
        82.           .onDidScroll(() => {
        83.             let secondRect = this.scroller.getItemRect(2);
        84.             if (secondRect.x === 0 && secondRect.y === 0 && secondRect.width === 0 && secondRect.height === 0) {
        85.               console.info(`索引为${2}的组件不在屏幕上`);
        86.               return;
        87.             }
        88.             this.header1Position = Math.min(0, secondRect.y - 200);
        89.             this.listStartOffset = Math.max(0, 100 + this.header1Position);
        90.           });
        91.         }.height('100%');
        92.       };
        93.     }.expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])
        94.     .clip(false)
        95.     .edgeEffect(EdgeEffect.Spring)
        96.     .friction(0.6)
        97.     .backgroundColor(Color.White)
        98.     .scrollBar(BarState.Off)
        99.     .width('100%')
        100.     .height('100%');
        101.   }
        102. }
        103. 

        104. interface TimeTableDynamic {
        105.   title: string;
        106.   projects: string[];
        107. }

        实现效果如下：

常见FAQ

Q：还有其他组件能实现吸顶效果吗？

A：可以通过Stack组件或者zIndex属性，这类层叠布局实现组件吸顶。但这类层叠方式，该场景下并不常见，该方式更多用于网页中的客服按钮/回到页面顶部等场景。

Q：如何实现滑动时吸顶标题组件颜色渐变的效果？

A：可以通过onDidScroll等监听滑动的事件，监听组件的偏移量，从而控制吸顶的标题组件改变透明度、背景颜色等状态。

总结

以上方案差异及适用场景如下：

展开

分类

普通吸顶效果

单标题滚动嵌套吸顶效果

多标题滚动嵌套吸顶效果

实现方式

Tabs或自定义标题栏

nestedScroll属性滚动嵌套Tabs或自定义标题栏

nestedScroll属性滚动嵌套Tabs或自定义标题栏/List组件的sticky属性

自定义吸顶标题时易错问题

自定义标题栏时Scroll等滚动组件没有设置高度限制导致滚动组件超出安全区。其最大自适应高度为屏幕的100%高度，可以设置height属性或者layoutWeight(1)属性限制高度。

滚动组件的父组件一定要设置高度限制为100%，若不设置高度限制，父组件自适应高度会导致吸顶失效，因为滚动组件的最大自适应高度为屏幕高度，当滚动组件子组件高度之和大于屏幕的100%时，滚动组件高度自适应100%高度，会导致标题超出屏幕范围，导致吸顶失效。

当采用nestedScroll属性滚动嵌套实现时，与“单标题滚动嵌套吸顶效果”需要注意相似问题。

适用场景

适用于所有的带标题的软件场景

微信朋友圈等类似场景

电商软件主页场景
相关推荐
文档如何实现页面上滑tabBar和顶部标题的悬停以及属性动画效果
文档如何解决Scroll组件无法设置某个元素一直固定在首位的问题
文档tabBar实现自定义遮罩效果
文档Scroll嵌套List滚动回顶部的动画实现
文档如何设置Tabs沉浸式
文档如何实现List组件所有分组上滑吸顶效果及触底提示
文档Web组件嵌套滚动
文档HarmonyOS下HdsNavigation与HdsTabs实现滚动模糊及沉浸光感材质效果的解决方案
文档如何实现分组列表的吸顶/吸底效果
文档底部抽屉滑动效果
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明
在 FAQ 中进行搜索
请输入您想要搜索的关键词