引言如果你同时使用手机和平板打开同一款应用你可能会注意到手机上是单列纵向滚动平板上是双列或三列网格。这不是两套代码——这是同一套代码根据屏幕尺寸动态切换了布局模式。这种同一套代码、多种屏幕表现的能力在移动端开发中称为响应式布局。HarmonyOS NEXT 提供了ohos.mediaqueryAPI 来实现响应式布局。它的工作原理类似于 Web 前端的 CSS Media Queries定义一个条件如屏幕宽度 ≥ 768vp监听这个条件的变化如设备旋转当条件匹配时切换布局。本文将通过构建一个响应式布局适配器深入讲解 mediaquery 的核心 APImatchMediaSync、MediaQueryListener、on(change)事件监听、以及基于断点的自适应布局策略。读完本文你将能够使用mediaquery.matchMediaSync()检测屏幕方向和尺寸使用on(change, callback)监听设备状态变化设计断点策略手机竖屏 / 手机横屏 / 平板三档使用Grid.columnsTemplate动态切换列数理解响应式布局与自适应布局的区别CSS Media Queries 的 ArkUI 对应如果你有 Web 开发经验你一定用过 CSS Media Queriesmedia(min-width:768px){.container{grid-template-columns:1fr 1fr;}}media(max-width:767px){.container{grid-template-columns:1fr;}}ArkUI 的ohos.mediaquery是这个概念的编程式对应。它不写在样式表中而是写在 ArkTS 代码中——通过 JavaScript API 检测条件、注册监听、驱动状态变化。import{mediaquery}fromkit.ArkUI;// 创建媒体查询监听器letmqListenermediaquery.matchMediaSync((min-width: 768vp));// 检查当前是否匹配if(mqListener.matches){// 平板布局}else{// 手机布局}// 监听后续变化如设备旋转、折叠屏展开mqListener.on(change,(result:mediaquery.MediaQueryResult){if(result.matches){// 切换到平板布局}});这个编程式 API 的一个优势是你可以在回调中执行任意的 ArkTS 逻辑——不仅仅是切换样式还可以重新组织数据结构、切换导航模式、甚至加载不同的子组件。核心 API 解析matchMediaSync(condition: string): MediaQueryListenermatchMediaSync接收一个条件字符串返回一个MediaQueryListener对象。条件字符串的语法与 CSS Media Queries 基本一致支持以下条件条件类型示例含义宽度(min-width: 768vp)视口宽度 ≥ 768vp宽度(max-width: 599vp)视口宽度 ≤ 599vp宽度(width: 360vp)视口宽度 360vp方向(orientation: landscape)横屏方向(orientation: portrait)竖屏设备类型(device-type: tablet)平板设备设备类型(device-type: phone)手机设备深色模式(dark-mode: true)系统深色模式注意单位使用vpvirtual pixel这是 ArkUI 的标准长度单位与 CSS 的px不同。MediaQueryListenerMediaQueryListener继承自MediaQueryResult增加了一个on方法用于注册变化监听matches: boolean— 当前条件是否匹配只读media: string— 匹配条件的原始字符串只读on(type: change, callback: CallbackMediaQueryResult): void— 注册变化监听off(type: change, callback?: CallbackMediaQueryResult): void— 移除监听当设备方向改变、折叠屏展开/折叠、窗口大小调整等事件发生时on(change)的回调会被触发result.matches反映了新的匹配状态。生命周期管理Listener 应该在aboutToAppear()中创建在aboutToDisappear()中移除privatemqListener:mediaquery.MediaQueryListener|nullnull;aboutToAppear():void{this.mqListenermediaquery.matchMediaSync((orientation: landscape));this.mqListener.on(change,this.onOrientationChange);}aboutToDisappear():void{if(this.mqListener!null){this.mqListener.off(change,this.onOrientationChange);}}Demo 设计三档断点策略本文 Demo 定义了三档断点断点条件列数布局模式手机竖屏width 600vp1 列单列纵向手机横屏600vp ≤ width 768vp2 列双列网格平板width ≥ 768vp3 列三列网格断点值的选取参考了常见设备尺寸手机竖屏约 320-400vp手机横屏约 600-700vp平板约 768vpDemo 提供两个入口来感知断点变化真实设备检测aboutToAppear()中使用matchMediaSync检测实际屏幕尺寸手动模拟切换三个按钮允许用户在手机上手动切换到平板布局模式手动模拟是必要的——因为在手机设备上真实屏幕尺寸永远处于手机竖屏断点中。如果没有模拟器用户无法在手机设备上看到平板布局的效果。断点更新逻辑updateBreakpoint(name:string):void{this.currentBreakpointname;if(name手机竖屏 ( 600vp)){this.columns1;this.layoutMode单列;}elseif(name手机横屏 (600-768vp)){this.columns2;this.layoutMode双列;}elseif(name平板 ( 768vp)){this.columns3;this.layoutMode三列;}}columns这个State变量的变化会触发 Grid 组件的重新渲染从而改变列数。核心实现自适应 Grid 布局Demo 的内容区是一个包含 6 张卡片的 Grid列数由columns状态决定Grid(){ForEach(this.cardData,(card:CardData){GridItem(){Column(){Text(card.title).fontSize(15).fontColor(#FFFFFF).fontWeight(FontWeight.Bold)Text(card.desc).fontSize(11).fontColor(#FFFFFFCC)}.width(100%).padding(16).borderRadius(10).backgroundColor(card.color)}},(card:CardData)card.title)}.columnsTemplate(this.getColumnsTemplate()).columnsGap(10).rowsGap(10)getColumnsTemplate()根据当前columns值返回不同的模板字符串getColumnsTemplate():string{if(this.columns1){return1fr;}if(this.columns2){return1fr 1fr;}return1fr 1fr 1fr;}columnsTemplate使用 CSS Grid 的fr单位——每列等分可用空间。1fr 1fr表示两列等宽1fr 1fr 1fr表示三列等宽。这种基于模板字符串的动态列数是 Grid 组件最灵活的用法——你不需要为每种布局写三套 Grid只需要改变columnsTemplate的参数。交互流程Demo 提供三个主要交互真实设备信息展示页面加载时自动检测设备方向和平板状态显示当前断点和布局模式手动断点切换三个按钮手机竖屏 / 手机横屏 / 平板让用户手动切换Grid 列数实时响应方向变化监听如果用户旋转设备on(change)回调自动检测并更新断点信息设备信息面板显示四个状态Row(){this.infoBadge(当前断点,this.currentBreakpoint,#1677FF)this.infoBadge(布局模式,this.layoutMode,#D53F8C)}Row(){this.infoBadge(方向,this.isLandscape?横屏:竖屏,#38A169)this.infoBadge(列数,this.columns.toString() 列,#ED8936)}这些信息让用户清楚看到当前运行在哪个断点中、Grid 是如何响应的。响应式布局 vs 自适应布局虽然响应式和自适应常被混用但它们有明确的区别维度响应式布局Responsive自适应布局Adaptive布局变化连续性变化任意宽度都有合适表现离散性变化几个固定断点实现方式百分比、flex、相对单位不同断点的固定布局设计成本高需要保证所有宽度都好看中只设计几个关键断点典型场景Web 网站移动端 AppArkUI 方式Flex 百分比 weightmediaquery 断点 Grid对于移动端 App 开发自适应布局Adaptive通常是更务实的选择——你只需要针对三到四个关键断点设计布局即可不需要像响应式网站那样覆盖从 320px 到 2560px 的所有宽度。本文 Demo 采取的是自适应策略定义三个断点每个断点对应固定的列数。这符合绝大多数 App 的多设备适配需求。ohos.mediaquery 的局限性理解 mediaquery 的局限性能帮助你做出更合理的技术决策只能检测不能改变mediaquery 告诉你当前屏幕是什么状态但它不能改变屏幕尺寸。真正的布局变化需要你根据检测结果手动切换。断点是全局的mediaquery 检测的是整个应用窗口的尺寸而不是某个组件的容器尺寸。如果你需要在特定容器内做响应式布局如侧边栏内部的宽度变化mediaquery 不适用需要使用组件的onAreaChange回调。不支持嵌套查询与 CSSmedia (min-width: 768px) and (orientation: landscape)不同ArkUI 的 mediaquery 单次调用只支持一个条件。如果需要组合条件需要分别创建多个 listener。API 18 已标记废弃在 API 18 中matchMediaSync被标记为 deprecated推荐使用ohos.arkui.UIContext.MediaQuery#matchMediaSync。不过 API 24 中旧 API 仍然可用。完整页面结构Column根容器 ├── Header深色标题栏响应式布局 ohos.mediaquery 标签 ├── Scroll │ └── Column │ ├── 设备信息面板4 个 badges断点、模式、方向、列数 │ ├── 断点模拟器3 个按钮手机竖屏 / 手机横屏 / 平板 │ ├── 自适应内容区Grid列数动态变化 │ └── API 参考文字 └── 根容器结束总结本文通过构建一个响应式布局适配器深入讲解了 HarmonyOS ArkUI 中ohos.mediaquery媒体查询 API 的核心用法matchMediaSync接收条件字符串返回 MediaQueryListener支持宽度、方向、设备类型、深色模式等条件MediaQueryListener提供matches当前是否匹配、on(change)变化监听、off(change)移除监听三档断点策略手机竖屏 1 列 / 手机横屏 2 列 / 平板 3 列Grid.columnsTemplate通过1fr模板字符串动态切换列数手动断点模拟通过按钮切换覆盖真实设备检测结果方便开发调试响应式/自适应布局是一次开发、多设备运行的基础设施。在一个鸿蒙应用需要同时运行在手机、折叠屏、平板、车机上的时代mediaquery 提供的设备感知能力是构建多端适配界面的第一步。在某种意义上mediaquery 是设备与 UI 之间的翻译官——它把硬件的物理属性屏幕尺寸、方向翻译成软件能理解的条件表达式。开发者只需要关心匹配什么条件时用什么布局而不需要关心这个硬件的像素密度是多少、物理尺寸是多少。