# CollapsingToolbar

**Repository Path**: jackiehou/collapsing-toolbar

## Basic Information

- **Project Name**: CollapsingToolbar
- **Description**: 实现了HarmonyOS下的折叠工具栏效果
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-07-28
- **Last Updated**: 2025-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CollapsingToolbar

#### 介绍

HarmonyOS下折叠工具栏效果

![](https://gitee.com/jackiehou/image/raw/master/mnnpd-2tfrd.gif)

### 安装

```
ohpm install @jackiehou/collapsing-toolbar
```

### 使用说明

#### 状态管理V1

```ts
import { CollapsingToolbar, CollapsingToolbarState} from '@jackiehou/collapsing-toolbar'
```

```ts
  //折叠的状态
  @State collapsingState: CollapsingToolbarState = new CollapsingToolbarState()

  build() {
    Column() {
      CollapsingToolbar({
          collapseLength:this.param.collapseHeight,//收起来的高度,可以为0
          expandLength:this.param.expandHeight,//展开的高度，必须大于0
          state:this.collapsingState,//折叠的状态
          header: this.header,//顶部可折叠的内容
          content: this.content,//您的内容，如list等
        })
    }.height('100%')
    .width('100%')
  }

  @LocalBuilder //组件内部@Builder 建议使用@LocalBuilder，不然会碰到this指向的问题
  header() {
     //...
  }
  
  @LocalBuilder 
  content() {
    //...
  }
```

#### 状态管理V2

```ts
import { CollapsingToolbarStateV2, CollapsingToolbarV2} from '@jackiehou/collapsing-toolbar'

//折叠的状态
collapsingState: CollapsingToolbarStateV2 = new CollapsingToolbarStateV2()

CollapsingToolbarV2({
    collapseLength:this.param.collapseHeight,//收起来的高度,可以为0
    expandLength:this.param.expandHeight,//展开的高度，必须大于0
    state:this.collapsingState,//折叠的状态
    header: this.header,//顶部可折叠的内容
    content: this.content,//您的内容，如list等
  })

```

#### 注意事项

content包含list,grid,WaterFlow等需要为其设置nestedScroll属性

```ts
List() {
    //...
  }
  .nestedScroll({
    scrollForward: NestedScrollMode.PARENT_FIRST,
    scrollBackward: NestedScrollMode.SELF_FIRST
  })
```

#### 折叠工具栏的跟手动画

```ts
import {
  CollapsingToolbar,
  CollapsingToolbarState,
  lerp,
  lerpColor, lerpPercentage } from '@jackiehou/collapsing-toolbar'

  @LocalBuilder
  header() {//header的父组件是Stack，其alignContent属性为TopStart
    //header背景色
    Rect({ width: '100%', height: '100%' })
      .fill(this.expandBgColor)
      .opacity(this.collapsingState.progress) //折叠状态透明，展开状态显示
    //返回按钮
    SymbolGlyph($r('sys.symbol.chevron_left'))
      .renderingStrategy(SymbolRenderingStrategy.SINGLE)
      .fontSize(30)
      .fontWeight(FontWeight.Medium)
      .height(this.collapsingState.collapseHeight > 0 ? this.collapsingState.collapseHeight : 56)
      .align(Alignment.Center)
      .margin({ left: 15, })
      .translate({ y: this.collapsingState.yOffset })//pin效果，组件的y轴位置不随CollapsingToolbar滑动而变化
        /**
         *颜色插值器
         * lerpColor方法第一个参数colorStart：CollapsingToolbar完全折叠状态下的颜色
         * lerpColor方法第一个参数colorEnd：CollapsingToolbar完全展开状态下的颜色
         * lerpColor方法第三个参数this.collapsingState.progress：0到1的小数，0：CollapsingToolbar完全折叠状态，1：CollapsingToolbar完全展开状态
         */
      .fontColor([lerpColor(this.collapseFontColor, this.expandFontColor, this.collapsingState.progress)])
      .onClick(() => {
        router.back()
      })
    //标题
    Text('CollapsingToolbar')
      .height(this.collapsingState.collapseHeight > 0 ? this.collapsingState.collapseHeight : 56)
      .textAlign(TextAlign.Center)
      .margin({
        //collapse状态： 居左40vp，
        //expand状态：   左边距居中
        left: this.collapsingState.lerpX(40, '50%'),
        //collapse状态： top：折叠状态工具栏到顶部的距离，
        //expand状态：   上边距居中
        top: this.collapsingState.lerpY(this.collapsingState.maxOffset, '50%'),
      })
      .translate({
        //collapse状态： 不位移，
        //expand状态：   加上margin的expand状态 整体居中
        x: lerpPercentage('0%', '-50%', this.collapsingState.progress),
        y: lerpPercentage('0%', '-50%', this.collapsingState.progress),
      })
      .fontSize(lerp(16, 22, this.collapsingState.progress))
      .maxLines(1)
      .fontWeight(FontWeight.Medium)
      .fontColor(lerpColor(this.collapseFontColor, this.expandFontColor, this.collapsingState.progress))//fontColor颜色插值器

    SymbolGlyph($r('sys.symbol.heart'))
      .renderingStrategy(SymbolRenderingStrategy.SINGLE)
      .fontSize(25)
      .fontWeight(FontWeight.Medium)
      .height(this.collapsingState.collapseHeight > 0 ? this.collapsingState.collapseHeight : 56)
      .align(Alignment.Center)
      .position({ right: 0, bottom: 0 })//修改当前子组件在Stack的align，等同于BottomEnd
      .margin({ right: 15 })
      .fontColor([lerpColor(this.collapseFontColor, this.expandFontColor, this.collapsingState.progress)])//fontColor颜色插值器
  }
```

### 接口说明

#### CollapsingToolbar&CollapsingToolbarV2组件各项属性

| 名称             | 类型                                               | 是否必填 | 说明          |
|----------------|--------------------------------------------------|------|-------------|
| collapseLength | Dimension                                        | 是    | 折叠工具栏收起来的高度 |
| expandLength   | Dimension                                        | 是    | 折叠工具栏展开的高度  |
| state          | CollapsingToolbarState\|CollapsingToolbarStateV2 | 否    | 折叠工具栏的状态    |
| immersionProp  | ImmersionProp                                    | 否    | 沉浸式状态栏需要的属性 |
| isScrollSnap   | boolean                                          | 否    | 是否使用限位滚动    |
| edgeEffect     | EdgeEffect                                       | 否    | 设置边缘滑动效果    |
| headerAlign    | Alignment                                        | 否    | header的对齐方式 |
| header         | () => void                                       | 否    | 折叠工具栏的内容    |
| contentBuilder | () => void                                       | 是    | content内容   |
| log            | (tag:string,msg:string) => void)                 | 否    | 打印log的      |

