这篇文章不谈功能新增只谈显示是否稳定。HarmonyOS 项目如果准备上架多设备适配不能放到最后补。手机竖屏看起来正常不代表平板、横屏、小窗口和 2in1 就不会出现图片拉伸、文字截断或底部按钮被遮挡。健康菜谱助手属于内容型应用页面里有图片、卡片、列表、详情和阅读长文本。这类页面最容易在宽屏和小窗口下失衡所以从首页开始就要用断点和约束来写布局。关键词HarmonyOS 多设备、Breakpoint、底部导航、安全区、响应式布局先定义目标设备图 1先定义目标设备项目目标设备包括手机、平板和 2in1。手机以单列和底部导航为主平板要限制内容宽度2in1 要考虑窗口大小变化和鼠标操作。不同设备不是简单缩放关系而是信息密度和交互距离不同。因此页面根容器要使用百分比宽高内容区要能居中长内容必须放进 Scroll底部导航要留出安全距离。尤其是阅读页和详情页如果底部没有余量系统手势区域会影响操作。断点工具函数type Breakpoint sm | md | lgfunction resolveBreakpoint(width: number): Breakpoint {if (width 1200) {return lg}if (width 720) {return md}return sm}function contentMaxWidth(bp: Breakpoint): number | string {return bp lg ? 1180 : bp md ? 960 : 100%}断点决定布局不决定业务图 2断点决定布局不决定业务断点系统只解决展示问题不应该影响业务逻辑。比如当前是 sm、md 还是 lg只决定 banner 高度、内容最大宽度和卡片排列不应该改变菜谱数据本身。业务和布局分开才能避免横竖屏切换时数据状态丢失。项目通过 currentBreakpoint 存储当前断点页面根据断点计算 maxWidth。小屏幕全宽平板和桌面窗口限制在 960 或 1180 左右让页面不会被拉成横向长条。底部导航为什么继续放下面图 3底部导航为什么继续放下面有些桌面应用会把导航放左侧但健康菜谱助手的主要使用场景仍然是移动端和轻量浏览。统一使用底部导航可以降低用户认知也能让手机、平板、小窗口之间保持一致。底部导航要避免图标和文字挤压。标签文字需要单行、省略和固定高度导航区域要在系统手势区上方留空间。这个细节不明显但审核时很容易因为遮挡或不可点击被指出。图片和文字是适配重点图 4图片和文字是适配重点菜谱图片必须保持比例不能为了填满卡片而任意拉伸。标题、难度、时间、标签等文字要设置 maxLines 和 textOverflow。阅读文章则要关注行高和段落间距宽屏时不能让每行文字过长。适配不是把所有单位都改成百分比。真正有效的是明确哪些元素固定比例、哪些元素弹性扩展、哪些元素在宽屏时限制最大宽度。适配不是一套 CSS 式缩放图 5适配不是一套 CSS 式缩放ArkUI 多设备适配更像布局策略而不是把所有尺寸乘一个比例。手机上合理的卡片宽度在平板上可能显得空手机上合适的横向滑动在 2in1 上可能不符合鼠标操作习惯。健康菜谱助手采用内容最大宽度和居中容器是为了让宽屏阅读仍然舒服。同时图片比例要独立于容器宽度。菜谱图不能为了填充而变形阅读页也不能让一行文字横跨整个屏幕。视觉稳定比“占满屏幕”更重要。审核视角下的布局风险AppGallery 布局审核关注的是错位、截断、遮挡、模糊和不可操作。健康菜谱助手的风险点集中在图片卡片、底部导航、阅读页长文本、服务卡片入口和弹窗提示。每加一个新页面都要检查这些点。适配检查最好固定成表格手机竖屏、手机横屏、平板竖屏、平板横屏、2in1 窗口缩放、系统深色模式。不要只在开发时随手看一眼因为布局问题通常只在特定尺寸才暴露。落地细节阅读页和详情页的宽度策略不同同样是内容页菜谱详情和阅读文章的宽度策略不完全一样。详情页有图片、食材、步骤和操作按钮宽屏下可以适当利用横向空间阅读页则以长文本为主如果一行文字太长阅读速度会下降。因此阅读页的最大文本宽度应该更保守。平板横屏时可以让详情页图片和食材信息形成更宽的视觉区但步骤仍然保持较清晰的段落宽度。2in1 窗口缩小时页面要回到单列而不是强行维持宽屏布局。断点系统的意义就在这里用同一套代码表达不同设备下的阅读方式。还要注意状态栏和导航栏。页面背景如果和系统栏颜色割裂截图看起来会很粗糙如果底部按钮贴近手势条用户会误触或点不到。适配不是只看内容区也要看系统边界。多端适配的工程检查点多设备适配完成后重点不是问“有没有写断点”而是看结果是否自然。手机竖屏下底部导航要容易点击横屏或小窗口下内容不能被压到不可读平板上页面不能无限拉宽2in1 上鼠标点击和窗口缩放都不能破坏布局。健康菜谱助手还要单独检查阅读页。长文章在宽屏下如果一行太长会明显降低可读性详情页则要检查图片和步骤是否还在用户视线内。不同页面的信息密度不同不能用同一套宽度策略套到底。我建议把适配测试固定成发布前流程。每做一个新页面就至少在 sm、md、lg 三种宽度下看一次。这样问题会在开发阶段暴露而不是等审核或用户反馈。适配后的维护方式适配不是一次完成后就不用管。每新增一个卡片、弹窗、底部按钮或长文本页面都可能重新带来布局风险。健康菜谱助手后续如果加入购物清单、做菜模式或设置页都要沿用同一套断点和安全区规则。我更建议把适配经验写进开发约定页面根容器要有明确背景长内容必须可滚动图片必须保持比例底部操作要避开系统手势区。这样以后新增页面时不需要每次重新讨论规则。适配测试记录如何保存适配测试最好留下记录而不是测试完就算结束。可以按设备类型记录截图、问题、修复方式和复测结果。比如“平板横屏首页 banner 过高”“2in1 小窗口底部导航文字截断”“阅读页宽屏行长过长”这些记录后续都能变成项目的适配经验。有记录以后下一次改首页或阅读页时就能快速回看哪些尺寸曾经出过问题。适配经验会沉淀下来而不是只停留在某一次调试里。HarmonyOS 6.x 多设备适配落点健康菜谱助手的多设备适配不是写一句“支持平板”就结束而是在页面结构里落到具体规则。手机侧保持底部导航和单列内容平板侧限制内容最大宽度2in1 侧重点检查窗口缩放、鼠标点击和横向空间分配。这样同一套 ArkUI 页面不会因为屏幕变宽就失去阅读节奏。这部分对应 HarmonyOS 6.x 应用在主流终端上的适配要求。项目用断点、Scroll、内容限宽、图片比例、文本省略和底部安全区把布局风险提前处理目标是让首页、详情页、阅读页和卡片入口在不同设备上都不出现错位、截断、拉伸或底部遮挡。多设备适配的具体检查手机端重点检查底部导航、卡片宽度和滚动可达性。平板端重点检查内容是否过宽、图片是否被拉伸、阅读文本是否过长。2in1 重点检查窗口缩放时布局是否突然跳变鼠标点击区域是否足够清晰。不同设备的风险点不一样所以适配不能只靠一张手机截图判断。健康菜谱助手的页面里既有图文卡片也有长文章和服务卡片。图文卡片要保证图片比例长文章要保证行宽和行高卡片要保证小尺寸下文字不截断。只要这三类内容稳定应用在大多数设备形态下就不会显得粗糙。安全区和底部导航的处理底部导航放在下面符合移动端习惯但它必须尊重系统手势区域。按钮、标签、底部工具条和弹窗操作区都要留出足够距离尤其是在全面屏和手势导航设备上。如果底部按钮被系统导航区域遮挡用户会直接认为应用不可用这也是 AppGallery 审核常见风险。适配时不要只调一个固定高度。更稳妥的方式是把系统避让区域、最小安全间距和页面滚动容器一起考虑。长页面的最后一项内容要能滚到可见区域底部导航不应该压住列表结尾弹窗按钮也不能贴到屏幕边缘。适配问题要前置到开发阶段很多多设备问题不是最后一天才出现的而是开发时就埋下了。比如固定宽度卡片、固定高度图片、没有滚动的长页面、底部按钮贴边、文字没有 maxLines这些写法在手机样机上可能看起来正常但换到平板或小窗口就会明显变形。所以健康菜谱助手把适配规则写进开发习惯页面根容器全宽高长内容放入 Scroll图片保持比例宽屏限制最大内容宽度底部操作避开系统手势区域。这样每个新页面都天然带着适配意识而不是等审核指出问题再临时修。适配文章的评分关键给出设备矩阵多设备适配文章要写出检查范围。只说“支持手机和平板”不够应该明确手机竖屏、手机横屏、小窗口、平板横屏、2in1 窗口缩放分别检查什么。健康菜谱助手的重点是底部导航、首页图片、阅读页行宽、详情页滚动和卡片入口。发布摘要可以写成本文以健康菜谱助手为例记录 ArkUI 页面在手机、平板和 2in1 上的适配策略重点讲断点、内容最大宽度、底部安全区、图片比例和长文本阅读体验。适配踩坑左侧导航和底部导航的取舍这个项目在 2in1 窗口里曾出现过导航栏偏向左侧的体验问题。排查后发现桌面宽屏并不一定意味着要采用左侧导航因为健康菜谱助手的主场景仍然是移动端和轻量浏览用户在手机、平板和小窗口之间切换时更需要稳定一致的底部入口。最终做法是保留底部导航并通过内容最大宽度、居中布局和安全区 padding 解决宽屏留白问题而不是把主导航改成左栏。这个选择让移动端体验不被破坏也降低了多设备之间的认知成本。文章写出这种取舍比只说“已适配”更有参考价值。断点与安全区代码示例适配文章要有能复用的判断逻辑。下面的代码把宽度断点和底部安全距离拆开便于页面统一使用tstype DeviceLevel phone | tablet | twoInOnefunction resolveDeviceLevel(width: number): DeviceLevel {if (width 1200) {return twoInOne}if (width 720) {return tablet}return phone}function resolveContentWidth(level: DeviceLevel): number | string {return level twoInOne ? 1180 : level tablet ? 960 : 100%}文章里再解释为什么手机继续用底部导航、为什么宽屏不无限拉伸、为什么长文章要限制行宽就能把适配经验写得更扎实。第四篇小结多设备适配是一种工程习惯而不是发布前修补。健康菜谱助手通过断点、内容限宽、滚动容器、底部导航和图片比例控制让同一套 ArkUI 页面在多个设备形态下保持稳定。下一篇会进入语音朗读模块。写在最后欢迎多设备体验如果你手边有手机、平板或 2in1 设备欢迎下载健康菜谱助手测试一下多设备布局。特别是首页、阅读页和底部导航如果你发现某个尺寸下不够舒服欢迎评论反馈我会继续把适配细节打磨得更稳。十三、接入前检查清单第四篇同一套 ArkU正式接入前工程侧要过一遍检查清单SDK 版本与目标 API 版本匹配、权限在清单中声明且按需申请、能力开关在专用配置层管理、包体积增量符合预算。任何一项不过就先停带着不匹配的版本往上冲排错成本会翻倍。interface PrecheckItem { name: string; pass: boolean; note?: string } const checklist: PrecheckItem[] [ { name: SDK/API版本匹配, pass: false }, { name: 权限声明完整, pass: false }, { name: 开关集中管理, pass: false }, { name: 包体积增量预算, pass: false }, ] const allPass checklist.every(x x.pass)检查清单跑通的标志是新建工程按清单接入一次成功且不依赖任何口头经验。做不到说明文档还缺关键步骤。十四、常见坑与版本适配记录第四篇同一套 ArkU最常踩的坑集中在三处示例代码用的旧接口在新版本被拆分、默认配置与生产预期不一致、调试环境与真机行为有差异。每踩一个坑就记进版本适配表注明坑点、影响版本、修复方式与验证方式。interface Pitfall { issue: string; sinceApi: string; fix: string; verifiedOn: string[] } const pitfalls: Pitfall[] [] function knownPit(api: string): Pitfall[] { return pitfalls.filter(p p.sinceApi api) }适配表的价值在升级时兑现每次目标版本变更先对照表过一遍已知坑能省下一整轮盲目排查。