鸿蒙设备形态远不止手机一种——折叠屏、平板、2in1、车机,屏幕尺寸和方向千差万别。同一套 UI,在竖屏手机上好看,展开到折叠屏或平板后往往就「散架」了。这篇文章给出一套可复制的适配思路,并附可直接上手的 ArkTS 代码。

一、先理解三个核心概念
  1. 断点(Breakpoint):ArkUI 内置了一套窗口宽度断点,用来区分设备形态:
  • sm:320 – 600vp
  • md:600 – 840vp
  • lg:840 – 1024vp
  • xl:1024 – 1280vp
  • xxl:1280vp 以上
  1. 媒体查询(mediaquery):监听窗口方向、宽高等条件变化,做逻辑分支。

  2. 栅格布局(GridRow/GridCol):声明式地把内容按列排布,并能随断点自动改变列数和占位。

三者配合,就能让一套代码覆盖从手机到平板的绝大多数场景。

二、实战 1:用 GridRow/GridCol 做响应式栅格

最常用的场景:一个卡片列表,手机上 2 列、折叠屏展开后 3 列、平板上 4 列。用栅格容器一行代码就能搞定。

// 卡片数据模型与卡片子组件
interface CardData {
  title: string
  desc: string
  color: string
}

@Component
struct CardItem {
  title: string = ''
  desc: string = ''
  color: string = '#FF007DFF'

  build() {
    Column({ space: 8 }) {
      Text(this.title)
        .fontSize(18)
        .fontWeight(FontWeight.Bold)
        .fontColor(Color.White)
      Text(this.desc)
        .fontSize(13)
        .fontColor('#CCFFFFFF')
        .maxLines(2)
        .textOverflow({ overflow: TextOverflow.Ellipsis })
    }
    .width('100%')
    .height(120)
    .padding(16)
    .justifyContent(FlexAlign.Center)
    .borderRadius(12)
    .backgroundColor(this.color)
  }
}

@Entry
@Component
struct AdaptiveGrid {
  private cards: CardData[] = [
    { title: '卡片 1', desc: '鸿蒙开发', color: '#FF007DFF' },
    { title: '卡片 2', desc: 'ArkUI 声明式', color: '#FF6A3DFF' },
    { title: '卡片 3', desc: '响应式布局', color: '#FF2FA36B' },
    { title: '卡片 4', desc: '栅格布局', color: '#FFB14BF4' },
    { title: '卡片 5', desc: '折叠屏适配', color: '#FFE84826' },
    { title: '卡片 6', desc: '多形态设备', color: '#FF00B8D9' }
  ]

  build() {
    // columns 按断点指定列数:sm 4 列,md 8 列,lg 12 列
    GridRow({ gutter: { x: 12, y: 12 }, columns: { sm: 4, md: 8, lg: 12 } }) {
      ForEach(this.cards, (item: CardData) => {
        // span 也按断点变化:sm 占 2 列(=2列/行),md 占 2 列(=4列/行),lg 占 3 列(=4列/行)
        GridCol({ span: { sm: 2, md: 2, lg: 3 } }) {
          CardItem({ title: item.title, desc: item.desc, color: item.color })
        }
      }, (item: CardData) => item.title)
    }
    .width('100%')
    .padding(12)
  }
}

关键点:columns 和 span 都可以传对象 { sm, md, lg, xl, xxl },系统会根据当前窗口宽度命中对应断点,自动切换列数和占位,无需手写任何 if/else。

三、实战 2:监听横竖屏方向变化

折叠屏或平板经常被旋转,需要根据方向调整布局。用 mediaquery 监听方向:

import mediaquery from '@ohos.mediaquery'

@Entry
@Component
struct OrientationPage {
  private listener = mediaquery.matchMediaSync('(orientation: landscape)')

  aboutToAppear() {
    // 注册监听,回调里 result.matches 为 true 表示横屏
    this.listener.on('change', (result) => {
      if (result.matches) {
        // 横屏:可以切成分栏布局
        console.info('切换到横屏')
      } else {
        console.info('切换到竖屏')
      }
    })
  }

  aboutToDisappear() {
    // 记得解绑,避免内存泄漏
    this.listener.off('change')
  }

  build() {
    // ...
  }
}
四、实战 3:精确监听窗口尺寸变化

有些场景(比如拖拽分屏、窗口自由缩放)断点变化滞后,需要实时拿到宽高,用 window 模块:

import window from '@ohos.window'

@Entry
@Component
struct ResizePage {
  async listenResize() {
    const win = await window.getLastWindow(getContext(this))
    win.on('windowSizeChange', (data) => {
      // data.width / data.height 是实时宽高(vp)
      console.info(`窗口尺寸变化:${data.width} x ${data.height}`)
    })
  }

  aboutToAppear() {
    this.listenResize()
  }

  build() {
    // ...
  }
}

拿到实时宽高后,可以自定义判断逻辑:比如宽度超过 600vp 时切换成分栏导航,低于时收成底部 Tab。

