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