前言

折叠屏设备是HarmonyOS的重要特色，屏幕状态变化时需要动态调整UI布局。@pura/harmony-utils 的 DisplayUtil 封装了屏幕变化监听方法，帮助开发者实时感知屏幕状态变化，实现折叠屏适配。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、DisplayUtil监听核心API

DisplayUtil 提供了以下屏幕变化监听方法：

方法	说明	参数	使用场景
onDisplayChange(callback)	监听屏幕变化	() => void	折叠屏适配
offDisplayChange(callback)	取消屏幕变化监听	() => void	释放资源
isFoldable()	判断是否折叠屏设备	无	设备类型判断
getFoldStatus()	获取折叠状态	无	布局切换

1.1 核心特性

• 实时感知：屏幕变化时立即触发回调
• 折叠屏支持：专门支持折叠屏状态检测
• 回调机制：基于回调函数的事件驱动模式
• 生命周期安全：支持注册和取消，避免内存泄漏

1.2 折叠屏状态对照

折叠状态	说明	布局建议
展开	大屏模式	多列布局、详情+列表
折叠	小屏模式	单列布局、简洁展示
半折叠	桌面模式	特殊适配

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 监听屏幕变化

import { DisplayUtil } from '@pura/harmony-utils';

private displayCallback = () => {
  let width = DisplayUtil.getWidth();
  let height = DisplayUtil.getHeight();
  this.result = `屏幕变化: ${width}x${height}`;
};

aboutToAppear() {
  DisplayUtil.onDisplayChange(this.displayCallback);
}

aboutToDisappear() {
  DisplayUtil.offDisplayChange(this.displayCallback);
}

2.3 折叠屏检测

Button('检测折叠屏')
  .width('100%')
  .onClick(() => {
    try {
      let foldable = DisplayUtil.isFoldable();
      this.result = `折叠屏: ${foldable ? '是 📱➡️📺' : '否'}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { DisplayUtil } from '@pura/harmony-utils';

@Entry
@Component
struct DisplayListenerDemo {
  @State result: string = '';
  private displayCallback = () => {
    let width = DisplayUtil.getWidth();
    this.result = `屏幕变化: 宽度${width}vp`;
  };

  aboutToAppear() {
    DisplayUtil.onDisplayChange(this.displayCallback);
  }
  aboutToDisappear() {
    DisplayUtil.offDisplayChange(this.displayCallback);
  }

  build() {
    Column({ space: 12 }) {
      Button('检测折叠屏').width('100%').onClick(() => {
        try {
          let foldable = DisplayUtil.isFoldable();
          let width = DisplayUtil.getWidth();
          this.result = `折叠屏: ${foldable}\n宽度: ${width}vp`;
        } catch (e) { this.result = '异常: ' + e; }
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 折叠屏自适应布局

import { DisplayUtil } from '@pura/harmony-utils';

@State columns: number = 1;

aboutToAppear() {
  this.updateLayout();
  DisplayUtil.onDisplayChange(() => this.updateLayout());
}

updateLayout() {
  let width = DisplayUtil.getWidth();
  this.columns = width >= 600 ? 2 : 1;
}

4.2 折叠状态日志记录

import { DisplayUtil, LogUtil } from '@pura/harmony-utils';

DisplayUtil.onDisplayChange(() => {
  let status = DisplayUtil.getFoldStatus();
  LogUtil.info(`折叠状态变化: ${status}`);
});

五、注意事项

1. 回调引用：注册和取消监听需使用同一回调引用
2. 生命周期：页面销毁时务必取消监听
3. 性能：屏幕变化回调中避免耗时操作
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 多次触发：折叠/展开过程中可能多次触发回调

六、常见问题

Q1: 非折叠屏设备需要监听屏幕变化吗？

建议也监听，因为屏幕旋转等场景也会触发变化。

Q2: getFoldStatus()在非折叠屏设备上返回什么？

返回无效状态，建议先通过 isFoldable() 判断是否折叠屏。

Q3: 回调中可以直接更新UI吗？

可以，回调在主线程执行，可以直接更新状态变量。

Q4: 折叠过程中回调触发几次？

可能触发多次，建议在回调中使用防抖处理避免频繁更新。

总结

DisplayUtil 的屏幕变化监听方法为折叠屏适配提供了实时感知能力。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以根据屏幕状态动态调整布局，确保应用在折叠和展开状态下都有良好的用户体验。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。