一、应用概述与功能

1.1 应用简介

本案例（index67）是一个基于 HarmonyOS NEXT 平台开发的屏幕手电应用，完整展示了 ArkUI 中 window 模块的窗口亮度控制 API 使用方法。应用通过将屏幕亮度调至最高并全屏显示白光，实现了简易的手电功能，同时支持一键关闭恢复原始亮度。

1.2 核心功能点

1. 窗口亮度控制：使用 window.setWindowBrightness 动态调整屏幕亮度
2. 全屏白光：开启时显示纯白色背景模拟手电效果
3. 状态切换：通过 Toggle 控制手电的开关状态
4. 资源恢复：页面退出时自动恢复原始亮度
5. 点击关闭：点击屏幕任意位置快速关闭手电

1.3 技术亮点

应用使用 window.getLastWindow 获取当前窗口实例，调用 setWindowBrightness 设置亮度值（0.0-1.0）。开启时亮度设为 1.0（最高）+ 白色背景，关闭时恢复 0.6 + 灰色背景。页面通过 Stack 堆叠实现开关两种状态的无缝切换。

二、核心知识点

2.1 window 模块

window 模块基于 @kit.ArkUI 提供，核心 API：

• window.getLastWindow(context)：获取当前窗口
• window.setWindowBrightness(value)：设置窗口亮度（0.0-1.0）

2.2 亮度控制原理

setWindowBrightness 直接控制系统屏幕亮度，绕过系统自动亮度调节。页面退出时必须恢复，否则会影响用户正常使用。

2.3 条件渲染

使用 if (this.on) 条件渲染实现开关状态的 UI 切换，开启时显示全屏白光，关闭时显示操作界面。

三、源码逐段解析

3.1 状态变量

@State on 控制手电开关状态，初始为 false。

3.2 setBrightness 方法

通过 window.getLastWindow 获取窗口实例，异步调用 setWindowBrightness 设置亮度。包裹 try-catch 防止异常。

3.3 toggle 方法

更新 on 状态，开启时设置亮度为 1.0 并提示"手电已开启"，关闭时恢复亮度为 0.6。

3.4 aboutToDisappear

页面退出时自动恢复亮度到 0.6，确保不会遗留高亮度设置。

3.5 UI 结构

Stack 根容器，背景色随开关切换。开启状态显示白色全屏 + 大太阳图标 + 关闭提示；关闭状态显示操作界面。

四、UI 布局与交互设计

4.1 关闭状态界面

顶部标题栏 + 大号手电图标（72vp）+ 说明文字 + 开启按钮（200×50vp，橙色）+ 底部提示文字。

4.2 开启状态界面

全屏白色背景 + 居中大号太阳图标（96vp）+ "手电筒开启中"文字。点击屏幕任意位置关闭。

4.3 视觉对比

关闭状态使用浅灰色背景 #f2f3f5，开启状态使用纯白色 #ffffff，形成强烈的视觉对比。

五、状态管理与数据流

5.1 亮度状态

on 状态变量驱动 UI 显示和亮度设置，两者通过 toggle 方法同步更新。

5.2 生命周期保障

aboutToDisappear 确保即使异常退出也能恢复亮度，保证用户体验。

六、性能优化策略

6.1 条件渲染

开启状态下只渲染最少的 UI 元素（图标+文字），避免不必要的渲染开销。

6.2 亮度优化

设置亮度为 1.0 时屏幕功耗较高，应提供快速关闭的交互路径。

七、完整代码实现

import window from '@kit.ArkUI';

@Entry
@Component
struct Index67 {
  @State on: boolean = false;

  private setBrightness(v: number): void {
    try {
      window.getLastWindow(getContext(this)).then((win: window.Window) => {
        win.setWindowBrightness(v);
      });
    } catch (err) {
    }
  }

  private toggle(val: boolean): void {
    this.on = val;
    if (val) {
      this.setBrightness(1.0);
      promptAction.showToast({ message: '手电已开启' });
    } else {
      this.setBrightness(0.6);
      promptAction.showToast({ message: '手电已关闭' });
    }
  }

  aboutToDisappear(): void {
    this.setBrightness(0.6);
  }

  build() {
    Stack() {
      Column().width('100%').height('100%')
        .backgroundColor(this.on ? '#ffffff' : '#f2f3f5')

      if (this.on) {
        Column({ space: 12 }) {
          Text('☀️').fontSize(96)
          Text('手电筒开启中').fontSize(18).fontWeight(FontWeight.Bold).fontColor('#444444')
        }
        .width('100%').height('100%')
        .justifyContent(FlexAlign.Center)
        .onClick(() => { this.toggle(false); })
      } else {
        Column() {
          Row() {
            Button('返回').backgroundColor('#1a6cff').fontColor(Color.White)
              .onClick(() => { router.back(); })
            Text('屏幕手电').fontSize(18).fontWeight(FontWeight.Bold)
            Blank()
          }
          .width('100%').padding({ left: 12, right: 12, top: 10, bottom: 10 })

          Column({ space: 14 }) {
            Text('🔦').fontSize(72)
            Text('点击下方按钮开启全屏白光手电').fontSize(15).fontColor('#666666')
            Button('开启手电').width(200).height(50).backgroundColor('#ff8f1f').fontColor(Color.White).fontSize(18)
              .onClick(() => { this.toggle(true); })
            Text('开启后屏幕亮度将调至最高，点击屏幕任意位置关闭')
              .fontSize(12).fontColor('#999999').margin({ top: 10 })
          }
          .width('100%').layoutWeight(1).justifyContent(FlexAlign.Center)
        }
        .width('100%').height('100%')
      }
    }
    .width('100%').height('100%')
  }
}

八、测试与调试

8.1 功能测试要点

1. 验证开启手电时亮度是否调至最高
2. 测试点击关闭的响应速度
3. 检查页面退出时亮度恢复
4. 验证模拟器与真机的差异

8.2 常见问题排查

1. 亮度不变化：window API 在模拟器上可能不生效，需真机测试
2. 无法获取窗口：检查上下文是否正确
3. 亮度未恢复：确认 aboutToDisappear 是否执行

九、可扩展方向

9.1 功能扩展

1. 亮度调节：支持多级亮度调节
2. 色温调节：支持屏幕色温调整
3. 定时关闭：自动关闭手电功能

十、总结与经验

通过开发 index67 屏幕手电案例，我们掌握了 HarmonyOS NEXT 中 window 模块的亮度控制 API。核心要点包括：窗口实例的获取方式、setWindowBrightness 的调用、状态与亮度的联动、以及生命周期内的资源恢复。在实际项目中，使用系统级 API 时务必注意对系统设置的影响，确保在退出时恢复原始状态，尊重用户的系统偏好设置。