MediaQuery (@ohos.mediaquery)

Overview

Media queries are at the core of responsive design and widely used on mobile devices. You can use media queries to apply application styles based on the device type or device state. Specifically, media queries allow you to:

1. Design a layout style based on the device and application attributes (such as display area, dark light color, and resolution).

2. Update the page layout to adapt to dynamic screen changes (for example, screen splitting or switching between landscape and portrait modes).

Usage

Invoke the API in the mediaquery module to set the media query condition and the callback, and change the page layout or implement service logic in the callback corresponding to the condition. The procedure is as follows:

Import the mediaquery module, as shown below:

import mediaquery from '@ohos.mediaquery';

Use the matchMediaSync API to set the media query condition and save the returned listener. The following is the example for listening for landscape events:

let listener: mediaquery.MediaQueryListener = mediaquery.matchMediaSync('(orientation: landscape)');

Register the onPortrait callback using the saved listener, and change the page layout or implement service logic in the callback. When the media query condition is matched, the callback is triggered. The sample code is as follows:

onPortrait(mediaQueryResult: mediaquery.MediaQueryResult) {
  if (mediaQueryResult.matches as boolean) {
    // do something here
  } else {
    // do something here
  }
}

listener.on('change', onPortrait);

Media Query Conditions

The media query condition consists of the media type (optional), logical operator, and media feature. The logical operator is used to connect different media types and media features. A media feature must be enclosed in parentheses (). There may be multiple media features.

Syntax

Syntax rules include media-type, media-logic-operations, and media-feature.

[media-type] [media-logic-operations] [(media-feature)]

Examples are as follows:

• screen and (round-screen: true): The query is valid when the device screen is round.

• (max-height: 800px): The query is valid when the height is less than or equal to 800 px.

• (height <= 800px): The query is valid when the height is less than or equal to 800 px. (The logical operators are recommended when the media features are uncertain.)

• screen and (device-type: tv) or (resolution < 2): The query is valid when the device type is TV or the device resolution is less than 2. This is a multi-condition query that contains multiple media features.

media-type

media-logic-operations

You can use logical operators (and, or, not, and only) to compose complex media queries. You can also combine them using comma (,). The following table describes the operators.

Table 1 Media logical operators

Media range operators include <=, >=, <, and >. For details, see the following table.

Table 2 Logical operators for range query

media-feature

The media features include the width and height of the application display area, device resolution, and device width and height. For details, see the following table.

Table 3 Media features

Example Scenario

In the following examples, media queries are used to apply different content and styles to the page text when the screen is switched between landscape and portrait modes.

Stage model:

import mediaquery from '@ohos.mediaquery';
import window from '@ohos.window';
import common from '@ohos.app.ability.common';

@Entry
@Component
struct MediaQueryExample {
  @State color: string = '#DB7093';
  @State text: string = 'Portrait';
  @State portraitFunc:mediaquery.MediaQueryResult|void|null = null;
  // The query is valid when the device is in landscape mode.
  listener:mediaquery.MediaQueryListener = mediaquery.matchMediaSync('(orientation: landscape)');

  // The callback is triggered when the query is valid.
  onPortrait(mediaQueryResult:mediaquery.MediaQueryResult) {
    if (mediaQueryResult.matches as boolean) {// If the device is in landscape mode, the page layout is changed accordingly.
      this.color = '#FFD700';
      this.text = 'Landscape';
    } else {
      this.color = '#DB7093';
      this.text = 'Portrait';
    }
  }

  aboutToAppear() {
    // Bind to the current application instance.
    // Register the callback.
    this.listener.on('change', (mediaQueryResult:mediaquery.MediaQueryResult) => { this.onPortrait(mediaQueryResult) });
  }

  // Change the landscape/portrait mode of the device in the callback.
  private changeOrientation(isLandscape: boolean) {
    // Obtain the context information of the UIAbility instance.
    let context:common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
    // Invoke this API to manually change the landscape/portrait mode of the device.
    window.getLastWindow(context).then((lastWindow) => {
      lastWindow.setPreferredOrientation(isLandscape ? window.Orientation.LANDSCAPE : window.Orientation.PORTRAIT)
    });
  }

  build() {
    Column({ space: 50 }) {
      Text(this.text).fontSize(50).fontColor(this.color)
      Text('Landscape').fontSize(50).fontColor(this.color).backgroundColor(Color.Orange)
        .onClick(() => {
          this.changeOrientation(true);
        })
      Text('Portrait').fontSize(50).fontColor(this.color).backgroundColor(Color.Orange)
        .onClick(() => {
          this.changeOrientation(false);
        })
    }
    .width('100%').height('100%')
  }
}

FA model:

import mediaquery from '@ohos.mediaquery';
import featureAbility from '@ohos.ability.featureAbility';

@Entry
@Component
struct MediaQueryExample {
  @State color: string = '#DB7093';
  @State text: string = 'Portrait';
  @State portraitFunc:mediaquery.MediaQueryResult|void|null = null;
  listener:mediaquery.MediaQueryListener = mediaquery.matchMediaSync('(orientation: landscape)'); // The query is valid when the device is in landscape mode.

  onPortrait(mediaQueryResult:mediaquery.MediaQueryResult) { // The callback is triggered when the query is valid.
    if (mediaQueryResult.matches as boolean) {// If the device is in landscape mode, the page layout is changed accordingly.
      this.color = '#FFD700';
      this.text = 'Landscape';
    } else {
      this.color = '#DB7093';
      this.text = 'Portrait';
    }
  }

  aboutToAppear() {
    // Bind to the current application instance.
    this.listener.on('change', (mediaQueryResult:mediaquery.MediaQueryResult) => { this.onPortrait(mediaQueryResult) }); // Register the callback.
  }

  build() {
    Column({ space: 50 }) {
      Text(this.text).fontSize(50).fontColor(this.color)
      Text('Landscape').fontSize(50).fontColor(this.color).backgroundColor(Color.Orange)
        .onClick(() => {
          let context = featureAbility.getContext();
          context.setDisplayOrientation(0); // Invoke this API to manually change the landscape/portrait mode of the device.
        })
      Text('Portrait').fontSize(50).fontColor(this.color).backgroundColor(Color.Orange)
        .onClick(() => {
          let context = featureAbility.getContext();
          context.setDisplayOrientation(1); // Invoke this API to manually change the landscape/portrait mode of the device.
        })
    }
    .width('100%').height('100%')
  }
}

Figure 1 Portrait mode

Figure 2 Landscape mode