• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Media Query
2
3> **NOTE**
4>
5> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
6
7
8## Modules to Import
9
10```js
11import mediaquery from '@ohos.mediaquery'
12```
13
14
15## Required Permissions
16
17None.
18
19
20## mediaquery.matchMediaSync
21
22matchMediaSync(condition: string): MediaQueryListener
23
24Sets the media query criteria and returns the corresponding listening handle.
25
26**System capability**: SystemCapability.ArkUI.ArkUI.Full
27
28**Parameters**
29
30| Name      | Type    | Mandatory  | Description                                      |
31| --------- | ------ | ---- | ---------------------------------------- |
32| condition | string | Yes   | Matching condition of a media event. For details, see [Syntax of Media Query Conditions](../../ui/ui-ts-layout-mediaquery.md#syntax-of-media-query-conditions).|
33
34**Return value**
35| Type                | Description                    |
36| ------------------ | ---------------------- |
37| MediaQueryListener | Listening handle to a media event, which is used to register or deregister the listening callback.|
38
39**Example**
40  ```js
41let listener = mediaquery.matchMediaSync('(orientation: landscape)'); // Listen for landscape events.
42  ```
43
44
45## MediaQueryListener
46
47Media query handle, including the first query result when the handle is applied for.
48
49**System capability**: SystemCapability.ArkUI.ArkUI.Full
50
51### Attributes
52
53| Name     | Type   | Readable  | Writable  | Description        |
54| ------- | ------- | ---- | ---- | ---------- |
55| matches | boolean | Yes   | No   | Whether the match condition is met. |
56| media   | string  | Yes   | No   | Matching condition of a media event.|
57
58
59### on
60
61on(type: 'change', callback: Callback<MediaQueryResult>): void
62
63Registers a callback with the corresponding query condition by using the handle. This callback is triggered when the media attributes change.
64
65**System capability**: SystemCapability.ArkUI.ArkUI.Full
66
67**Parameters**
68| Name     | Type                              | Mandatory  | Description              |
69| -------- | -------------------------------- | ---- | ---------------- |
70| type     | string                           | Yes   | Must enter the string **change**.|
71| callback | Callback<MediaQueryResult> | Yes   | Callback registered with media query.      |
72
73**Example**
74  For details, see [off Example](#off).
75
76
77### off
78
79off(type: 'change', callback?: Callback<MediaQueryResult>): void
80
81Deregisters a callback with the corresponding query condition by using the handle, so that no callback is triggered when the media attributes change.
82
83**System capability**: SystemCapability.ArkUI.ArkUI.Full
84
85**Parameters**
86| Name     | Type                              | Mandatory  | Description                           |
87| -------- | -------------------------------- | ---- | ----------------------------- |
88| type     | boolean                          | Yes   | Must enter the string **change**.             |
89| callback | Callback<MediaQueryResult> | No   | Callback to be deregistered. If the default value is used, all callbacks of the handle are deregistered.|
90
91**Example**
92  ```ts
93    import mediaquery from '@ohos.mediaquery'
94
95    let listener = mediaquery.matchMediaSync('(orientation: landscape)'); // Listen for landscape events.
96    function onPortrait(mediaQueryResult) {
97        if (mediaQueryResult.matches) {
98            // do something here
99        } else {
100            // do something here
101        }
102    }
103    listener.on('change', onPortrait) // Register a callback.
104    listener.off('change', onPortrait) // Deregister a callback.
105  ```
106
107
108## MediaQueryResult
109
110
111### Attributes
112
113| Name     | Type   | Readable  | Writable  | Description        |
114| ------- | ------- | ---- | ---- | ---------- |
115| matches | boolean | Yes   | No   | Whether the match condition is met. |
116| media   | string  | Yes   | No   | Matching condition of a media event.|
117
118
119### Example
120
121```ts
122import mediaquery from '@ohos.mediaquery'
123
124
125@Entry
126@Component
127struct MediaQueryExample {
128  @State color: string = '#DB7093'
129  @State text: string = 'Portrait'
130  listener = mediaquery.matchMediaSync('(orientation: landscape)')
131
132  onPortrait(mediaQueryResult) {
133    if (mediaQueryResult.matches) {
134      this.color = '#FFD700'
135      this.text = 'Landscape'
136    } else {
137      this.color = '#DB7093'
138      this.text = 'Portrait'
139    }
140  }
141
142  aboutToAppear() {
143    let portraitFunc = this.onPortrait.bind(this) // Bind the current JS instance.
144    this.listener.on('change', portraitFunc)
145  }
146
147  build() {
148    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
149      Text(this.text).fontSize(24).fontColor(this.color)
150    }
151    .width('100%').height('100%')
152  }
153}
154```
155