#### CollapsingToolbarState&CollapsingToolbarStateV2 折叠工具栏的状态

| 方法名/字段名         | 参数/类型                                                                                  | 说明                                                                                    |
|-----------------|----------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
| progress        | number                                                                                 | 折叠工具栏progress，0到1的小数                                                                  |
| fraction        | number                                                                                 | edgeEffect设置为spring，顶部回弹状态下fraction会大于1                                               |
| yOffset         | number                                                                                 | 折叠工具栏的y轴偏移量，折叠状态为的值为expandHeight - collapseHeight，展开状态的值为0                            |
| collapseHeight  | number                                                                                 | 折叠工具栏收起来的高度                                                                           |
| expandHeight    | number                                                                                 | 折叠工具栏展开的高度                                                                            |
| width           | number                                                                                 | toolbar的宽度                                                                            |
| displayHeight   | number                                                                                 | toolbar显示区域高度，不包含状态栏高度，Scroll的edgeEffect设置为spring，顶部回弹状态下displayHeight会大于expandHeight |
| statusBarHeight | number                                                                                 | 状态栏高度，如果没有设置immersionProp将不会获取状态栏高度                                                   |
| maxOffset       | number                                                                                 | 折叠状态工具栏Y轴最大的偏移量                                                                       |
| isCollapsed     | boolean                                                                                | 工具栏是否收起                                                                               |
| isExpanded      | boolean                                                                                | 工具栏是否展开                                                                               |
| lerpX           | (collapse: number \| Percentage, expand: number \| Percentage) => number \| Percentage | x轴长度，偏移量等属性的插值器方法                                                                     |
| lerpY           | (collapse: number \| Percentage, expand: number \| Percentage) => number \| Percentage | y轴长度，偏移量等属性的插值器方法                                                                     |
| collapse        | (animation: ScrollAnimationOptions \| boolean) =>void                                  | 折叠工具栏                                                                                 |
| expand          | (animation: ScrollAnimationOptions \| boolean) =>void                                  | 展开工具栏                                                                                 |
| constructor     | state: ToolBarState                                                                    | 构造器参数state为工具栏初始的状态                                                                   |

#### ToolBarState枚举

