HarmonyOS ArkUI Navigation + GridRow：折叠态切换后的双栏路由恢复与返回栈收敛【鸿蒙心迹】

多形态适配里有一种问题很安静：界面没有崩，列表和详情也都能显示，但设备从紧凑态切到展开态后，返回键要按两次；再折回去，详情页又不见了。原因通常不在 GridRow 的列数，而在同一条业务路由被同时表达成"栈中的页面"和"右栏的选择"。

本文用 RouteDesk 演示一个消息工作台。页面名为 AdaptiveInboxPage，示例时刻统一为 12:22，当前消息 msg_4821，列表位置 37，展开态为 EXPANDED，恢复后栈深度为 2，诊断状态为 RESTORED。这些数据用于对齐正文与配图，不作为真机测试结果。

一、同一个详情，不应该拥有两套互相竞争的历史

紧凑宽度下，列表占满屏幕，点击消息后用 Navigation 进入详情，这是自然的前进关系。展开宽度下，列表与详情并排，点击消息只需更新右栏。麻烦出现在形态切换：如果展开时仍保留紧凑态压入的详情目的地，同时又在右栏渲染相同详情，返回栈里就藏着一个用户看不见的页面。

最常见的表现是：当前看到双栏，按返回键没有明显变化，第二次才离开工作台。第一下其实弹出了隐藏的详情目的地。反方向也会出问题：在展开态只保存 selectedId，折回紧凑态后没有把它恢复成可见详情，用户突然回到列表顶部。

我更愿意把这件事看成"路由投影"。业务状态只有一份：当前消息 ID、来源列表位置、筛选条件。界面形态决定如何投影它。紧凑态投影到导航栈，展开态投影到右栏。切换形态时要迁移投影，但不能复制业务历史。

示例约定如下：

• COMPACT：列表或详情单页显示，详情存在于 NavPathStack。
• EXPANDED：列表与详情并排，详情由 selectedId 驱动；栈中不保留工作台内部详情。
• msg_4821：无论形态如何变化，业务选择都保持一致。
• listIndex=37：返回列表时恢复到原位置，不用消息数组下标冒充稳定位置。
• stackDepth=2：诊断口径包含应用根目的地与工作台目的地，不包含右栏详情。

二、宽度只负责分型，不直接改导航

很多实现把 onAreaChange 写成一个万能入口：判断宽度、清空栈、选择详情、滚动列表、写持久化全挤在回调里。面积回调可能连续触发，布局动画期间宽度也会抖动。直接执行迁移，会造成重复 pushPath 或多次 pop。

这段代码解决宽度变化频繁触发时，形态判断不稳定的问题。

type WindowMode = 'COMPACT' | 'EXPANDED';

const EXPANDED_MIN_VP: number = 840;

@Entry
@Component
struct AdaptiveInboxPage {
  @State private windowMode: WindowMode = 'COMPACT';
  @State private pendingMode?: WindowMode;

  private classify(width: number): WindowMode {
    return width >= EXPANDED_MIN_VP ? 'EXPANDED' : 'COMPACT';
  }

  private requestMode(width: number): void {
    const next = this.classify(width);
    if (next === this.windowMode || next === this.pendingMode) {
      return;
    }
    this.pendingMode = next;
    Promise.resolve().then(() => {
      const target = this.pendingMode;
      this.pendingMode = undefined;
      if (target !== undefined && target !== this.windowMode) {
        this.applyMode(target);
      }
    });
  }

  build() {
    Column() {
      this.Workbench()
    }
    .onAreaChange((_oldValue, newValue) => {
      this.requestMode(Number(newValue.width));
    })
  }
}

阈值 840vp 是 RouteDesk 的设计决策，不是系统固定值。项目应根据内容最小宽度、字体缩放和交互密度设定断点。代码先把多次宽度事件收敛为一次微任务，再调用 applyMode()。这样布局感知只产生"目标形态"，真正的路由迁移集中在另一个方法里，便于测试和记录日志。

这里也没有根据"折叠屏型号"分支。窗口可能来自分屏、自由窗口、外接显示或横竖屏变化，可靠输入是应用实际可用区域。设备类型可以参与体验设计，但不应替代窗口尺寸判断。

三、把详情选择做成可序列化的业务快照

