HarmonyOS 应用开发：实现个人主页界面背景下拉放大效果的完整开发

在移动应用开发中，图片下拉放大是一种常见的交互效果，能为用户带来更流畅、生动的视觉体验。本文将以 HarmonyOS 应用开发为例，基于 ArkTS 语言，详细讲解如何在列表页面中实现顶部图片的下拉放大功能，同时解析核心代码逻辑与关键技术点，帮助开发者快速掌握该效果的实现方法。

效果图

HarmonyOS 应用开发：实现个人主页界面背景下拉放大效果的完整开发

文章目录

一、效果概述与核心原理

1. 最终效果

在页面顶部放置一张背景图片，当用户向下拉动页面（触发下拉刷新动作）时，图片会随下拉偏移量同步放大；当用户向上滚动页面时，图片会保持原有尺寸或逐渐“隐藏”到顶部；松开下拉动作后，图片会恢复初始大小，整体交互自然流畅。

2. 核心原理

实现该效果主要依赖 HarmonyOS 的 Refresh 组件（下拉刷新容器）和 Scroll 组件（滚动容器），结合状态变量动态控制图片的尺寸与边距，核心逻辑可拆解为 3 步：

  1. 状态变量定义：通过 @State 装饰器定义图片高度（heightNum）、边距（marginNum）、初始高度（imageH）等变量，用于动态控制图片样式。
  2. 下拉放大逻辑：监听 Refresh 组件的 onOffsetChange 事件，获取下拉偏移量，将“初始图片高度 + 下拉偏移量”赋值给图片高度，实现下拉时图片放大。
  3. 滚动复位逻辑：监听 Scroll 组件的 onDidScroll 事件，当页面向上滚动时，重置图片边距与高度，确保图片不会因滚动出现异常拉伸。

二、完整代码解析

以下是实现图片下拉放大效果的完整代码，我们将按“组件结构→核心逻辑→关键细节”的顺序逐步解析。

1. 完整代码

import { phone_pops_up } from '../home/MakeCallDialog'

// 自定义列表数据类
class myList {
  image: string
  url: string
  text: string

  constructor(image: string, url: string, text: string) {
    this.image = image
    this.url = url
    this.text = text
  }
}

@Entry
@Component
struct RefreshExample {
  // 故障维修弹窗控制器
  repairPopUps: CustomDialogController = new CustomDialogController({
    builder: phone_pops_up(),
    cornerRadius: { topLeft: 10, topRight: 10, bottomLeft: 0, bottomRight: 0 },
    alignment: DialogAlignment.Bottom,
    width: '100%'
  })

  // 状态变量：控制下拉刷新、图片样式、列表数据
  @State isRefreshing: boolean = false // 下拉刷新状态
  @State heightNum: number = 0 // 图片当前高度
  @State marginNum: number = 0 // 图片边距（控制位置）
  @State imageH: number = 0 // 图片初始高度（从组件尺寸变化中获取）
  @State name: string = '码到成功✓' // 顶部文本
  scroller = new Scroller() // Scroll 控制器

  // 列表数据源
  private myListdata: myList[] = [
    new myList('', '', '预定电桩'), new myList('', '', '分享电桩'),
    new myList('', '', '充电记录'), new myList('', '', '数据分析'),
    new myList('', '', '故障维修'), new myList('', '', '修改密码'),
    new myList('', '', '关于我们'), new myList('', '', '设置')
  ]

  // 1. 下拉刷新区域：承载放大的背景图片
  @Builder
  freshArea() {
    Image($r("app.media.My_background")) // 顶部背景图片
      .width("100%")
      .height(this.heightNum) // 动态控制高度（核心：下拉时放大）
      .margin({ top: this.marginNum, bottom: -this.marginNum }) // 控制图片位置，避免拉伸异常
  }

