Web 页面也能在窗口间“自由移动”？一文看懂 HarmonyOS Web 组件窗口迁移

在大屏设备和多窗口场景逐渐普及的今天，应用交互也正在从“单窗口”向更加灵活的多窗口体验延伸。

比如在浏览器类应用中，用户可能希望直接将一个正在浏览的 Tab 页拖出，变成独立窗口；也可能希望把独立窗口中的页面重新拖回浏览器，与其他 Tab 页放在一起。如果每次窗口切换都重新创建 Web 页面，不仅实现起来更加复杂，也难以满足连续、自然的多窗口交互需求。

HarmonyOS Web 组件支持在不同窗口的组件树之间进行挂载和移除。开发者可以让同一个 Web 组件在不同窗口间迁移，实现类似浏览器 Tab 页拖出、拖入的多窗口交互体验。

为了帮助开发者快速实现 HarmonyOS Web 组件的窗口迁移，HarmonyOS 开发者官网上线了《 Web 组件在不同的窗口间迁移》最佳实践，只需三步就能让 Web 页面在窗口间“自由移动”，打造连续、自然的多窗口交互体验。

一、Web 组件窗口迁移，核心是什么？

简单来说，Web 组件窗口迁移并不是重新创建一个网页，而是改变已有 Web 组件在 UI 组件树中的“位置”。

其基本思路是：首先通过 BuilderNode 创建 Web 组件的离线节点，再利用自定义占位节点控制这个 Web 节点何时挂载、何时移除。当 Web 节点从窗口 A 对应的组件树中移除，再挂载到窗口 B 的组件树中，就完成了一次窗口迁移。

可以把整个过程理解为：创建一个 Web 组件 → 在窗口 A 挂载 → 从窗口 A 移除 → 在窗口 B 重新挂载。整个迁移过程中，真正发生变化的是 Web 组件与窗口组件树之间的挂载关系。

第一步：先创建一个可以动态挂载的 Web 组件

要实现窗口迁移，首先需要让 Web 组件能够脱离固定页面进行动态管理。

在 HarmonyOS 官方示例中，主窗口 Ability 启动后，会在 loadContent 完成之后获取当前窗口的 UIContext，并通过命令式方式创建 Web 动态组件。

具体实现时，需要分别创建 WebviewController 和 BuilderNode。其中，WebviewController 负责 Web 组件相关控制能力，而 BuilderNode 则负责构建动态组件节点。

开发者还可以通过 Map 等方式保存对应的 BuilderNode 和 WebviewController，方便后续在不同页面或窗口中获取和管理对应 Web 组件。

第二步：通过 NodeController 控制“挂上去”和“拿下来”

组件创建完成后，接下来最关键的就是控制它什么时候出现在窗口中。

这里可以通过继承 NodeController 实现自定义节点控制逻辑，并借助 FrameNode 保存当前需要挂载的 Web 节点。

当需要显示 Web 组件时，可以获取 BuilderNode 对应的 FrameNode，将其作为当前节点进行挂载；当需要从当前窗口移除 Web 组件时，则取消对应节点的挂载。

官方示例分别封装了 attachWeb() 和 detachWeb() 方法，用来完成 Web 组件的挂载和移除。

也就是说，开发者不需要围绕每一个窗口重新定义完整 Web 页面，而是可以围绕同一个 Web 节点控制其挂载位置。

第三步：利用 NodeContainer 承载 Web 节点

有了可动态控制的 Web 节点之后，还需要在页面中为它准备一个“位置”。

HarmonyOS 提供的 NodeContainer 可以与 NodeController 配合使用。页面通过 NodeContainer 绑定对应的 NodeController，再通过 rebuild() 触发节点刷新，最终决定 Web 组件是否显示在当前页面中。

例如，当用户执行“拖出窗口”操作时，开发者可以先将 Web 组件从原窗口对应的 NodeContainer 中移除，再将同一个节点挂载到新窗口对应的 NodeContainer。

反过来，当用户需要将独立窗口中的页面重新放回原窗口时，也可以按照相同逻辑重新调整节点挂载关系。

这样一来，窗口迁移就可以从复杂的“页面重新创建”，转化为更加清晰的“节点动态迁移”。

二、一个细节尤其需要注意：同一个 Web 组件不能“分身”

在实现窗口迁移时，还有一个非常重要的原则：不要将同一个 Web 组件同时挂载到两个父节点下。

在节点挂载之前，开发者需要判断当前 FrameNode 是否已经存在父节点。如果 Web 组件已经挂载在一个窗口的组件树中，就应该先完成移除，再挂载到另一个窗口。

如果同一个 Web 组件同时被挂载到不同父节点，可能产生非预期行为。官方示例也专门在 attachWeb() 过程中增加了节点父级检查。

因此，在设计完整的窗口迁移流程时，可以遵循一个简单原则：先移除，再挂载。这也是保证 Web 组件在不同窗口之间正确迁移的关键。

三、从“页面切换”到“组件迁移”，多窗口体验更灵活

随着 PC、平板以及大屏设备上的多窗口使用场景不断丰富，开发者需要考虑的不再只是一个页面如何在一个窗口中展示，也包括内容如何在不同窗口之间灵活流转。

HarmonyOS 通过自定义节点、BuilderNode、NodeController 和NodeContainer 等能力，将 Web 组件从固定页面结构中解耦出来。开发者可以通过控制节点挂载关系，实现同一个 Web 组件在不同窗口之间迁移，为浏览器、多窗口办公以及复杂 Web 应用等场景提供更灵活的实现方式。

对于需要适配多窗口交互的开发者而言，可以重点掌握三个关键点：

通过 BuilderNode 创建动态 Web 节点；

通过 NodeController 控制节点挂载和移除；

再通过 NodeContainer 完成页面承载。

理解这套逻辑之后，Web 组件窗口迁移的实现思路也就变得更加清晰。

链接开发者可访问“HarmonyOS 开发者官网”，首页点击“开发”>>“开发文档”，在左侧目录栏找到“开发”，然后依次点击“应用框架”>>“ArkWeb（方舟 Web）”>>“管理网页加载与浏览记录”>>“Web 组件在不同的窗口间迁移”，查看更详细的示例代码。

??查看更详细示例代码：（可复制链接至网页跳转）

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/web-component-migrate

关注公众号，获取更多 HarmonyOS 技术内容

【扫码加入 ArkWeb 技术交流群】

HarmonyOS Web 开发指南：如何使用 DevTools 高效调试前端页面？

只需五步！快速定位应用网页加载问题 | HarmonyOS 官网上线实操指南

打造流畅 Web 体验：ArkWeb 页面加载、交互响应与帧率优化全解析

鸿蒙应用开发中的 Web 页面帧率异常分析与实战优化

点击下方??【】，一步直达“Web 组件在不同的窗口间迁移”的代码示例