路由参数经常塞进一个完整对象：消息标题、头像、时间、正文都复制一份。列表数据刷新后，栈里的旧对象与右栏的新对象就会出现差异。更稳妥的做法是路由只保存稳定 ID，详情内容由仓储按 ID 获取。恢复需要的列表位置和筛选条件也放在一个明确快照里。

这段代码解决双栏选择、列表位置与导航参数各自保存导致的漂移。

export interface InboxSnapshot {
  selectedId?: string;
  listIndex: number;
  filter: 'ALL' | 'UNREAD';
  revision: number;
}

export interface MessageRouteParam {
  id: string;
  source: 'INBOX';
  revision: number;
}

export class InboxRouteStore {
  snapshot: InboxSnapshot = {
    selectedId: 'msg_4821',
    listIndex: 37,
    filter: 'ALL',
    revision: 12
  };

  select(id: string): MessageRouteParam {
    this.snapshot = {
      ...this.snapshot,
      selectedId: id,
      revision: this.snapshot.revision + 1
    };
    return { id, source: 'INBOX', revision: this.snapshot.revision };
  }
}

revision 不是服务器版本，而是页面快照的本地修订号。它可以帮助诊断"恢复动作是否覆盖了更新选择"，但不应拿来解决数据同步冲突。selectedId 允许为空：展开态刚进入工作台时，右栏可以显示占位页，而不是擅自打开第一条消息。是否自动选中第一项是产品决策，不能因为双栏有空白就让技术层替用户做选择。

列表位置 37 也不是消息的业务 ID。它只服务视觉恢复；数据集合改变后，需要把它夹在新的有效范围内，或者用锚点 ID 重新定位。本文保留 index 是为了演示字段一致性，不建议把它当成长期持久化的唯一定位依据。

四、迁移时只保留一份详情投影

Navigation 的路径栈适合表达可返回的页面历史。展开态右栏则是当前工作台内部的视图状态。切到展开态时，应从详情路由中提取 ID，保存到 store，然后把工作台内部详情从栈顶收掉；切回紧凑态时，如果存在选中 ID，再压入一次详情。迁移方法要幂等，同一目标形态调用两次不能多压一个页面。

这段代码解决形态切换后隐藏详情仍留在返回栈的问题。

@Component
struct AdaptiveInboxPage {
  private pathStack: NavPathStack = new NavPathStack();
  private routeStore: InboxRouteStore = new InboxRouteStore();
  @State private windowMode: WindowMode = 'COMPACT';
  @State private selectedId?: string = 'msg_4821';

  private applyMode(target: WindowMode): void {
    if (target === this.windowMode) {
      return;
    }

    if (target === 'EXPANDED') {
      const param = this.pathStack.getParamByName('MessageDetail')
        .pop() as MessageRouteParam | undefined;
      this.selectedId = param?.id ?? this.routeStore.snapshot.selectedId;
      this.pathStack.removeByName('MessageDetail');
    } else if (this.selectedId !== undefined) {
      this.pathStack.removeByName('MessageDetail');
      this.pathStack.pushPath({
        name: 'MessageDetail',
        param: {
          id: this.selectedId,
          source: 'INBOX',
          revision: this.routeStore.snapshot.revision
        } as MessageRouteParam
      });
    }
    this.windowMode = target;
  }
}

getParamByName()、removeByName() 与 pushPath() 都应以当前 SDK 的 NavPathStack 参考为准；团队如果封装了路由层，建议在封装中集中适配版本差异。示例先读取详情参数，再移除同名目的地。反过来写会把恢复所需的 ID 一起丢掉。

切回紧凑态之前先 removeByName('MessageDetail')，是幂等处理：即使一次异常迁移留下重复详情，也先收敛再压入当前选择。这样不会依赖"栈顶恰好就是详情"的脆弱假设。若应用允许详情之上继续打开编辑页或附件页，就不能粗暴删除所有同名项，需要给工作台路由加实例 ID，按作用域收敛。

下面的 DevEco Studio 风格画面用于说明工程位置。左侧是 pages、model 与 components，中间标出 applyMode()，右侧模拟器显示展开双栏，底部日志为 MODE COMPACT → EXPANDED、RESTORE msg_4821 与 STACK depth=2。它是演示图，不是开发工具或设备的实际截图。

五、GridRow 只决定排布，详情状态不藏进组件树

布局层的责任是：紧凑态显示一个主区域，展开态显示列表与详情两列。不要让右栏组件在 aboutToAppear() 中自行决定选中第一条，也不要让列表组件直接清理导航栈。否则父页面无法解释状态为何改变。

