1# @ohos.mediaquery (媒体查询) 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @zju_ljz--> 5<!--Designer: @lanshouren--> 6<!--Tester: @liuli0427--> 7<!--Adviser: @HelloCrease--> 8 9提供根据不同媒体类型定义不同的样式。 10 11> **说明：** 12> 13> 从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> 15> 该模块不支持在[UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md)的文件声明处使用，即不能在UIAbility的生命周期中调用，需要在创建组件实例后使用。 16> 17> 本模块功能依赖UI的执行上下文，不可在[UI上下文不明确](../../ui/arkts-global-interface.md#ui上下文不明确)的地方使用，参见[UIContext](arkts-apis-uicontext-uicontext.md)说明。 18 19 20## 导入模块 21 22```ts 23import { mediaquery } from '@kit.ArkUI'; 24``` 25 26 27## mediaquery.matchMediaSync<sup>(deprecated)</sup> 28 29matchMediaSync(condition: string): MediaQueryListener 30 31设置媒体查询的查询条件，并返回对应的监听句柄。 32 33> **说明：** 34> 35> 从API version 18开始废弃，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getMediaQuery](arkts-apis-uicontext-uicontext.md#getmediaquery)获取[MediaQuery](arkts-apis-uicontext-mediaquery.md)对象，再通过此对象调用替代方法[matchMediaSync](arkts-apis-uicontext-mediaquery.md#matchmediasync)。 36> 37> 从API version 10开始，可以通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getMediaQuery](arkts-apis-uicontext-uicontext.md#getmediaquery)方法获取当前UI上下文关联的[MediaQuery](arkts-apis-uicontext-mediaquery.md)对象。 38 39**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 40 41**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 42 43**系统能力：** SystemCapability.ArkUI.ArkUI.Full 44 45**参数：** 46 47| 参数名 | 类型 | 必填 | 说明 | 48| --------- | ------ | ---- | ------------------------------------------------------------ | 49| condition | string | 是 | 媒体事件的匹配条件，具体可参考[媒体查询语法规则](../../ui/arkts-layout-development-media-query.md#语法规则)。 | 50 51**返回值：** 52 53| 类型 | 说明 | 54| ------------------ | -------------------------------------------- | 55| [MediaQueryListener](#mediaquerylistener) | 媒体事件监听句柄，用于注册和去注册监听回调。 | 56 57**示例：** 58 59```ts 60import { mediaquery } from '@kit.ArkUI'; 61 62let listener: mediaquery.MediaQueryListener = mediaquery.matchMediaSync('(orientation: landscape)'); //监听横屏事件 63``` 64 65 66## MediaQueryListener 67 68媒体查询的句柄，并包含了申请句柄时的首次查询结果。媒体查询根据设置的条件语句，比如'(width <= 600vp)'，比较系统信息，若首次查询时相关信息未初始化，matches返回false。 69 70继承自[MediaQueryResult](#mediaqueryresult)。 71 72**卡片能力：** 从API version 12开始，该类型支持在ArkTS卡片中使用。 73 74**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 75 76**系统能力：** SystemCapability.ArkUI.ArkUI.Full 77 78 79### on('change') 80 81on(type: 'change', callback: Callback<MediaQueryResult>): void 82 83通过句柄向对应的查询条件注册回调，当媒体属性发生变更时会触发该回调。 84 85> **说明：** 86> 87> 注册的回调中不允许进一步调用on或off。 88 89**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 90 91**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 92 93**系统能力：** SystemCapability.ArkUI.ArkUI.Full 94 95**参数：** 96 97| 参数名 | 类型 | 必填 | 说明 | 98| -------- | ----------------------------------------------------- | ---- | ------------------------ | 99| type | string | 是 | 必须填写字符串'change'。 | 100| callback | Callback<[MediaQueryResult](#mediaqueryresult)> | 是 | 向媒体查询注册的回调。 | 101 102**示例：** 103 104 详见[off示例](#offchange)。 105 106 107### off('change') 108 109off(type: 'change', callback?: Callback<MediaQueryResult>): void 110 111通过句柄向对应的查询条件取消注册回调，当媒体属性发生变更时不再触发指定的回调。 112 113**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 114 115**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 116 117**系统能力：** SystemCapability.ArkUI.ArkUI.Full 118 119**参数：** 120 121| 参数名 | 类型 | 必填 | 说明 | 122| -------- | -------------------------------- | ---- | ---------------------------------------------------------- | 123| type | string | 是 | 必须填写字符串'change'。 | 124| callback | Callback<[MediaQueryResult](#mediaqueryresult)> | 否 | 需要去注册的回调，如果参数缺省则去注册该句柄下所有的回调。 | 125 126**示例：** 127 128<!--code_no_check--> 129<!--deprecated_code_no_check--> 130```ts 131import { mediaquery } from '@kit.ArkUI'; 132 133let listener: mediaquery.MediaQueryListener = mediaquery.matchMediaSync('(orientation: landscape)'); //监听横屏事件 134function onPortrait(mediaQueryResult:mediaquery.MediaQueryResult) { 135 if (mediaQueryResult.matches) { 136 // do something here 137 } else { 138 // do something here 139 } 140} 141listener.on('change', onPortrait) // 注册回调 142listener.off('change', onPortrait) // 去取消注册回调 143 ``` 144 145## MediaQueryResult 146 147用于执行媒体查询操作。 148 149**卡片能力：** 从API version 12开始，该类型支持在ArkTS卡片中使用。 150 151**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 152 153**系统能力：** SystemCapability.ArkUI.ArkUI.Full 154 155 156### 属性 157 158| 名称 | 类型 | 只读 | 可选 | 说明 | 159| ------- | ------- | ---- | ---- | -------------------- | 160| matches | boolean | 是 | 否 | 是否符合匹配条件。true表示满足查询条件，false表示不满足查询条件。 | 161| media | string | 是 | 否 | 媒体事件的匹配条件。 | 162 163 164### 示例 165 166> **说明：** 167> 168> 推荐通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getMediaQuery](arkts-apis-uicontext-uicontext.md#getmediaquery)方法获取当前UI上下文关联的[MediaQuery](arkts-apis-uicontext-mediaquery.md)对象。 169 170<!--code_no_check--> 171<!--deprecated_code_no_check--> 172```ts 173import { mediaquery } from '@kit.ArkUI'; 174 175@Entry 176@Component 177struct MediaQueryExample { 178 @State color: string = '#DB7093' 179 @State text: string = 'Portrait' 180 listener: mediaquery.MediaQueryListener = this.getUIContext().getMediaQuery().matchMediaSync('(orientation: landscape)'); //监听横屏事件，mediaquery.matchMediaSync接口已废弃，建议使用this.getUIContext().getMediaQuery().matchMediaSync()来获取 181 182 onPortrait(mediaQueryResult:mediaquery.MediaQueryResult) { 183 if (mediaQueryResult.matches) { 184 this.color = '#FFD700' 185 this.text = 'Landscape' 186 } else { 187 this.color = '#DB7093' 188 this.text = 'Portrait' 189 } 190 } 191 192 aboutToAppear() { 193 let portraitFunc = (mediaQueryResult: mediaquery.MediaQueryResult): void => this.onPortrait(mediaQueryResult) 194 // 绑定回调函数 195 this.listener.on('change', portraitFunc); 196 } 197 198 aboutToDisappear() { 199 // 解绑listener中注册的回调函数 200 this.listener.off('change'); 201 } 202 203 build() { 204 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 205 Text(this.text).fontSize(24).fontColor(this.color) 206 } 207 .width('100%').height('100%') 208 } 209} 210``` 211
