4、应用兼容性基础：API版本适配、屏幕分辨率适配、横竖屏切换处理、多窗口模式兼容
各位同学好，我是老张。今天咱们聊聊应用兼容性里最基础、也最容易被忽视的几个点。说实话，我见过太多开发者在功能开发上花了大把时间，结果在兼容性上栽跟头。嗯，咱们今天就把这几个坑一个个填上。
4.1 API版本适配——别让你的应用“穿越”了
API版本适配，说白了就是你的应用得知道自己在哪个系统版本上跑。鸿蒙系统从1.0到现在的3.0、4.0，API一直在演进。我个人的习惯是：永远不要假设用户用的是最新版本。
核心原则：用新API时，一定要做版本判断。否则低版本设备上直接崩溃，用户会直接卸载你的应用。
我在项目中遇到过这样一个案例：有个团队用了HarmonyOS 3.0才引入的分布式文件API，结果在2.0设备上直接闪退。后来排查发现，他们根本没做版本检查。
正确的做法是这样的：
// 检查API版本
if (canIUse("SystemCapability.DistributedFile.DistributedFile")) {
// 使用分布式文件API
console.info("当前设备支持分布式文件能力");
} else {
// 降级处理，使用本地文件API
console.info("当前设备不支持分布式文件，使用本地方案");
}我的小技巧：在开发阶段就列一个“API版本兼容清单”，把每个新API对应的最低版本标清楚。这样测试的时候直接对着清单查，省心省力。
4.2 屏幕分辨率适配——别让UI“变形”了
鸿蒙设备从手机到平板，再到智慧屏，分辨率跨度非常大。你想想看，一个720p的手机和一个4K的智慧屏，UI能一样吗？
我建议采用百分比布局或者自适应布局，而不是写死像素值。鸿蒙的ArkUI框架在这方面做得不错，提供了很多响应式布局的能力。
| 设备类型 | 典型分辨率 | 适配建议 |
|---|---|---|
| 手机 | 1080×2340 | 使用vp单位，避免px |
| 平板 | 2560×1600 | 考虑分栏布局 |
| 智慧屏 | 3840×2160 | 注意焦点控制和字体缩放 |
我曾经接手过一个项目，所有控件都用px写死了。结果在平板上，按钮小得像米粒，用户根本点不到。后来全部改成vp单位，配合Flex布局，问题才解决。
// 推荐：使用vp单位
Button("点击我")
.width(200.vp)
.height(60.vp)
// 不推荐：使用px单位
Button("点击我")
.width(200.px)
.height(60.px)注意：不要只适配主流分辨率。鸿蒙设备生态里有很多“非主流”尺寸，比如折叠屏展开后的异形分辨率。测试时尽量覆盖更多设备。
4.3 横竖屏切换处理——别让用户“转晕”了
横竖屏切换，看起来简单，但坑不少。我记得有一次测试，应用在竖屏下一切正常，一切到横屏，布局全乱了，有些控件甚至跑到了屏幕外面。
为什么会这样？说白了，很多开发者只写了竖屏的布局，没考虑横屏时空间变宽了，内容应该怎么重新排列。
鸿蒙提供了onConfigurationUpdate回调，可以监听屏幕方向变化：
@Entry
@Component
struct MyPage {
@State isLandscape: boolean = false;
build() {
Column() {
if (this.isLandscape) {
// 横屏布局
Row() {
// 左右分栏
}
} else {
// 竖屏布局
Column() {
// 上下排列
}
}
}
.onConfigurationUpdate((config) => {
this.isLandscape = config.direction === Direction.LANDSCAPE;
})
}
}避坑指南：我曾经在横竖屏切换时忘记保存页面状态，结果用户填了一半的表单，一切屏数据全丢了。后来我养成了习惯：在onConfigurationUpdate里先保存关键状态，再重新布局。
4.4 多窗口模式兼容——让应用“能屈能伸”
鸿蒙的多窗口模式，说白了就是应用可以在分屏、悬浮窗等形态下运行。这对应用的适配要求更高了——窗口大小随时可能变化。
我个人的经验是：不要假设窗口大小是固定的。很多应用在分屏模式下，窗口宽度可能只有正常的一半，这时候布局必须能自适应。
这里有几个关键点：
- 避免固定宽度：用
百分比或Flex布局 - 处理窗口大小变化：监听
windowSizeChange事件 - 悬浮窗模式：注意控件大小和交互方式
// 监听窗口大小变化
this.context.eventHub.on('windowSizeChange', (width, height) => {
console.info(`窗口大小变化：${width}x${height}`);
// 根据新尺寸调整布局
if (width < 400.vp) {
// 小窗口模式，简化UI
} else {
// 正常模式
}
});重要提醒：多窗口模式下，应用的onForeground和onBackground生命周期可能会频繁触发。我见过一个应用，每次切到后台都重新加载数据，结果在分屏模式下卡得要命。记得做好状态缓存。
知识体系总览
下面这张图，是我自己整理的应用兼容性知识体系。你可以把它当作一个检查清单，开发时对着看，能少走很多弯路。
好了，这一章的内容就到这里。API版本适配、屏幕分辨率、横竖屏、多窗口——这四个点看似基础，但每一个都能单独写一篇事故报告。希望各位在实际开发中，能把这些原则真正用起来。