这段代码解决同一业务状态在单栏和双栏中如何一致渲染的问题。

@Builder
private Workbench() {
  GridRow({ columns: { sm: 4, md: 8, lg: 12 }, gutter: 16 }) {
    GridCol({ span: this.windowMode === 'EXPANDED' ? 5 : 12 }) {
      MessageList({
        selectedId: this.selectedId,
        initialIndex: 37,
        onSelect: (id: string) => this.openMessage(id)
      })
    }

    if (this.windowMode === 'EXPANDED') {
      GridCol({ span: 7 }) {
        if (this.selectedId !== undefined) {
          MessageDetail({ id: this.selectedId })
        } else {
          EmptyDetailHint()
        }
      }
    }
  }
}

private openMessage(id: string): void {
  const param = this.routeStore.select(id);
  this.selectedId = id;
  if (this.windowMode === 'COMPACT') {
    this.pathStack.pushPath({ name: 'MessageDetail', param });
  }
}

GridRow 的列配置提供响应式排布能力，示例在展开态分为 5 列列表和 7 列详情。这里的 12 列与 5/7 比例是界面方案，不是 HarmonyOS 对折叠屏的强制规范。紧凑态只有列表占据主区域；详情作为导航目的地由 Navigation 容器展示。

openMessage() 先更新业务 store，再决定是否压栈。这样展开态不会制造隐藏历史，紧凑态也不会缺少可返回页面。若连续点击同一条消息，还可以在 routeStore.select() 前判断 ID 是否相同，避免重复修订和重复加载。

运行示意图显示 RouteDesk 处于 EXPANDED：左栏定位第 37 项，右栏打开 msg_4821，状态为 RESTORED，栈深度为 2。红色标注指向"单一 selectedId"和"无隐藏详情栈"两个关键判断。

六、返回键应该先问业务层"现在有什么可退"

紧凑态详情页的返回动作清晰：弹出详情，回到列表，并恢复位置。展开态没有内部详情路径可弹，返回应离开工作台或交给更上层导航。若产品希望展开态按返回先清空右栏，也可以实现，但必须成为显式规则，并与紧凑态语义区分。

诊断页可以列出三组状态：业务快照、界面投影、导航栈。示例中业务快照是 selectedId=msg_4821、listIndex=37、revision=12；界面投影是 EXPANDED / RIGHT_PANE；导航口径是 depth=2 / hiddenDetail=0。只有三者同时成立，RESTORED 才有意义。

这张图承担解释作用：从 COMPACT 切到 EXPANDED 后，详情 ID 被转移到右栏，MessageDetail 从工作台内部栈清除，返回动作只剩一层。红圈标的是 hiddenDetail=0，而不是装饰性的按钮。

调试日志建议按一次形态迁移分组：

1. AREA width=912 target=EXPANDED。
2. SNAPSHOT selected=msg_4821 index=37 revision=12。
3. MIGRATE detail=STACK_TO_PANE。
4. STACK remove=MessageDetail depth=2。
5. RESTORE state=RESTORED hiddenDetail=0。

如果看到两条连续 pushPath MessageDetail，先检查宽度事件是否被重复消费；如果 selectedId 正确但右栏空白，检查详情数据仓储是否把 ID 当作数组下标；如果返回一次无反应，检查栈中是否还有作用域不明的详情目的地。调试的目标不是让日志越多越好，而是能从一次迁移重建因果顺序。

七、四类边界比"能展开"更值得验收

第一类是冷启动。应用通过通知或深链直接打开 msg_4821 时，展开态应把它投影到右栏，紧凑态应压入详情。不能先进入默认列表，再依赖一次尺寸变化碰巧恢复。

第二类是数据失效。恢复时如果 msg_4821 已被删除，store 应清空选择，展开态显示占位，紧凑态返回列表；不能把一个不存在的 ID 留在栈里反复报错。列表位置 37 超出新数据范围时也要收敛。

第三类是多级详情。消息详情可能打开附件预览或编辑页。此时折叠切换不能把所有深层路由都粗暴映射成一个右栏。较稳妥的做法是只把工作台第一层详情投影到右栏，更深层目的地继续保持栈语义；或者明确切换形态时关闭临时页面，并向用户保存草稿。

