鸿蒙折叠屏平行视界适配：easy_go.json配置四坑与校

鸿蒙专家

「薪晴」（WorthDay，包名 com.wy.worthday，零权限、零联网、纯本地计算）在直板机上一切正常。装到折叠屏上展开后就露了馅：点进一个列表项，整页跳转，十二英寸的屏幕右半边空着。传统解法不难想——把 Router 迁到 Navigation、页面拆双分栏、跨栏状态推倒重来，但工程量按周算，改完还得把所有路由跳转回归一遍。后来走的另一条路：一份 JSON 配置，业务代码一行没动，折叠屏上就有了双页同构。平行视界到底是什么官方定义很克制：针对大屏设备的系统级应用显示技术，允许同一个应用同时开两个页面。关键词是“系统级”——它不是一套新的导航框架，而是在应用还没做分栏布局时，由系统替你把两个页面摆到同一屏上，属于兜底能力。这个定位也划出了边界：页面怎么摆它管，布局细节和交互心智它不管。接入只要三步第一步，在 entry/src/main/resources/base/profile/ 下新建配置文件，文中用的是 easy_go.json。第二步，在 module.json5 里加字段指过去：

2. {
3.   "module": {
4.     "easyGo": "$profile:easy_go"
5.   }
6. }

复制代码

第三步，写配置本身。平行视界只支持 entry 模块，应用级生效：

2. {
3.   "common": {
4.     "displayModeOptions": {
5.       "wideWindowMode": "routerSplit",
6.       "squareWindowMode": "routerSplit",
7.       "routerSplitOptions": {
8.         "homePage": "pages/Index",
9.         "mode": 1,
10.         "enableReducedContainerSize": true,
11.         "fullScreenPages": ["pages/SharePage"],
12.         "wideSplit": { "ratio": "1 | 2" },
13.         "squareSplit": { "ratio": "1 | 1" },
14.         "splitDividerColor": {
15.           "light": "#FFE3E6EB",
16.           "dark": "#FF2A2F38"
17.         }
18.       }
19.     }
20.   }
21. }

复制代码

长方形和方形必须拆成 wideSplit 与 squareSplit 两个对象，因为双折叠展开后窗口接近方形，可用比例跟长方形平板不是一回事。wideWindowMode 有三个取值：navigationSplit 按 Navigation 分栏、routerSplit 按 Router 分栏、original 关闭兼容走自己的布局。四个容易踩的坑其一，homePage 不配，左右关系全乱。只配 wideWindowMode 就想让系统自己识别，结果左边显示的页面与预期不一致，整个分栏的基点就是错的。跑 Router 的要配 routerSplit 并把 homePage 写成 pages/Index；跑 Navigation 的要配 navBar 或某个 NavDestination 的 name。官方文档里有一句提醒很关键：默认的主页识别机制“在有些场景下不能准确识别”。不主动指定，等于把基点交给一个不一定准的猜测。其二，mode 选错，交互心智不匹配。mode: 0 是购物模式，右侧永远是栈顶，适合层层深入；mode: 1 是导航模式（默认值），左边主页固定、右边覆盖式切换，适合 IM、邮箱、分类导航这类“左固定右内容”的结构。首页是 Tab 聚合页、点进去做横向切换的场景应停在 mode: 1；主流程一路下钻的则要配 0。这条配错不会报错，只是每次返回都有一点说不出的别扭。其三，按全窗口计算的布局进分栏会直接溢出。官方常见问题第一条就是 UI 元素被截断：卡片边缘被切掉一截，得改成按可用宽度自适应才正常。配套要打开 enableReducedContainerSize: true，否则虚拟容器和断点仍按全窗口算，详情页里写的断点判断等于白判断。其四，弹窗和沉浸页都默认自己占满全屏。弹窗、半模态进入分栏后会横跨分割线，这个没有配置项能救，只能让浮层跟随所在页面弹出。更尴尬的是“整屏只做一件事”的沉浸页——比如分享长图页，卡片要给用户看完整一张再存相册，进分栏会被劈成两半。这类页面不用改代码，塞进白名单即可：

2. "fullScreenPages": ["pages/SharePage"]

复制代码

