js-apis-mediaquery.md 4.7 KB
Newer Older
Z
zengyawen 已提交
1 2
# Media Query

W
wusongqing 已提交
3 4
> **NOTE**
>
Z
zengyawen 已提交
5 6 7 8 9
> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.


## Modules to Import

W
wusongqing 已提交
10
```js
Z
zengyawen 已提交
11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
import mediaquery from '@ohos.mediaquery'
```


## Required Permissions

None.


## mediaquery.matchMediaSync

matchMediaSync(condition: string): MediaQueryListener

Sets the media query criteria and returns the corresponding listening handle.

W
wusongqing 已提交
26 27
**System capability**: SystemCapability.ArkUI.ArkUI.Full

W
wusongqing 已提交
28
**Parameters**
W
wusongqing 已提交
29 30 31
| Name      | Type    | Mandatory  | Description                                      |
| --------- | ------ | ---- | ---------------------------------------- |
| 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).|
Z
zengyawen 已提交
32

W
wusongqing 已提交
33 34 35
**Return value**
| Type                | Description                    |
| ------------------ | ---------------------- |
W
wusongqing 已提交
36
| MediaQueryListener | Listening handle to a media event, which is used to register or deregister the listening callback.|
Z
zengyawen 已提交
37

W
wusongqing 已提交
38 39 40
**Example**
  ```js
listener = mediaquery.matchMediaSync('(orientation: landscape)'); // Listen for landscape events.
Z
zengyawen 已提交
41 42 43 44 45 46 47
  ```


## MediaQueryListener

Media query handle, including the first query result when the handle is applied for.

W
wusongqing 已提交
48
**System capability**: SystemCapability.ArkUI.ArkUI.Full
Z
zengyawen 已提交
49 50 51

### Attributes

W
wusongqing 已提交
52 53 54 55
| Name     | Type   | Readable  | Writable  | Description        |
| ------- | ------- | ---- | ---- | ---------- |
| matches | boolean | Yes   | No   | Whether the match condition is met. |
| media   | string  | Yes   | No   | Matching condition of a media event.|
Z
zengyawen 已提交
56 57 58 59 60 61 62 63


### on

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

Registers a callback with the corresponding query condition by using the handle. This callback is triggered when the media attributes change.

W
wusongqing 已提交
64 65
**System capability**: SystemCapability.ArkUI.ArkUI.Full

W
wusongqing 已提交
66 67 68 69 70
**Parameters**
| Name     | Type                              | Mandatory  | Description              |
| -------- | -------------------------------- | ---- | ---------------- |
| type     | string                           | Yes   | Must enter the string **change**.|
| callback | Callback<MediaQueryResult> | Yes   | Callback registered with media query.      |
Z
zengyawen 已提交
71

W
wusongqing 已提交
72
**Example**
Z
zengyawen 已提交
73 74 75 76 77 78 79
  For details, see [off Example](#off).


### off

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

W
wusongqing 已提交
80 81 82 83
Deregisters a callback with the corresponding query condition by using the handle, so that no callback is triggered when the media attributes change.

**System capability**: SystemCapability.ArkUI.ArkUI.Full

W
wusongqing 已提交
84 85 86 87
**Parameters**
| Name     | Type                              | Mandatory  | Description                           |
| -------- | -------------------------------- | ---- | ----------------------------- |
| type     | boolean                          | Yes   | Must enter the string **change**.             |
W
wusongqing 已提交
88
| callback | Callback<MediaQueryResult> | No   | Callback to be deregistered. If the default value is used, all callbacks of the handle are deregistered.|
W
wusongqing 已提交
89 90 91

**Example**
  ```js
Z
zengyawen 已提交
92 93 94 95 96 97 98 99 100 101
    import mediaquery from '@ohos.mediaquery'
    
    listener = mediaquery.matchMediaSync('(orientation: landscape)'); // Listen for landscape events.
    function onPortrait(mediaQueryResult) {
        if (mediaQueryResult.matches) {
            // do something here
        } else {
            // do something here
        }
    }
W
wusongqing 已提交
102
    listener.on('change', onPortrait) // Register a callback.
W
wusongqing 已提交
103
    listener.off('change', onPortrait) // Deregister a callback.
Z
zengyawen 已提交
104 105 106 107 108 109 110 111
  ```


## MediaQueryResult


### Attributes

W
wusongqing 已提交
112 113 114 115
| Name     | Type   | Readable  | Writable  | Description        |
| ------- | ------- | ---- | ---- | ---------- |
| matches | boolean | Yes   | No   | Whether the match condition is met. |
| media   | string  | Yes   | No   | Matching condition of a media event.|
Z
zengyawen 已提交
116 117 118 119


### Example

W
wusongqing 已提交
120
```js
Z
zengyawen 已提交
121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154
import mediaquery from '@ohos.mediaquery'

let portraitFunc = null

@Entry
@Component
struct MediaQueryExample {
  @State color: string = '#DB7093'
  @State text: string = 'Portrait'
  listener = mediaquery.matchMediaSync('(orientation: landscape)')

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

  aboutToAppear() {
    portraitFunc = this.onPortrait.bind(this) //bind current js instance
    this.listener.on('change', portraitFunc)
  }

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