目录

Controlling Brightness and Always-On (ArkTS)

When to Use

Brightness control is used to adjust the display brightness of an app window or device screen. You can dynamically adjust brightness based on page content characteristics, usage scenarios, and display requirements to improve page readability and content legibility. Brightness mainly includes window brightness and display brightness.

Always-on control is used to determine whether the screen remains lit for a period of time. It is suitable for scenarios that require continuous content display or long-term interactive visibility, preventing the system's automatic screen-off from affecting business processes.

Window Brightness and Display Brightness

Controlling Screen Always-On

Controlling screen always-on refers to calling the setWindowKeepScreenOn() API to set whether the device screen remains always-on when the current window is in the foreground. When a window set to always-on exists in the foreground, the device's automatic screen-off timeout capability will be disabled. This does not take effect on heterogenous virtual screens.

It is recommended to use this in scenarios where it is clear and necessary to keep the screen always-on, such as navigation, video playback, drawing, and gaming. In scenarios without screen interaction, pure audio playback, or other situations where the screen does not need to stay on continuously, setting screen always-on is not recommended.

When the window moves to the background, the system automatically releases the always-on lock held by that window. For video playback apps, when the audio or video stream is interrupted for a period of time, such as during pausing or network buffering, the system will also automatically release the always-on lock.

Keeping the screen always-on for extended periods in such scenarios may increase device power consumption and affect battery life. It is recommended to reasonably control the always-on duration based on the service requirements to ensure user experience.

The sample code is as follows:

import { window } from '@kit.ArkUI';
import { common } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const DOMAIN = 0x0000;

@Entry
@Component
struct Index {
  @State brightnessValue: number = 0.5;
  @State keepScreenOn: boolean = false;
  @State statusText: string = 'Adjust window brightness or keep-screen-on.';

  private currentWindow?: window.Window = undefined;

  aboutToAppear(): void {
    void this.initWindow();
  }

  // Get the current app window, and then set the window brightness and always‑on state through the Window object.
  private async initWindow(): Promise<void> {
    try {
      const hostContext = this.getUIContext().getHostContext();
      if (!hostContext) {
        throw new Error('Host context is unavailable.');
      }

      const context = hostContext as common.UIAbilityContext;
      this.currentWindow = await window.getLastWindow(context);

      const windowId = this.currentWindow.getWindowProperties().id;
      this.statusText = `window ready, id=${windowId}`;
      hilog.info(DOMAIN, 'windowBrightness', this.statusText);
    } catch (err) {
      this.statusText = `initWindow failed: ${JSON.stringify(err)}`;
      hilog.error(DOMAIN, 'windowBrightness', this.statusText);
    }
  }

  // Ensure the window object is initialized before calling the API.
  private async ensureWindow(): Promise<boolean> {
    if (!this.currentWindow) {
      await this.initWindow();
    }

    if (!this.currentWindow) {
      this.statusText = 'current window is unavailable.';
      return false;
    }

    return true;
  }

  // Set the current window brightness. The value ranges from 0 to 1. Passing -1 restores the system display brightness.
  private async applyBrightness(): Promise<void> {
    if (!await this.ensureWindow()) {
      return;
    }

    try {
      await this.currentWindow!.setWindowBrightness(this.brightnessValue);
      this.statusText = `setWindowBrightness(${this.brightnessValue.toFixed(2)}) success`;
      hilog.info(DOMAIN, 'windowBrightness', this.statusText);
    } catch (err) {
      this.statusText = `setWindowBrightness failed: ${JSON.stringify(err)}`;
      hilog.error(DOMAIN, 'windowBrightness', this.statusText);
    }
  }

  // Set whether to keep the screen on when the current window is in the foreground.
  private async applyKeepScreenOn(value: boolean): Promise<void> {
    if (!await this.ensureWindow()) {
      return;
    }

    try {
      this.keepScreenOn = value;
      await this.currentWindow!.setWindowKeepScreenOn(value);
      this.statusText = `setWindowKeepScreenOn(${value}) success`;
      hilog.info(DOMAIN, 'windowBrightness', this.statusText);
    } catch (err) {
      this.statusText = `setWindowKeepScreenOn failed: ${JSON.stringify(err)}`;
      hilog.error(DOMAIN, 'windowBrightness', this.statusText);
    }
  }

  build() {
    Column({ space: 16 }) {
      Text('Brightness and Keep Screen On')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .width('100%')
        .textAlign(TextAlign.Start)

      Text(`Brightness: ${this.brightnessValue.toFixed(2)}`)
        .width('100%')
        .fontSize(16)
        .textAlign(TextAlign.Start)

      Slider({
        value: this.brightnessValue,
        min: 0,
        max: 1,
        step: 0.01
      })
        .width('100%')
        .showTips(true)
        .onChange((value: number) => {
          this.brightnessValue = value;
        })

      Button('Apply Brightness')
        .width('100%')
        .onClick(() => {
          void this.applyBrightness();
        })

      Row() {
        Text(`Keep screen on: ${this.keepScreenOn}`)
          .layoutWeight(1)
          .fontSize(16)

        Toggle({ type: ToggleType.Switch, isOn: this.keepScreenOn })
          .onChange((value: boolean) => {
            void this.applyKeepScreenOn(value);
          })
      }
      .width('100%')

      Text(this.statusText)
        .width('100%')
        .fontSize(14)
        .textAlign(TextAlign.Start)
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .alignItems(HorizontalAlign.Start)
  }
}