| 枚举名称      | 说明  |
|-----------|-----|
| Collapsed | 收起来 |
| Expanded  | 展开  |

#### ImmersionProp

| 名称                 | 类型                  | 说明                        |
|--------------------|---------------------|---------------------------|
| isLayoutFullScreen | boolean             | 是否是全屏                     |
| types              | Array<SafeAreaType> | 组件的expandSafeArea属性的第一个参数 |
| edges              | Array<SafeAreaEdge> | 组件的expandSafeArea属性的第二个参数 |

#### 线性插值器方法说明

##### lerp 数值插值器

| 参数\|返回值  | 类型     | 说明                                                                                |
|----------|--------|-----------------------------------------------------------------------------------|
| start    | number | 插值的起始值                                                                            |
| stop     | number | 插值的结束值                                                                            |
| fraction | number | 介于0和1之间的参数表示插值的位置,包含0和1                                                           |
| return   | number | 当fraction为0时，结果为start；当fraction为1时，结果为stop；当fraction介于0和1之间时，结果是start和stop之间的某个值。 |

##### lerpInt 整数插值器

| 参数\|返回值  | 类型     | 说明                                                                                                          |
|----------|--------|-------------------------------------------------------------------------------------------------------------|
| start    | number | 插值的起始值                                                                                                      |
| stop     | number | 插值的结束值                                                                                                      |
| fraction | number | 介于0和1之间的参数表示插值的位置,包含0和1                                                                                     |
| return   | number | 当fraction为0时，结果为Math.round(start)；当fraction为1时，结果为Math.round(stop)；当fraction介于0和1之间时，结果是start和stop之间的某个整数值。 |

##### lerpPercentage 百分比插值器

| 参数\|返回值    | 类型         | 说明                                                                                                   |
|------------|------------|------------------------------------------------------------------------------------------------------|
| startValue | Percentage | 插值的起始值，百分比类型 例如'20%'                                                                                 |
| endValue   | Percentage | 插值的结束值，百分比类型 例如'80%'                                                                                 |
| fraction   | number     | 介于0和1之间的参数表示插值的位置,包含0和1                                                                              |
| return     | Percentage | 当fraction为0时，结果为startValue；当fraction为1时，结果为endValue；当fraction介于0和1之间时，结果是startValue和stopValue之间的某个值。 |

##### lerpPercent 数值/百分比插值器

| 参数\|返回值      | 类型                   | 说明                                                                                                |
|--------------|----------------------|---------------------------------------------------------------------------------------------------|
| startValue   | number \| Percentage | 插值的起始值， 为number类型或者百分比类型                                                                          |
| endValue     | number \| Percentage | 插值的结束值， 为number类型或者百分比类型                                                                          |
| fraction     | number               | 介于0和1之间的参数表示插值的位置,包含0和1                                                                           |
| parentLength | number               | 父组件的长度或者宽度                                                                                        |
| return       | number \| Percentage | 当fraction为0时，startValue；当fraction为1时，结果为endValue；当fraction介于0和1之间时，结果是startValue和stopValue之间的某个值。 |

##### lerpColor 颜色插值器

| 参数\|返回值    | 类型     | 说明                                                                                           |
|------------|--------|----------------------------------------------------------------------------------------------|
| colorStart | number | 插值的起始颜色值                                                                                     |
| colorEnd   | number | 插值的结束颜色值                                                                                     |
| fraction   | number | 介于0和1之间的参数表示插值的位置,包含0和1                                                                      |
| return     | number | 当fraction为0时，结果为colorStart；当fraction为1时，结果为colorEnd；当fraction介于0和1之间时，结果是start和stop之间的某个颜色值。 |

##### lerpColorAlpha ARGB颜色的alpha通道插值器

| 参数\|返回值  | 类型     | 说明                                                                                                                                        |
|----------|--------|-------------------------------------------------------------------------------------------------------------------------------------------|
| color    | number | 插值的起始颜色值                                                                                                                                  |
| alpha    | number | color颜色结束的alpha值                                                                                                                          |
| fraction | number | 介于0和1之间的参数表示插值的位置,包含0和1                                                                                                                   |
| return   | number | 当fraction为0时，结果为color，当fraction为1时，结果为color的RGB颜色+参数的alpha的得到的ARGB颜色值；当fraction介于0和1之间时，结果为color的RGB颜色+color的alpha到alpha直接的某个值得到的ARGB颜色值。 |

#### 示例代码&仓库地址

https://gitee.com/jackiehou/collapsing-toolbar

#### 开源协议

本项目基于 [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html) ，请自由的享受和参与开源。