第四类是生命周期。进入后台、窗口重建或应用恢复时，业务快照应比组件临时状态更可靠。保存字段要小而稳定，避免序列化完整详情对象。恢复后先验证 ID，再建立界面投影，最后恢复滚动位置。顺序反了，列表可能先滚到 37，随后数据刷新又把位置重置。

这些检查没有华丽效果，却决定双栏是否可信。响应式适配不是给宽屏多塞一列，而是在形态变化时保住用户正在处理的对象、可预测的返回路径和可解释的状态。

八、把布局和导航当成两个正交维度

GridRow 回答"内容怎么摆"，Navigation 回答"用户怎么走"。两者会相互影响，但不应该由同一个布尔值随意驱动所有副作用。本文把它们通过业务快照连接：当前消息始终是 msg_4821，窗口形态决定它在栈里还是右栏里；无论如何都只保留一份详情投影。

演示中的 840vp、第 37 项、栈深度 2 与 RESTORED 都是可核对的示例数据，不是系统默认参数或性能结论。实际项目需要根据设计断点、导航层级和 SDK 版本调整。尤其不要把"删除同名路径"直接复制到支持多工作台实例的应用里，应该增加实例作用域。

如果要给这次设计留一句短结论，就是：形态可以变，业务选择不要分叉；布局可以重排，返回历史必须收敛。把详情当作业务状态，再将它投影到适合当前窗口的容器里，折叠屏、平板和自由窗口才不会各自长出一套难以维护的导航逻辑。

九、恢复顺序决定用户看到的是续接还是闪回

状态恢复并不是把几个字段重新赋值。页面重建后，数据仓储、窗口尺寸、导航容器和列表组件的就绪时间不同。如果先按默认 COMPACT 压入详情，随后才识别当前其实是 EXPANDED，用户可能看到一次详情页闪现，再切成双栏；如果先滚动到第 37 项而列表数据尚未载入，滚动命令会被忽略，最终又停在顶部。

RouteDesk 把恢复分为四步。第一步读取轻量快照，只得到 msg_4821、37、筛选条件和修订号；第二步加载当前筛选下的列表，验证消息是否仍存在；第三步等待首次有效宽度，把窗口分类为 COMPACT 或 EXPANDED；第四步才建立路由投影并恢复列表位置。任何一步失败都能回退到可解释的状态，而不是半恢复。

"首次有效宽度"不等于任意大于零的值。组件测量初期可能产生过渡尺寸，项目可以要求布局容器已完成首次稳定测量，或者由窗口信息层提供确定值。不要设置一个随意的几十毫秒定时器；设备性能与动画不同，延时只会把竞态换成更难复现的竞态。

消息验证也不能省略。若 msg_4821 已不在 ALL 列表中，但仍存在于别的分类，可以按产品规则切换筛选或提示用户；若已删除，则清空 selectedId。本文选择清空并保留列表位置附近的可见上下文。紧凑态不压入失效详情，展开态显示"选择一条消息"的占位。这样返回栈不会包含一个注定加载失败的页面。

恢复完成后再写 RESTORED。这个状态不是"读到了快照"，而是业务 ID 已验证、形态已确定、投影已建立、列表锚点已处理。诊断页把四个子步骤分别列出，可以迅速区分是数据问题、尺寸问题、路由问题还是滚动问题。

十、返回策略要对临时层和业务页分层

工作台里除了消息详情，还可能有搜索框、筛选抽屉、附件预览和编辑草稿。它们不能全部挤进同一个 NavPathStack 语义。用户按返回时，通常应先关闭临时层，再处理当前业务详情，最后离开工作台。但展开态是否清空右栏，要由产品明确决定。

一种可维护的优先级是：先关闭模态或弹层；若有未保存编辑，执行确认流程；紧凑态若正在详情，弹回列表并恢复 37；展开态若右栏只是选择结果，返回直接交给工作台上层；最后才离开应用当前模块。每一层都返回"是否已消费"，而不是让多个组件同时监听并各自修改状态。

如果产品要求展开态第一次返回清空右栏，诊断口径也要相应改变：第一次返回把 selectedId 置空，但栈深度仍为 2；第二次返回离开工作台。此方案与本文示例不同，并非错误，关键是不要既清空右栏又弹一个隐藏详情。业务选择与导航历史仍然只能有一个权威来源。

