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