1# @ohos.mediaquery (媒体查询)
2
3提供根据不同媒体类型定义不同的样式。
4
5> **说明：**
6>
7> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
8>
9> 该模块不支持在[UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md)的文件声明处使用，即不能在UIAbility的生命周期中调用，需要在创建组件实例后使用。
10>
11> 本模块功能依赖UI的执行上下文，不可在UI上下文不明确的地方使用，参见[UIContext](js-apis-arkui-UIContext.md#uicontext)说明。
12>
13> 从API version 10开始，可以通过使用[UIContext](js-apis-arkui-UIContext.md#uicontext)中的[getMediaQuery](js-apis-arkui-UIContext.md#getmediaquery)方法获取当前UI上下文关联的[MediaQuery](js-apis-arkui-UIContext.md#mediaquery)对象。
14
15
16## 导入模块
17
18```ts
19import { mediaquery } from '@kit.ArkUI';
20```
21
22
23## mediaquery.matchMediaSync
24
25matchMediaSync(condition: string): MediaQueryListener
26
27设置媒体查询的查询条件，并返回对应的监听句柄。
28
29**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
30
31**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
32
33**系统能力：** SystemCapability.ArkUI.ArkUI.Full
34
35**参数：**
36
37| 参数名    | 类型   | 必填 | 说明                                                         |
38| --------- | ------ | ---- | ------------------------------------------------------------ |
39| condition | string | 是   | 媒体事件的匹配条件，具体可参考[媒体查询语法规则](../../ui/arkts-layout-development-media-query.md#语法规则)。 |
40
41**返回值：**
42
43| 类型               | 说明                                         |
44| ------------------ | -------------------------------------------- |
45| [MediaQueryListener](#mediaquerylistener) | 媒体事件监听句柄，用于注册和去注册监听回调。 |
46
47**示例：**
48
49```ts
50import { mediaquery } from '@kit.ArkUI';
51
52let listener:mediaquery.MediaQueryListener = this.getUIContext().getMediaQuery().matchMediaSync('(orientation: landscape)'); //监听横屏事件
53```
54
55
56## MediaQueryListener
57
58媒体查询的句柄，并包含了申请句柄时的首次查询结果。媒体查询根据设置的条件语句，比如'(width <= 600vp)'，比较系统信息，若首次查询时相关信息未初始化，matches返回false。
59
60继承自[MediaQueryResult](#mediaqueryresult)。
61
62**卡片能力：** 从API version 12开始，该类型支持在ArkTS卡片中使用。
63
64**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
65
66**系统能力：** SystemCapability.ArkUI.ArkUI.Full
67
68
69### on('change')
70
71on(type: 'change', callback: Callback&lt;MediaQueryResult&gt;): void
72
73通过句柄向对应的查询条件注册回调，当媒体属性发生变更时会触发该回调。
74
75> **说明：**
76>
77> 注册的回调中不允许进一步调用on或off。
78
79**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
80
81**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
82
83**系统能力：** SystemCapability.ArkUI.ArkUI.Full
84
85**参数：**
86
87| 参数名   | 类型                                                  | 必填 | 说明                     |
88| -------- | ----------------------------------------------------- | ---- | ------------------------ |
89| type     | string                                                | 是   | 必须填写字符串'change'。 |
90| callback | Callback&lt;[MediaQueryResult](#mediaqueryresult)&gt; | 是   | 向媒体查询注册的回调。     |
91
92**示例：**
93
94  详见[off示例](#offchange)。
95
96
97### off('change')
98
99off(type: 'change', callback?: Callback&lt;MediaQueryResult&gt;): void
100
101通过句柄向对应的查询条件取消注册回调，当媒体属性发生变更时不再触发指定的回调。
102
103**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
104
105**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
106
107**系统能力：** SystemCapability.ArkUI.ArkUI.Full
108
109**参数：**
110
111| 参数名   | 类型                             | 必填 | 说明                                                       |
112| -------- | -------------------------------- | ---- | ---------------------------------------------------------- |
113| type     | string                           | 是   | 必须填写字符串'change'。                                   |
114| callback | Callback&lt;[MediaQueryResult](#mediaqueryresult)&gt; | 否   | 需要去注册的回调，如果参数缺省则去注册该句柄下所有的回调。 |
115
116**示例：**
117
118  ```ts
119import { mediaquery } from '@kit.ArkUI';
120
121let listener = mediaquery.matchMediaSync('(orientation: landscape)'); //监听横屏事件
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) // 注册回调
130listener.off('change', onPortrait) // 去取消注册回调
131  ```
132
133## MediaQueryResult
134
135用于执行媒体查询操作。
136
137**卡片能力：** 从API version 12开始，该类型支持在ArkTS卡片中使用。
138
139**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
140
141**系统能力：** SystemCapability.ArkUI.ArkUI.Full
142
143
144### 属性
145
146| 名称    | 类型    | 可读 | 可写 | 说明                 |
147| ------- | ------- | ---- | ---- | -------------------- |
148| matches | boolean | 是   | 否   | 是否符合匹配条件。   |
149| media   | string  | 是   | 否   | 媒体事件的匹配条件。 |
150
151
152### 示例
153
154> **说明：**
155>
156> 推荐通过使用[UIContext](js-apis-arkui-UIContext.md#uicontext)中的[getMediaQuery](js-apis-arkui-UIContext.md#getmediaquery)方法获取当前UI上下文关联的[MediaQuery](js-apis-arkui-UIContext.md#mediaquery)对象。
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)') // 建议使用 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    // 绑定回调函数
181    this.listener.on('change', portraitFunc);
182  }
183
184  aboutToDisappear() {
185    // 解绑listener中注册的回调函数
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```