harmony 鸿蒙@ohos.mediaquery (Media Query)

2025-06-12
浏览 (4)

@ohos.mediaquery (Media Query)

The mediaquery module provides different styles for different media types.

NOTE

The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.

This module cannot be used in the file declaration of the UIAbility. In other words, the APIs of this module can be used only after a component instance is created; they cannot be called in the lifecycle of the UIAbility.

The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where the UI context is unclear. For details, see UIContext.

Modules to Import

import { mediaquery } from '@kit.ArkUI';

mediaquery.matchMediaSync^(deprecated)

matchMediaSync(condition: string): MediaQueryListener

Sets the media query condition. This API returns the corresponding media query listener.

NOTE

This API is deprecated since API version 18. You are advised to use matchMediaSync instead on the obtained MediaQuery object.

Since API version 10, you can use the getMediaQuery API in UIContext to obtain the MediaQuery object associated with the current UI context.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
condition	string	Yes	Media query condition. For details, see Syntax.

Return value

Type	Description
MediaQueryListener	Media query listener, which is used to register or deregister the listening callback.

Example

import { mediaquery } from '@kit.ArkUI';

let listener: mediaquery.MediaQueryListener = mediaquery.matchMediaSync('(orientation: landscape)'); // Listen for landscape events.

MediaQueryListener

Implements the media query listener, including the first query result when the listener is applied for. The specified media query condition, for example, ’(width <= 600vp)’, is compared system information. If related information is not initialized during the first query, matches returns false.

Inherits from MediaQueryResult.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

on(‘change’)

on(type: ‘change’, callback: Callback<MediaQueryResult>): void

Registers a media query listener. The callback is triggered when the media attributes change.

NOTE

The on or off function cannot be called in the registered callback.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Listener type. The value is fixed at ‘change’.
callback	Callback<MediaQueryResult>	Yes	Callback registered with media query.

Example

See the example of off.

off(‘change’)

off(type: ‘change’, callback?: Callback<MediaQueryResult>): void

Deregisters a media query listener, so that no callback is triggered when the media attributes change.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Listener type. The value is fixed at ‘change’.
callback	Callback<MediaQueryResult>	No	Callback to be deregistered. If the default value is used, all callbacks of the handle are deregistered.

Example

import { mediaquery } from '@kit.ArkUI';

let listener = mediaquery.matchMediaSync('(orientation: landscape)'); // Listen for landscape events.
function onPortrait(mediaQueryResult:mediaquery.MediaQueryResult) {
  if (mediaQueryResult.matches) {
    // do something here
  } else {
    // do something here
  }
}
listener.on('change', onPortrait) // Register the media query listener.
listener.off('change', onPortrait) // Deregister the listener.

MediaQueryResult

Provides the media query result.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Properties

Name	Type	Readable	Writable	Description
matches	boolean	Yes	No	Whether the media query condition is met. The value true means that the query conditions are met, and false means the opposite.
media	string	Yes	No	Media query condition.

Example

NOTE

You are advised to use the getMediaQuery API in UIContext to obtain the MediaQuery object associated with the current UI context.

import { mediaquery } from '@kit.ArkUI';

@Entry
@Component
struct MediaQueryExample {
  @State color: string = '#DB7093'
  @State text: string = 'Portrait'
  listener = mediaquery.matchMediaSync('(orientation: landscape)') // You are advised to use this.getUIContext().getMediaQuery().matchMediaSync().

  onPortrait(mediaQueryResult:mediaquery.MediaQueryResult) {
    if (mediaQueryResult.matches) {
      this.color = '#FFD700'
      this.text = 'Landscape'
    } else {
      this.color = '#DB7093'
      this.text = 'Portrait'
    }
  }

  aboutToAppear() {
    let portraitFunc = (mediaQueryResult: mediaquery.MediaQueryResult): void => this.onPortrait(mediaQueryResult)
    // Register the callback.
    this.listener.on('change', portraitFunc);
  }

  aboutToDisappear() {
    // Unregister the callback.
    this.listener.off('change');
  }

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Text(this.text).fontSize(24).fontColor(this.color)
    }
    .width('100%').height('100%')
  }
}