HarmonyOS 5.0.0 UIContext 断点监听怎么写稳：getMediaQuery、窗口变化和监听释放怎么拆

这个问题看起来像一个小细节，真正落到 HarmonyOS 5.0.0 以上的应用里，会牵出页面状态、生命周期、异常兜底和多设备适配几条线。我的处理方式是先把问题复现出来，再看哪一层负责，最后把能复用的部分封装起来。

我不会把它写成官方概念解释。概念只解决“知道是什么”，但开发时更常见的是：代码能跑，边界一来就乱。所以这篇按排查过程来讲，重点放在怎么复现、怎么拆方案、怎么验证。

问题先复现出来

最容易出错的写法，是页面进来时读一次宽度，然后把布局状态存在一个普通字段里。手机竖屏测试时它看起来没问题，但平板窗口被拖宽、折叠屏展开、横竖屏切换以后，页面还是按旧状态渲染。更麻烦的是页面已经退出，旧监听还在回调，新页面就会收到上一轮状态。

我一般会先做两个最小案例。第一个案例只保留问题本身，方便确认是不是框架能力用错；第二个案例加上工程边界，看看这个写法能不能放进真实项目里长期维护。

案例一：最小复现

先写一个最小页面，只监听 medium 断点。它的作用不是覆盖全部断点，而是验证监听和释放是不是成对出现。

@Entry
@Component
struct BreakpointDemo {
  @State current: string = 'compact'
  private listener?: mediaquery.MediaQueryListener

  aboutToAppear() {
    const ctx = getContext(this) as common.UIAbilityContext
    this.listener = ctx.getUIContext().getMediaQuery().matchMediaSync('(600vp <= width < 840vp)')
    this.listener.on('change', (m) => {
      this.current = m.matches ? 'medium' : 'compact'
    })
  }

  aboutToDisappear() {
    this.listener?.off('change')
  }
}

这段代码的重点不是行数，而是把触发条件写清楚。只要能稳定复现，后面判断问题就不会靠猜。这里我会观察三件事：状态有没有按预期变化，异常分支有没有被吃掉，页面离开后还有没有旧回调。

案例二：加上工程边界

工程里通常不止一个页面要监听断点，所以第二步把监听对象收口。页面只传 query 和回调，销毁时统一 release。

class BreakpointStore {
  private items: Array<mediaquery.MediaQueryListener> = []

  watch(uiContext: UIContext, query: string, hit: (ok: boolean) => void) {
    const item = uiContext.getMediaQuery().matchMediaSync(query)
    item.on('change', event => hit(event.matches))
    this.items.push(item)
  }

  release() {
    this.items.forEach(item => item.off('change'))
    this.items = []
  }
}

第二个案例比第一个更接近工程写法。它多出来的不是复杂度，而是边界：重复进入页面、任务被取消、窗口切换、资源失败、旧数据回写，这些都是线上更容易遇到的问题。

几种方案怎么选

我的判断标准很简单：如果这个能力只影响一个按钮，可以放在页面里；如果它会影响页面结构、数据回写、资源释放或者审核材料，就应该收口。HarmonyOS 应用后面要适配的设备形态会越来越多，把边界提前拆清楚，比上线后补丁式修复要稳。

验证清单

验证时我会按下面这几步走：第一，冷启动进入页面，看默认状态是否正确；第二，触发问题场景，看状态是否能恢复；第三，快速退出再进入，看旧任务是否还会回调；第四，模拟失败分支，看用户是否有兜底提示；第五，保留一张截图或日志，方便后续回看。

这几个动作看起来普通，但能挡住大部分“本地没问题、换设备就不稳”的情况。尤其是窗口化、折叠屏、多任务、后台恢复这些场景，靠肉眼点两下是不够的。

可以怎么封装复用

断点监听适合封装成一个很薄的 BreakpointStore，不要塞业务逻辑。它只负责监听、分发、释放。页面拿到 compact、medium、expanded 后，再决定列表列数、弹窗宽度和导航结构。这样后面做平板或折叠屏适配时，不需要逐页复制监听代码。

封装时我会刻意少做一点，不会一上来做成大框架。只保留三个入口：start、update、release。start 负责注册和初始化，update 负责接收变化，release 负责释放资源。这样后面无论换成页面监听、任务队列还是资源加载，都能沿着同一套检查方式排查。

以后怎么避免

这类问题最怕写完就算结束。我的做法是把它写进页面检查清单：有没有复现步骤，有没有两个案例，有没有失败兜底，有没有释放动作，有没有跨设备或窗口变化验证。只要其中一项缺失，就先别急着合并。

这篇对应的官方知识点可以继续往外扩：生命周期负责资源边界，ArkUI 状态负责界面刷新，TaskPool 或异步任务负责耗时逻辑，AGC 审核材料负责最终上架解释。把这些边界连起来，文章才不是空讲概念，代码也更经得起后续维护。