五、踩坑记录(都是实际会遇到的)
  1. 只在 span 传数字、忘了配 columns 断点:数字是「固定占几列」,如果不给 columns 设断点,折叠屏展开后列数不会变,布局就不响应了。要么两者都用对象形式,要么明确知道自己在做什么。

  2. span 数字和对象混用:同一个 GridCol 里要么写 span: 2,要么写 span: { sm: 2, md: 3 },混着写容易让人困惑、效果不符合预期。

  3. mediaquery 监听不 off:on('change') 注册的回调如果页面销毁时不 off,会造成内存泄漏,反复进出页面后卡顿。

  4. 单位用 px 不用 vp:多设备适配下务必用 vp(虚拟像素),用 px 在高低密度屏幕上会缩放异常,平板上看尤其明显。

  5. 断点变化 vs 窗口尺寸变化的时机差异:断点是根据宽度区间「跳变」的,而 windowSizeChange 是「连续」的。需要精确控制时用窗口监听,需要简洁语义时用断点。

六、小结

鸿蒙多形态适配的核心就一句话:把「写死」的布局改成「声明式响应」。

  • 有卡片/列表网格 → 用 GridRow/GridCol + 断点;
  • 要区分横竖屏 → 用 mediaquery;
  • 要精确到宽高 → 用 window 的 windowSizeChange。

三者按需组合,一套代码就能在手机、折叠屏、平板上优雅地跑起来。下一篇我会接着写「三方库/三方框架的接入与封装」,欢迎关注交流。


七、完整可运行示例(可直接复制)

把上面三块整合成一个页面,顶部实时显示「断点 / 方向 / 窗口尺寸」,下面是响应式栅格,可以直接复制到 entry/src/main/ets/pages/Index.ets 运行:

import mediaquery from '@ohos.mediaquery'
import window from '@ohos.window'

interface CardData {
  title: string
  desc: string
  color: string
}

@Component
struct CardItem {
  title: string = ''
  desc: string = ''
  color: string = '#FF007DFF'

  build() {
    Column({ space: 8 }) {
      Text(this.title)
        .fontSize(18)
        .fontWeight(FontWeight.Bold)
        .fontColor(Color.White)
      Text(this.desc)
        .fontSize(13)
        .fontColor('#CCFFFFFF')
        .maxLines(2)
        .textOverflow({ overflow: TextOverflow.Ellipsis })
    }
    .width('100%')
    .height(120)
    .padding(16)
    .justifyContent(FlexAlign.Center)
    .borderRadius(12)
    .backgroundColor(this.color)
  }
}

@Entry
@Component
struct Index {
  @State currentBreakpoint: string = 'sm'
  @State orientation: string = '竖屏'
  @State windowSize: string = '加载中...'

  private mediaListener = mediaquery.matchMediaSync('(orientation: landscape)')

  private cards: CardData[] = [
    { title: '卡片 1', desc: '鸿蒙开发', color: '#FF007DFF' },
    { title: '卡片 2', desc: 'ArkUI 声明式', color: '#FF6A3DFF' },
    { title: '卡片 3', desc: '响应式布局', color: '#FF2FA36B' },
    { title: '卡片 4', desc: '栅格布局', color: '#FFB14BF4' },
    { title: '卡片 5', desc: '折叠屏适配', color: '#FFE84826' },
    { title: '卡片 6', desc: '多形态设备', color: '#FF00B8D9' }
  ]

  aboutToAppear() {
    this.mediaListener.on('change', (result: mediaquery.MediaQueryResult) => {
      this.orientation = result.matches ? '横屏' : '竖屏'
    })
    window.getLastWindow(getContext(this)).then((win: window.Window) => {
      // 首次进入先读取初始尺寸(windowSizeChange 只在尺寸变化时触发)
      const rect = win.getWindowProperties().windowRect
      this.windowSize = `${rect.width} x ${rect.height}`
      win.on('windowSizeChange', (data: window.Size) => {
        this.windowSize = `${data.width} x ${data.height}`
      })
    })
  }

  aboutToDisappear() {
    this.mediaListener.off('change')
  }

  build() {
    Column({ space: 12 }) {
      Column({ space: 4 }) {
        Text('多形态设备适配 Demo')
          .fontSize(20)
          .fontWeight(FontWeight.Bold)
          .fontColor('#FF182431')
        Text(`断点: ${this.currentBreakpoint}  |  方向: ${this.orientation}  |  窗口: ${this.windowSize}`)
          .fontSize(13)
          .fontColor('#99182431')
      }
      .width('100%')
      .alignItems(HorizontalAlign.Start)
      .padding({ top: 12, bottom: 4 })

      GridRow({ gutter: { x: 12, y: 12 }, columns: { sm: 4, md: 8, lg: 12 } }) {
        ForEach(this.cards, (item: CardData) => {
          GridCol({ span: { sm: 2, md: 2, lg: 3 } }) {
            CardItem({ title: item.title, desc: item.desc, color: item.color })
          }
        }, (item: CardData) => item.title)
      }
      .width('100%')
      .onBreakpointChange((breakpoints: string) => {
        this.currentBreakpoint = breakpoints
      })

      Text('拖动窗口或旋转设备,观察栅格列数与顶部状态的变化')
        .fontSize(12)
        .fontColor('#99182431')
        .width('100%')
        .textAlign(TextAlign.Center)
        .padding(12)
    }
    .width('100%')
    .height('100%')
    .padding({ left: 12, right: 12, top: 4, bottom: 4 })
    .backgroundColor('#FFF1F3F5')
  }
}

八、运行效果(实机截图)

上面这套代码在 Mate X7 折叠屏模拟器上真实构建、安装、运行后的截图如下:
展开形态
在这里插入图片描述

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