这行大概是整份配置里性价比最高的：分栏的默认假设是“两个页面被同时看”，沉浸页的前提是“只看这一件事”，两者天生冲突。分割线同理，splitDividerColor 要按 light 和 dark 各配一份 #AARRGGBB，不支持深色模式就配成同色，别留一条在深色下发光的分割线。比例、拖拽与应用内分屏ratio 的格式是“正整数 | 正整数”，范围夹在 1:2 到 2:1 之间，配超了会静默取边界值，不报错。isDraggable 一开，ratio 就失效，默认从 1:1 起在三档之间吸附拖动。isDraggable 这一版没开，因为它一开连默认值和初始态也一起交出去了；不过结论摆出来：用户自己找到舒服的比例，往往比我们猜更聪明，前提是拖完布局不塌。应用内分屏的开关是 enableInSplitScreen: true：分栏态下点分屏入口，应用以主窗口进入系统分屏，原窗口继续保持平行视界，一屏三区。入口按钮要判两个条件，isEasySplit() 判断是否处于分栏态，windowStatusType 判断是否已经在系统分屏里；只判前者，用户已经分屏了按钮还在，点了没反应。两个硬边界要记住：自由多窗模式下暂不支持平行视界；mode、比例拖拽、分割线这些属于 API 26 新能力，得升到 HarmonyOS 7，并以实际支持机型为准。什么时候该自己写 Navigation平行视界的好处是不改业务代码就换来两页同屏，代价是布局控制权交给系统。所以要算两笔账：两页同时在屏是真省了跳转返回，还是把两页都挤窄了；一份 JSON 的成本能不能压住后续的 UI 返工。能自己写的就自己写 Navigation——三分栏、跨栏联动、特殊转场都归这一类；留给平行视界的，是“这一版没精力重写”的那部分。判据也容易搞错：路由关系只是入场券，真正的判据是这两个页面要不要被同时看见。深链路一路往里钻、看完就走的场景强行分屏反而是干扰。另外 routerSplitOptions 和 navigationSplitOptions 不能并存，第一步得想清楚自己跑在哪套路由上。AI 写 ArkTS 不准，问题不在模型“笨”页面怎么摆解决之后，下一个问题更根本：页面本身怎么造出来。用 AI 辅助写鸿蒙，体验是分裂的——通用 TypeScript 逻辑顺手，ArkTS 组件经常来回改三四轮。最典型的报错是 Object literals cannot be used as type declarations，对应规则 arkts-no-obj-literals-as-types：

2. let person: { name: string; age: number } = { name: 'Alice', age: 30 };

复制代码

这行在 TypeScript 里完全合法，放到 ArkTS 就编译不过。原因不复杂：ArkTS 的语料远少于 TS，两者语法又高度相似，模型学过海量 TS，遇到像 TS 的写法就按 TS 生成——这是概率问题，不是智力问题。所以做法不该是期待“它自己知道鸿蒙怎么写”，而是先把鸿蒙的规则装给它，再让它干活。前者靠运气，后者靠工程。把 DevEco CLI 接进已有工作流DevEco CLI 的价值在于它不是 IDE。已经有一套通用 Agent 的 AI Coding 流程时，为了用鸿蒙的 AI 能力去换 IDE，等于工作流推倒重来；一个人做产品，最贵的成本就是打断自己的节奏。DevEco CLI 反过来把鸿蒙开发能力做成命令，让 Agent 去调：

2. devecocli init   # 把鸿蒙技能集装进 Agent
3. devcocli check   # 语法检查
4. devecocli build  # 编译打包
5. devecocli run    # 推包运行

复制代码

价值在可组合：“改完代码 → check → build → run → 看日志”这条链路，以前靠人肉串，现在成了流水线的一环。配套知识库覆盖多设备高频场景、ArkUI 与媒体安全开发指南、API 参考、FAQ 和版本说明，两个设计细节决定它好不好用：本地响应，不用联网查文档；渐进式读取，按需加载而不是一次灌进去，这对上下文有限的 Agent 尤其重要。官方 Skill 有 70 多个，多设备避让适配和废弃接口检查最常用，前者省掉人眼扫页面的活，后者是升 API 版本时的必备动作。它支持被 Claude Code、OpenClaw、Codex、Trae、Qoder 等主流 AI Coding Agent 集成，不要求你换工具，只要求工具能调命令行。Goal 模式的边界：交给它执行，不交给它思考DevEco Code 是另一条开箱即用的路，三种模式对应三种分工：Goal 规格驱动，锁定验收标准、自测修复到达标；Plan 先出完整方案、人工审核后再编码；Build 快速定需求、边写边测。Goal 的链路很长：需求澄清、验收标准确认、方案设计确认、任务列表确认，然后代码生成、语法检查、修复、构建出包、推模拟器、功能自验证，关键在于“规格制定阶段简单交互，之后免人工介入”。这句话也划出了边界——它不替你思考，只替你执行一个已经想清楚的规格。所以适用面很窄：只用在验收标准能写成断言的活上，比如“点第二步必须进第三步，返回必须回第二步”。需求还在变的探索期用 Goal 模式是浪费它的自测能力，它会把一个错误的目标执行得非常彻底。把手工适配变成可验证的流水线平行视界是配置兜底，但兜底有前提：你得先知道哪些页面需要适配，而这恰恰是手工适配最耗时、最容易漏的部分。官方把这件手工活拆成三层难点：范围难识别，组合太多人眼扫不全，漏一个就是上线后一条差评；方案难落地，既要适配新设备又不能把原设备的基线体验搞塌；结果难验证，每种形态都要单独复现、回归、确认，验证本身比改代码还费时间。HarmonyOS 开发助手里“多设备适配”做的事和手工流程一致，只是做成了流水线。五步中第 1 步和第 5 步才是真价值点，正好对应范围识别和结果验证；中间三步反倒可以预期，本来就知道要改代码。它不是丢一份“这里可能有问题”的清单就完事，而是把页面语义和空间关系还原出来、按真机或模拟器的真实尺寸算风险、给出改完能再跑一遍的验证路径。对一个人做产品来说，省掉的不是改代码的时间，而是“确认自己改对了”的时间，后者通常更贵。它覆盖屏幕适配和相机适配。相机这条值得单独提：折叠开合会让相机预览方向错乱，这种问题布局检查工具完全扫不出来。插件不只在 DevEco Studio 里用，Visual Studio Marketplace、Open VSX Registry、JetBrains Marketplace、DCloud 插件市场都能装，搜 HarmonyOS Dev Assistant 装完即用。它的完整能力有四块——一站式生成元服务、小程序转换元服务、三方库鸿蒙化、多设备适配；原生 ArkTS 应用没有迁移负担，只用到最后一块即可。留给人的那条线这些工具真正解决的问题，是“决定权放在谁手里”：平行视界把布局决定权交给系统，换来零改造；Navigation 把决定权留在自己手里，换来精细控制；Goal 模式把执行权交给 AI，前提是规格由你定；开发助手把“找出适配范围”交给工具，因为人眼扫不全组合。但有些判断工具给不了：mode 选 0 还是 1，ratio 配 1:2 还是开拖拽，工具能告诉你“这里有 12 个页面需要适配”，却不会告诉你“这两个页面应该被同时看见”。那条线，还得自己划。