编辑草稿更敏感。切到展开态时不能为了收敛 MessageDetail 顺手删除其上的编辑目的地，否则可能丢内容。可以禁止形态迁移期间自动关闭编辑，或把编辑草稿先保存到独立 store，再重建合适投影。路由清理方法应认识"工作台详情""附件预览""编辑"这些层级，而不是只根据页面名称批量删除。

硬件返回、手势返回和页面按钮最好走同一策略函数。三条入口各写一遍，很快就会出现某条路径没有恢复列表位置，另一条路径遗漏草稿确认。自动化测试也应针对策略函数构造不同状态，而不是只模拟点击左上角按钮。

十一、可复核的测试矩阵应跨越两次形态变化

只测试从紧凑切到展开不够，许多重复路由要到"紧凑---展开---紧凑"第二次迁移才出现。最小矩阵可以包含：列表无选择时往返；打开 msg_4821 后往返；在展开态改选另一条再折回；第 37 项附近的数据刷新后往返；从通知冷启动详情后往返；附件预览打开时尝试切换；应用后台重建后恢复。

打开 msg_4821 的期望序列是：紧凑态压入详情；展开后选中 ID 保持，内部详情路径清零；再次紧凑时只压入一份详情；返回一次回到列表，位置仍为 37。检查点包括 hiddenDetail=0、当前 ID、栈内同名路径数量和列表锚点，缺一项都可能把问题藏住。

展开态改选另一条时，右栏立即更新，导航栈不能增长；折回紧凑态只压入最后选择的消息。若日志出现先压 msg_4821、再压新 ID，说明点击逻辑没有根据当前形态分流，或者迁移还在读取过期快照。此时不要通过返回时连弹两次来补救，应修正产生重复历史的入口。

数据刷新场景用于检验 index 的边界。如果列表缩短到 20 条，第 37 项已经无效，恢复函数要把位置收敛到有效范围，并在诊断中写出 index 37 → 19。如果消息仍在列表中，更好的做法是按稳定锚点定位，再把 index 当作后备。配图保持 37 是因为示例没有发生数据缩短，不应把两种情形混在一张图里。

测试结果也要区分"演示符合预期"和"设备实测通过"。本文只给出可执行的检查逻辑和期望数据，没有声明某一折叠屏型号、某一系统构建上的测试结论。团队交付时应补充设备或模拟器信息、窗口尺寸、系统与 SDK 版本、操作序列和实际日志，再决定是否能写通过。

十二、让日志围绕一次迁移形成闭环

日志若只写 expanded=true，无法解释谁触发、迁移了什么、最后是否收敛。可以为每次形态迁移分配 transitionId，例如 layout_0027，随后所有 AREA、SNAPSHOT、MIGRATE、STACK、RESTORE 事件都带同一 ID。出现异常时按 ID 聚合，就能看到完整闭环。

日志字段也应保持克制。消息正文和联系人名称没有必要进入布局诊断，只记录脱敏业务 ID、列表位置、形态、路径名、栈深度与修订号。深链参数若含敏感内容，应在进入统一路由层时先提取允许记录的字段，不能直接序列化整个 param。

重复迁移可以通过两项指标暴露：同一宽度区间内 applyMode 调用次数，以及一次 transition 中同名详情的移除和压入次数。它们不是产品性能指标，却很适合在开发阶段发现抖动。若面积事件很多但最终只有一次迁移，说明收敛生效；若一次迁移产生多个详情路径，说明幂等条件失效。

最后，日志闭环必须有结束事件。成功写 RESTORED，回退写 FALLBACK_TO_LIST，失败写明确阶段。只有开始没有结束，会让排查者误以为线程卡住，也无法统计未闭环迁移。一次可解释的失败通常比一次表面成功、内部留下隐藏路径更容易修复。

十三、参考资料与核对说明

• HarmonyOS 多设备自适应应用官方入口：https://developer.huawei.com/consumer/cn/multidevice/adaptive-apps/
• HarmonyOS Navigation 组件参考：https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-navigation
• HarmonyOS GridRow 组件参考：https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-gridrow
• HarmonyOS 平行视界社区主题（用于理解场景，具体接口以当前 SDK 文档为准）：https://developer.huawei.com/consumer/cn/forum/topic/0201221235973021541

本文不声称已在某一具体设备上完成测试。配图是与本篇字段一致的交互演示图，不是实际 DevEco Studio 或真机截图。