1# @ohos.mediaquery (Media Query)
2
3The **mediaquery** module provides different styles for different media types.
4
5> **NOTE**
6>
7> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
8>
9> This module cannot be used in the file declaration of the [UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md). 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.
10>
11> 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](js-apis-arkui-UIContext.md#uicontext).
12>
13> Since API version 10, you can use the [getMediaQuery](js-apis-arkui-UIContext.md#getmediaquery) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the [MediaQuery](js-apis-arkui-UIContext.md#mediaquery) object associated with the current UI context.
14
15
16## Modules to Import
17
18```ts
19import { mediaquery } from '@kit.ArkUI';
20```
21
22
23## mediaquery.matchMediaSync
24
25matchMediaSync(condition: string): MediaQueryListener
26
27Sets the media query condition. This API returns the corresponding media query listener.
28
29**Widget capability**: This API can be used in ArkTS widgets since API version 12.
30
31**Atomic service API**: This API can be used in atomic services since API version 11.
32
33**System capability**: SystemCapability.ArkUI.ArkUI.Full
34
35**Parameters**
36
37| Name   | Type  | Mandatory| Description                                                        |
38| --------- | ------ | ---- | ------------------------------------------------------------ |
39| condition | string | Yes  | Media query condition. For details, see [Syntax](../../ui/arkts-layout-development-media-query.md#syntax).|
40
41**Return value**
42
43| Type              | Description                                        |
44| ------------------ | -------------------------------------------- |
45| [MediaQueryListener](#mediaquerylistener) | Media query listener, which is used to register or deregister the listening callback.|
46
47**Example**
48
49```ts
50import { mediaquery } from '@kit.ArkUI';
51
52let listener:mediaquery.MediaQueryListener = mediaquery.matchMediaSync('(orientation: landscape)'); // Listen for landscape events.
53```
54
55
56## MediaQueryListener
57
58Implements 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**.
59
60Inherits from [MediaQueryResult](#mediaqueryresult).
61
62**Widget capability**: This API can be used in ArkTS widgets since API version 12.
63
64**Atomic service API**: This API can be used in atomic services since API version 11.
65
66**System capability**: SystemCapability.ArkUI.ArkUI.Full
67
68
69### on('change')
70
71on(type: 'change', callback: Callback&lt;MediaQueryResult&gt;): void
72
73Registers a media query listener. The callback is triggered when the media attributes change.
74
75> **NOTE**
76>
77> The **on** or **off** function cannot be called in the registered callback.
78
79**Widget capability**: This API can be used in ArkTS widgets since API version 12.
80
81**Atomic service API**: This API can be used in atomic services since API version 11.
82
83**System capability**: SystemCapability.ArkUI.ArkUI.Full
84
85**Parameters**
86
87| Name  | Type                                                 | Mandatory| Description                    |
88| -------- | ----------------------------------------------------- | ---- | ------------------------ |
89| type     | string                                                | Yes  | Listener type. The value is fixed at **'change'**.|
90| callback | Callback&lt;[MediaQueryResult](#mediaqueryresult)&gt; | Yes  | Callback registered with media query.    |
91
92**Example**
93
94  See the example of [off](#offchange).
95
96
97### off('change')
98
99off(type: 'change', callback?: Callback&lt;MediaQueryResult&gt;): void
100
101Deregisters a media query listener, so that no callback is triggered when the media attributes change.
102
103**Widget capability**: This API can be used in ArkTS widgets since API version 12.
104
105**Atomic service API**: This API can be used in atomic services since API version 11.
106
107**System capability**: SystemCapability.ArkUI.ArkUI.Full
108
109**Parameters**
110
111| Name  | Type                            | Mandatory| Description                                                      |
112| -------- | -------------------------------- | ---- | ---------------------------------------------------------- |
113| type     | string                           | Yes  | Listener type. The value is fixed at **'change'**.                                  |
114| callback | Callback&lt;[MediaQueryResult](#mediaqueryresult)&gt; | No  | Callback to be deregistered. If the default value is used, all callbacks of the handle are deregistered.|
115
116**Example**
117
118  ```ts
119import { mediaquery } from '@kit.ArkUI';
120
121let listener = mediaquery.matchMediaSync('(orientation: landscape)'); // Listen for landscape events.
122function onPortrait(mediaQueryResult:mediaquery.MediaQueryResult) {
123  if (mediaQueryResult.matches) {
124    // do something here
125  } else {
126    // do something here
127  }
128}
129listener.on('change', onPortrait) // Register the media query listener.
130listener.off('change', onPortrait) // Deregister the listener.
131  ```
132
133## MediaQueryResult
134
135Provides the media query result.
136
137**Widget capability**: This API can be used in ArkTS widgets since API version 12.
138
139**Atomic service API**: This API can be used in atomic services since API version 11.
140
141**System capability**: SystemCapability.ArkUI.ArkUI.Full
142
143
144### Attributes
145
146| Name   | Type   | Readable| Writable| Description                |
147| ------- | ------- | ---- | ---- | -------------------- |
148| matches | boolean | Yes  | No  | Whether the media query condition is met.  |
149| media   | string  | Yes  | No  | Media query condition.|
150
151
152### Example
153
154> **NOTE**
155>
156> You are advised to use the [getMediaQuery](js-apis-arkui-UIContext.md#getmediaquery) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the [MediaQuery](js-apis-arkui-UIContext.md#mediaquery) object associated with the current UI context.
157
158```ts
159import { mediaquery } from '@kit.ArkUI';
160
161@Entry
162@Component
163struct MediaQueryExample {
164  @State color: string = '#DB7093'
165  @State text: string = 'Portrait'
166  listener = mediaquery.matchMediaSync('(orientation: landscape)') // You are advised to use this.getUIContext().getMediaQuery().matchMediaSync().
167
168  onPortrait(mediaQueryResult:mediaquery.MediaQueryResult) {
169    if (mediaQueryResult.matches) {
170      this.color = '#FFD700'
171      this.text = 'Landscape'
172    } else {
173      this.color = '#DB7093'
174      this.text = 'Portrait'
175    }
176  }
177
178  aboutToAppear() {
179    let portraitFunc = (mediaQueryResult: mediaquery.MediaQueryResult): void => this.onPortrait(mediaQueryResult)
180    // Register the callback.
181    this.listener.on('change', portraitFunc);
182  }
183
184  aboutToDisappear() {
185    // Unregister the callback.
186    this.listener.off('change');
187  }
188
189  build() {
190    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
191      Text(this.text).fontSize(24).fontColor(this.color)
192    }
193    .width('100%').height('100%')
194  }
195}
196```
197