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[媒体查询](../reference/apis-arkui/js-apis-mediaquery.md)作为响应式设计的核心，在移动设备上应用十分广泛。媒体查询可根据不同设备类型或同设备不同状态修改应用的样式。媒体查询常用于下面两种场景： 13 141. 针对设备和应用的属性信息（比如显示区域、深浅色、分辨率），设计出相匹配的布局。 15 162. 当屏幕发生动态改变时（比如分屏、横竖屏切换），同步更新应用的页面布局。 17 18 19## 引入与使用流程 20 21媒体查询通过mediaquery模块接口，设置查询条件并绑定回调函数，任一[媒体特征](#媒体特征media-feature)改变时，均会触发回调函数，返回匹配结果，根据返回值更改页面布局或者实现业务逻辑，实现页面的响应式设计。具体步骤如下： 22 23首先导入媒体查询模块。 24 25 26```ts 27import { mediaquery } from '@kit.ArkUI'; 28``` 29 30通过matchMediaSync接口设置媒体查询条件，保存返回的条件监听句柄listener。例如监听横屏事件： 31 32 33```ts 34let listener: mediaquery.MediaQueryListener = this.getUIContext().getMediaQuery().matchMediaSync('(orientation: landscape)'); 35``` 36 37给条件监听句柄listener绑定回调函数onPortrait，当listener检测设备状态变化时执行回调函数。在回调函数内，根据不同设备状态更改页面布局或者实现业务逻辑。 38 39 40```ts 41onPortrait(mediaQueryResult: mediaquery.MediaQueryResult) { 42 if (mediaQueryResult.matches as boolean) { 43 // do something here 44 } else { 45 // do something here 46 } 47} 48 49listener.on('change', onPortrait); 50``` 51 52 53## 媒体查询条件 54 55媒体查询条件由媒体类型、逻辑操作符、媒体特征组成，其中媒体类型可省略，逻辑操作符用于连接不同媒体类型与媒体特征，其中，媒体特征要使用“()”包裹且可以有多个。 56 57 58### 语法规则 59 60语法规则包括[媒体类型（media-type）](#媒体类型media-type)、[媒体逻辑操作（media-logic-operations）](#媒体逻辑操作media-logic-operations)和[媒体特征（media-feature）](#媒体特征media-feature)。 61 62 63```ts 64[media-type] [media-logic-operations] [(media-feature)] 65``` 66 67例如： 68 69- screen and (round-screen: true) ：表示当设备屏幕是圆形时条件成立。 70 71- (max-height: 800px) ：表示当高度小于等于800px时条件成立。 72 73- (height <= 800px) ：表示当高度小于等于800px时条件成立。 74 75- screen and (device-type: tv) or (resolution < 2) ：表示包含多个媒体特征的多条件复杂语句查询，当设备类型为tv或设备分辨率小于2时条件成立。 76 77- (dark-mode: true) ：表示当系统为深色模式时成立。 78 79 80### 媒体类型（media-type） 81查询条件未写媒体类型时，默认为screen。媒体类型必须写在查询条件开头。 82 83| **类型** | **说明** | 84| ------ | -------------- | 85| screen | 按屏幕相关参数进行媒体查询。 | 86 87 88### 媒体逻辑操作（media-logic-operations） 89 90媒体逻辑操作符：and、or、not、only用于构成复杂媒体查询，也可以通过comma（, ）将其组合起来，详细解释说明如下表。 91 92 **表1** 媒体逻辑操作符 93 94| 类型 | 说明 | 95| ---------------- | ------------------------------------------------------------ | 96| and | 将多个媒体特征（Media Feature）以“与”的方式连接成一个媒体查询，只有当所有媒体特征都为true时，查询条件成立。另外，它还可以将媒体类型和媒体功能结合起来。例如：screen and (device-type: wearable) and (max-height: 600px) 表示当设备类型是智能穿戴且应用的最大高度小于等于600个像素单位时成立。 | 97| or | 将多个媒体特征以“或”的方式连接成一个媒体查询，如果存在结果为true的媒体特征，则查询条件成立。例如：screen and (max-height: 1000px) or (round-screen: true) 表示当应用高度小于等于1000个像素单位或者设备屏幕是圆形时，条件成立。 | 98| not | not操作符必须搭配screen使用，取反媒体查询结果，媒体查询结果不成立时返回true，否则返回false。例如：not screen and (min-height: 50px) and (max-height: 600px) 表示当应用高度小于50个像素单位或者大于600个像素单位时成立。 | 99| only | only操作符必须搭配screen使用, 当前效果与单独使用screen相同。例如：only screen and (height <= 50) 。| 100| comma（, ） | 将多个媒体特征以“或”的方式连接成一个媒体查询，如果存在结果为true的媒体特征，则查询条件成立。其效果等同于or运算符。例如：screen and (min-height: 1000px), (round-screen: true) 表示当应用高度大于等于1000个像素单位或者设备屏幕是圆形时，条件成立。 | 101 102媒体范围操作符包括<=，>=，<，>，详细解释说明如下表。 103 104 **表2** 媒体逻辑范围操作符 105 106| 类型 | 说明 | 107| ----- | ---------------------------------------- | 108| <= | 小于等于，例如：screen and (height <= 50)。 | 109| >= | 大于等于，例如：screen and (height >= 600)。 | 110| < | 小于，例如：screen and (height < 50)。 | 111| > | 大于，例如：screen and (height > 600)。 | 112 113 114### 媒体特征（media-feature） 115 116媒体特征包括应用显示区域的宽高、设备分辨率以及设备的宽高等属性，详细说明如下表。 117 118 **表3** 媒体特征说明表 119 120比较height、width等宽高尺寸时，支持vp和px单位，无单位时默认为px。 121 122| 类型 | 说明 | 123| ----------------- | ---------------------------------------- | 124| height | 应用页面可绘制区域的高度。 | 125| min-height | 应用页面可绘制区域的最小高度。 | 126| max-height | 应用页面可绘制区域的最大高度。 | 127| width | 应用页面可绘制区域的宽度。 | 128| min-width | 应用页面可绘制区域的最小宽度。 | 129| max-width | 应用页面可绘制区域的最大宽度。 | 130| resolution | 设备的分辨率，支持dpi，dppx和dpcm单位。其中：<br/>- dpi表示每英寸中物理像素个数，1dpi ≈ 0.39dpcm；<br/>- dpcm表示每厘米上的物理像素个数，1dpcm ≈ 2.54dpi；<br/>- dppx表示每个px中的物理像素数（此单位按96px = 1英寸为基准，与页面中的px单位计算方式不同），1dppx = 96dpi。 | 131| min-resolution | 设备的最小分辨率。 | 132| max-resolution | 设备的最大分辨率。 | 133| orientation | 屏幕的方向。<br/>可选值：<br/>- orientation: portrait（设备竖屏）；<br/>- orientation: landscape（设备横屏）。 | 134| device-height | 设备的高度。 | 135| min-device-height | 设备的最小高度。 | 136| max-device-height | 设备的最大高度。 | 137| device-width | 设备的宽度。当前仅在应用初始化时保存一次，不会随设备宽度变化实时更新，例如折叠屏的折叠展开场景。 | 138| device-type | 设备的类型。<br/>可选值：default、phone、tablet、tv、car、wearable、2in1。 | 139| min-device-width | 设备的最小宽度。 | 140| max-device-width | 设备的最大宽度。 | 141| round-screen | 屏幕类型，圆形屏幕为true，非圆形屏幕为false。 | 142| dark-mode | 系统当前的深浅模式。可选值：true、false。 <br/> 深色模式为true，浅色模式为false。 | 143 144>**说明：** 145> 146>目前在卡片中使用媒体查询，只支持height、width。 147 148## 场景示例 149 150下例中使用媒体查询，实现屏幕横竖屏切换时，为页面文本应用添加不同的内容和样式。 151 152Stage模型下的示例： 153 154<!--deprecated_code_no_check--> 155```ts 156import { mediaquery, window } from '@kit.ArkUI'; 157import { common } from '@kit.AbilityKit'; 158 159@Entry 160@Component 161struct MediaQueryExample { 162 @State color: string = '#DB7093'; 163 @State text: string = 'Portrait'; 164 // 当设备横屏时条件成立 165 listener:mediaquery.MediaQueryListener = this.getUIContext().getMediaQuery().matchMediaSync('(orientation: landscape)'); 166 167 // 当满足媒体查询条件时，触发回调 168 onPortrait(mediaQueryResult:mediaquery.MediaQueryResult) { 169 if (mediaQueryResult.matches as boolean) { // 若设备为横屏状态，更改相应的页面布局 170 this.color = '#FFD700'; 171 this.text = 'Landscape'; 172 } else { 173 this.color = '#DB7093'; 174 this.text = 'Portrait'; 175 } 176 } 177 178 aboutToAppear() { 179 // 绑定当前应用实例 180 // 绑定回调函数 181 this.listener.on('change', (mediaQueryResult: mediaquery.MediaQueryResult) => { 182 this.onPortrait(mediaQueryResult) 183 }); 184 } 185 186 aboutToDisappear() { 187 // 解绑listener中注册的回调函数 188 this.listener.off('change'); 189 } 190 191 // 改变设备横竖屏状态函数 192 private changeOrientation(isLandscape: boolean) { 193 // 获取UIAbility实例的上下文信息 194 let context:common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext; 195 // 调用该接口手动改变设备横竖屏状态 196 window.getLastWindow(context).then((lastWindow) => { 197 lastWindow.setPreferredOrientation(isLandscape ? window.Orientation.LANDSCAPE : window.Orientation.PORTRAIT) 198 }); 199 } 200 201 build() { 202 Column({ space: 50 }) { 203 Text(this.text).fontSize(50).fontColor(this.color) 204 Text('Landscape').fontSize(50).fontColor(this.color).backgroundColor(Color.Orange) 205 .onClick(() => { 206 this.changeOrientation(true); 207 }) 208 Text('Portrait').fontSize(50).fontColor(this.color).backgroundColor(Color.Orange) 209 .onClick(() => { 210 this.changeOrientation(false); 211 }) 212 } 213 .width('100%').height('100%') 214 } 215} 216``` 217 218FA模型下的示例： 219 220<!--deprecated_code_no_check--> 221```ts 222import { mediaquery } from '@kit.ArkUI'; 223import { featureAbility } from '@kit.AbilityKit'; 224 225@Entry 226@Component 227struct MediaQueryExample { 228 @State color: string = '#DB7093'; 229 @State text: string = 'Portrait'; 230 listener:mediaquery.MediaQueryListener = mediaquery.matchMediaSync('(orientation: landscape)'); // 当设备横屏时条件成立 231 232 onPortrait(mediaQueryResult:mediaquery.MediaQueryResult) { // 当满足媒体查询条件时，触发回调 233 if (mediaQueryResult.matches as boolean) { // 若设备为横屏状态，更改相应的页面布局 234 this.color = '#FFD700'; 235 this.text = 'Landscape'; 236 } else { 237 this.color = '#DB7093'; 238 this.text = 'Portrait'; 239 } 240 } 241 242 aboutToAppear() { 243 // 绑定当前应用实例 244 this.listener.on('change', (mediaQueryResult:mediaquery.MediaQueryResult) => { this.onPortrait(mediaQueryResult) }); //绑定回调函数 245 } 246 247 aboutToDisappear() { 248 // 解绑listener中注册的回调函数 249 this.listener.off('change'); 250 } 251 252 build() { 253 Column({ space: 50 }) { 254 Text(this.text).fontSize(50).fontColor(this.color) 255 Text('Landscape').fontSize(50).fontColor(this.color).backgroundColor(Color.Orange) 256 .onClick(() => { 257 let context = featureAbility.getContext(); 258 context.setDisplayOrientation(0); //调用该接口手动改变设备横竖屏状态 259 }) 260 Text('Portrait').fontSize(50).fontColor(this.color).backgroundColor(Color.Orange) 261 .onClick(() => { 262 let context = featureAbility.getContext(); 263 context.setDisplayOrientation(1); //调用该接口手动改变设备横竖屏状态 264 }) 265 } 266 .width('100%').height('100%') 267 } 268} 269``` 270 271 **图1** 竖屏 272 273 274 275 **图2** 横屏 276 277 278 279## 相关实例 280 281针对媒体查询开发，以下相关实例可供参考： 282 283- [横竖屏切换（ArkTS）（API9）](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/UI/ArkTsComponentCollection/MediaQuery) 284