热心网友6

这篇把平行视界的定位讲得很透，尤其是“系统替你把两页摆到同一屏上”这个兜底定位，比不少文档里绕来绕去的定义好理解。我们项目也是折叠屏展开后右半边空着，第一反应也是迁 Navigation，看到一份 JSON 能不动业务代码就出双页，确实值得试。 四个坑里 homePage 那条我踩得最深。当时只配了 routerSplit，以为系统能自己识别，结果展开后左边出来个不相干的页面，返回逻辑也跟着乱，后来老老实实写 pages/Index 才正常。mode 我也犹豫过，首页是 Tab 聚合、点进去横向切页，配 0 试了下每次返回都别扭，换回 1 才顺，确实是不报错但手感不对。 enableReducedContainerSize: true 这个提醒很关键。我们详情页里写了断点判断，没开之前按全窗口算，一分栏就溢出，卡片边缘直接被切。fullScreenPages 白名单也深有同感，分享长图页被劈成两半那个画面太真实了，塞进白名单基本零成本。 想请教一下应用内分屏那个入口按钮，isEasySplit 和 windowStatusType 两个条件同时判，你们是在页面 onPageShow 里刷状态，还是监听窗口变化？我们目前只在显示时判一次，担心用户拖了窗口后按钮状态没更新。另外自由多窗不支持平行视界这条边界也记下了，之前真没注意。感谢分享，先收藏了。

热心网友6

感谢分享，这篇把平行视界的定位讲得很清楚——“系统级兜底能力”，不是导航框架，这个定性一出来后面很多取舍就顺了。我们之前也踩过 homePage 不配的坑，表现确实是左边显示的页面跟预期对不上，当时还以为是页面栈顺序的问题，排查了半天才回到配置本身，官方那句“有些场景下不能准确识别”真不是客套话。 mode 那条我特别有共鸣。0 和 1 配反了完全不报错，但用户点返回的时候会有一种说不上来的别扭，这种“软错误”比崩溃还难查。我们最后是按首页结构来定的：Tab 聚合页就停 1，主流程一路下钻的才用 0，跟帖子里说的一致。 fullScreenPages 白名单那行确实性价比最高。分享长图页被劈成两半这个场景太典型了，用户要的是看完整一张再存，分栏默认假设“两页同时看”跟它天生冲突，塞白名单比改代码省事太多。 另外 enableReducedContainerSize 这个点提醒得好，断点判断按全窗口算的话详情页里写的自适应全白搭，很容易漏。 有个小疑问想请教：isDraggable 这一版没开，是担心初始态和吸附档位不可控吗？如果后面开启，除了布局不塌之外还有没有别的回归点要提前看？我们正在犹豫要不要放给用户。

热心网友6

这篇总结很实用，尤其是把几个容易静默出错的点讲清楚了：homePage 不定会导致分栏基点错、mode 0 和 1 的交互心智差别、enableReducedContainerSize 不开断点等于白算，还有 fullScreenPages 把沉浸页塞进白名单，这几条都是排查时很容易绕进去的。配置示例也直观，wideSplit 和 squareSplit 分开配、分割线明暗两套颜色、ratio 超范围静默取边界这些细节挺有提醒价值。想确认一下，fullScreenPages 里填的是不是就是 Router 的路由路径，比如 pages/SharePage 这种？另外 enableReducedContainerSize 是不是建议分栏场景统一打开，避免详情页按全窗口算宽？最后那段“什么时候该自己写 Navigation”的权衡也很中肯，先算清两页同屏到底省了跳转还是挤窄了内容，再决定要不要上 JSON 兜底，这个判断思路很有帮助。