  build() {
    // 2. 下拉刷新容器：包裹整个页面，触发下拉放大逻辑
    Refresh({ 
      refreshing: $$this.isRefreshing, // 双向绑定刷新状态
      builder: this.freshArea() // 下拉时显示的内容（即放大的图片）
    }) {
      // 3. 滚动容器：承载列表内容，监听滚动事件
      Scroll(this.scroller) {
        Column({ space: 10 }) {
          // 顶部区域：包含背景图片（透明占位）和头像文本
          Stack() {
            // 透明占位图片：用于获取初始高度（关键！）
            Image($r("app.media.My_background"))
              .width("100%")
              .height(150)
              .opacity(0) // 设为透明，仅用于获取尺寸
              .onSizeChange((old, newValue) => {
                // 组件渲染完成后，获取图片初始高度并赋值给状态变量
                this.imageH = Number(newValue.height)
                this.marginNum = this.imageH // 初始边距 = 初始高度
                this.heightNum = this.imageH // 初始图片高度 = 初始高度
                console.log('图片初始高度：' + this.imageH)
              })

            // 头像与文本：叠在透明图片上方，形成顶部布局
            Row({ space: 10 }) {
              Image($r("app.media.My_avatar"))
                .width(90)
                .align(Alignment.BottomEnd)
              Text(this.name)
                .fontWeight(700)
                .fontSize(20)
                .padding({ bottom: 10 })
            }
          }
          .width('100%')
          .height(200)
          .alignContent(Alignment.BottomStart)

          // 列表区域：循环渲染自定义列表项
          Column({ space: 10 }) {
            ForEach(this.myListdata, (item: myList, inedx) => {
              Row({ space: 30 }) {
                // 列表项左侧：图标 + 文本
                Row({ space: 10 }) {
                  Image($r('app.media.my' + inedx))
                    .width(25)
                  Text(item.text)
                    .fontSize(15)
                    .fontWeight(700)
                    .fontColor(Color.Black)
                }
                // 列表项右侧：箭头图标
                Image($r('app.media.homeexported_image'))
                  .height(30)
              }
              // 故障维修项点击事件：打开弹窗
              .onClick(() => {
                if (inedx === 4 && this.repairPopUps != null) {
                  this.repairPopUps.open()
                }
              })
              // 列表项底部边框
              .border({ width: { bottom: 1 }, color: "#ffe7e7e7" })
              .padding(7)
              .justifyContent(FlexAlign.SpaceBetween)
              .width('100%')
            })
          }
        }
      }
      .margin(14)
      .scrollBar(BarState.Off) // 隐藏滚动条
      // 4. Scroll 滚动事件：控制图片复位
      .onDidScroll((scrollOffset: number) => {
        console.info("当前滚动偏移量：", this.scroller.currentOffset().yOffset)
        // 当页面未向上滚动（yOffset ≤ 0）时，重置边距，避免图片位置异常
        if (this.scroller.currentOffset().yOffset <= 0) {
          this.marginNum = this.imageH
          return
        }
        // 页面向上滚动时，根据滚动高度调整图片（此处注释代码可扩展为“上滚隐藏”效果）
        let offset = this.scroller.currentOffset().yOffset > this.imageH 
          ? this.imageH 
          : this.scroller.currentOffset().yOffset
        console.info("滚动调整偏移量：" + offset)
      })
    }
    .height("100%")
    // 5. Refresh 状态变化事件：监听下拉刷新状态（可选，用于扩展刷新逻辑）
    .onStateChange((refreshStatus: RefreshStatus) => {
      console.info('下拉刷新状态：' + refreshStatus)
      // 示例：刷新完成后重置 isRefreshing
      if (refreshStatus === RefreshStatus.Refresh) {
        setTimeout(() => {
          this.isRefreshing = false
        }, 1000)
      }
    })
    // 6. Refresh 偏移量变化事件：核心！实现下拉放大
    .onOffsetChange((value: number) => {
      console.log("下拉偏移量：" + value)
      // 下拉时，图片高度 = 初始高度 + 下拉偏移量（实现放大效果）
      this.heightNum = this.imageH + value
    })
    .refreshOffset(64) // 触发下拉刷新的最小偏移量
    .pullToRefresh(false) // 关闭系统默认下拉刷新动画（避免与自定义效果冲突）
  }
}

2. 核心逻辑拆解

（1）图片初始高度获取：onSizeChange 事件

要实现“下拉放大”，首先需要知道图片的初始高度（即未下拉时的高度）。代码中通过“透明占位图片”的 onSizeChange 事件获取初始高度：

  • 占位图片设置 opacity(0)，仅用于渲染尺寸，不显示在界面上；
  • 组件渲染完成后，newValue.height 会返回图片的实际高度，将其赋值给 imageH（初始高度）、heightNum（当前高度）、marginNum（当前边距），确保初始状态下图片尺寸正确。
（2）下拉放大：onOffsetChange 事件

Refresh 组件的 onOffsetChange 事件会返回下拉偏移量（value，单位：px），这是实现放大效果的关键：

  • 当下拉时，value 为正数，且随下拉距离增大而增大；
  • 将 heightNum（图片当前高度）设为 imageH + value，即“初始高度 + 下拉偏移量”，图片会随下拉同步放大；
  • 松开下拉后，value 回归 0，heightNum 恢复为 imageH，图片回到初始尺寸。
