鸿蒙三方库 | harmony-utils之WindowUtil屏幕亮度与常亮详解

SansanDoris

18人浏览 · 2026-07-11 23:32:56

SansanDoris · 2026-07-11 23:32:56 发布

前言

屏幕亮度控制和常亮设置在阅读、视频播放、导航等场景中非常实用。@pura/harmony-utils 的 WindowUtil 封装了亮度和常亮控制方法，开发者可以轻松实现亮度调节和屏幕常亮功能。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

在这里插入图片描述

一、WindowUtil亮度核心API

WindowUtil 提供了以下亮度和常亮控制方法：

方法	说明	参数	使用场景
`setScreenBrightness(value)`	设置屏幕亮度（0-255）	number	阅读模式、户外模式
`getScreenBrightness()`	获取当前屏幕亮度	无	亮度状态查询
`setKeepScreenOn(enabled)`	设置屏幕常亮	boolean	视频、导航、阅读

1.1 核心特性

简洁易用：封装复杂API为一行调用，降低使用门槛
类型安全：完整的TypeScript类型定义，编译期即可发现错误
异常处理：内置异常捕获机制，避免运行时崩溃
即时生效：亮度设置后立即生效

1.2 亮度值参考

亮度值	效果	适用场景
0-50	极暗	夜间阅读
50-128	中等	室内使用
128-200	较亮	正常使用
200-255	最亮	户外使用

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 设置屏幕亮度

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

Button('设置最大亮度')
  .width('100%')
  .onClick(() => {
    try {
      WindowUtil.setScreenBrightness(255);
      this.result = '亮度已设为最大 ☀️';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

Button('设置中等亮度')
  .width('100%')
  .onClick(() => {
    try {
      WindowUtil.setScreenBrightness(128);
      this.result = '亮度已设为中等 🌤️';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 屏幕常亮

Button('开启屏幕常亮')
  .width('100%')
  .onClick(() => {
    try {
      WindowUtil.setKeepScreenOn(true);
      this.result = '屏幕常亮已开启 💡\n适用于阅读和视频播放';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

Button('关闭屏幕常亮')
  .width('100%')
  .onClick(() => {
    try {
      WindowUtil.setKeepScreenOn(false);
      this.result = '屏幕常亮已关闭';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

在这里插入图片描述

三、完整页面示例

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

@Entry
@Component
struct BrightnessDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('获取当前亮度').width('100%').onClick(() => {
        try {
          let brightness = WindowUtil.getScreenBrightness();
          this.result = `当前亮度: ${brightness}/255`;
        } catch (e) { this.result = '异常: ' + e; }
      });
      Button('开启常亮').width('100%').onClick(() => {
        WindowUtil.setKeepScreenOn(true);
        this.result = '屏幕常亮已开启';
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 阅读模式亮度自动调节

import { WindowUtil, DeviceUtil } from '@pura/harmony-utils';

function enterReadingMode() {
  WindowUtil.setKeepScreenOn(true);
  let level = DeviceUtil.getBatteryLevel();
  let brightness = level > 30 ? 128 : 80;
  WindowUtil.setScreenBrightness(brightness);
}

4.2 亮度滑块控制

@State brightness: number = 128;

Slider({
  value: this.brightness,
  min: 0,
  max: 255
})
.onChange((value: number) => {
  this.brightness = value;
  WindowUtil.setScreenBrightness(value);
})