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