（3）滚动复位：onDidScroll 事件

Scroll 组件的 onDidScroll 事件用于监听页面滚动，避免向上滚动时图片出现异常拉伸：

  • 当页面未向上滚动（yOffset ≤ 0）时，重置 marginNum = imageH，确保图片位置正确；
  • 若需要实现“向上滚动时图片隐藏”，可取消注释代码中的逻辑：通过滚动偏移量 offset 动态减小 heightNum 和 marginNum，让图片随上滚逐渐收缩到顶部。

（4）图片自然缩放的关键布局

.margin({ top: this.marginNum, bottom: -this.marginNum }) 是实现图片自然缩放的关键布局调整：

正负抵消：顶部正边距使图片向上偏移，底部负边距让下方列表向上靠拢，两者抵消后，图片高度变化不会挤压或留白
视觉引导：下拉放大时，图片额外高度 “向上延伸”；上滚时，随边距减小 “向上收缩”，保持与手势的一致性
动态适配：marginNum 与图片初始高度、滚动偏移联动，确保各交互阶段布局自然
在这里插入图片描述

三、关键细节与注意事项

  1. 避免图片拉伸变形
    图片需设置 width: 100%，确保宽度充满屏幕，高度通过 heightNum 动态控制，避免宽高比失衡导致拉伸。若图片为固定比例，可在 onOffsetChange 中计算高度时按比例调整，例如：

    // 假设图片宽高比为 2:1，宽度为屏幕宽度（this.screenWidth）
this.heightNum = (this.screenWidth / 2) + value

  2. 关闭系统默认刷新动画
    Refresh 组件默认有下拉刷新动画，可能与自定义图片放大效果冲突，需设置 pullToRefresh(false) 关闭默认动画，仅保留自定义的 builder 内容（即放大的图片）。

  3. 处理刷新状态
    若需要结合“下拉刷新数据”的逻辑，可在 onStateChange 事件中监听 RefreshStatus.Refresh 状态（即下拉到触发刷新的阈值时），执行数据请求，请求完成后将 isRefreshing 设为 false，结束刷新状态。

  4. 图片资源路径正确
    代码中图片资源（如 $r("app.media.My_background")）需确保在 main_pages.json 对应的模块中存在，路径错误会导致图片不显示，影响效果。

四、效果扩展：上滚图片隐藏

若需要实现“向上滚动时图片逐渐隐藏”的效果，可取消 onDidScroll 事件中的注释代码，核心逻辑如下：

.onDidScroll((scrollOffset: number) => {
  if (this.scroller.currentOffset().yOffset <= 0) {
    this.marginNum = this.imageH
    return
  }
  // 向上滚动时，计算调整后的高度
  let offset = this.scroller.currentOffset().yOffset > this.imageH 
    ? this.imageH 
    : this.scroller.currentOffset().yOffset
  // 当滚动高度超过 100px 时，图片高度固定为 100px；否则随滚动减小
  if ((this.imageH - offset) < 100) {
    this.heightNum = 100
    this.marginNum = this.heightNum
  } else {
    this.heightNum = this.imageH - offset
    this.marginNum = this.heightNum
  }
})
  • 上滚时，offset 增大，this.imageH - offset 减小，heightNum 随之减小，图片逐渐收缩；
  • 当收缩到 100px 时，固定高度，避免图片过小影响界面美观。

五、总结

本文通过 HarmonyOS 的 Refresh 和 Scroll 组件，结合状态变量动态控制图片尺寸，实现了“下拉放大、松开复位”的交互效果。核心在于：

  1. 利用 onSizeChange 获取图片初始高度；
  2. 利用 onOffsetChange 实现下拉放大；
  3. 利用 onDidScroll 处理滚动复位。

该方案逻辑清晰、代码简洁，可直接复用到底部列表、个人中心等页面，也可根据需求扩展“上滚隐藏”“比例缩放”等效果。
完整代码

完整代码：gitee 开箱即可使用

# harmonyos # 华为
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

HarmonyOS 6.1 全栈实战录 - 81 打通全联接物理层：实战 Connectivity Kit 自定义 BLE 广播与 Wi-Fi P2P 频段智选中控

avatar HarmonyOS开发者社区
cover

【HarmonyOS 6.0】Map Kit瓦片图层深度解析：本地加载方式与瓦片数据缓存能力

avatar HarmonyOS开发者社区
cover

Flutter 和 ArkTS 在一个鸿蒙项目里应该怎么分工

avatar HarmonyOS开发者社区