HarmonyOS Web Component Window Migration: 3 Steps for Seamless Multi-Window UX

Core Concept: What Is Web Component Window Migration?

As large-screen devices and multi-window scenarios become common, app interactions are shifting from single-window to flexible multi-window experiences. In browser-like apps, users may want to drag a tab out into an independent window or drag it back into the tab strip. Recreating the Web page on every window switch adds complexity and breaks continuity.

HarmonyOS Web component supports mounting and unmounting between different window component trees. Developers can migrate the same Web component across windows, achieving a browser-tab drag-and-drop experience.

The core idea is not to recreate the page but to change the Web component's position in the UI component tree. The basic flow: create a Web component via BuilderNode as an offline node, use a custom placeholder node to control when the Web node mounts or unmounts. When the node is removed from window A's component tree and mounted to window B's tree, migration completes. The only change is the mounting relationship between the Web component and window component trees.

Three-Step Implementation

Step 1: Create a Dynamically Mountable Web Component

To enable window migration, the Web component must be detachable from a fixed page for dynamic management. In the official example, after the main window Ability starts and loadContent finishes, the current window's UIContext is obtained and a Web dynamic component is created imperatively.

Implementation requires creating both a WebviewController (for Web component control) and a BuilderNode (for building the dynamic component node). Developers can store the BuilderNode and WebviewController in a Map for later retrieval and management across pages or windows.

Step 2: Control Mount and Unmount with NodeController

After component creation, the key is controlling when it appears in a window. By inheriting NodeController and using FrameNode to hold the current Web node, developers can implement custom mount logic. When showing the Web component, get the BuilderNode 's FrameNode and mount it; when removing, unmount the corresponding node.

The official example encapsulates attachWeb() and detachWeb() methods for mounting and unmounting. This avoids redefining a full Web page for each window; instead, the same Web node's mount position is controlled.

Step 3: Host the Web Node with NodeContainer

With a dynamically controllable Web node, a placeholder in the page is needed. HarmonyOS provides NodeContainer to work with NodeController. The page binds a NodeController to a NodeContainer and calls rebuild() to refresh the node, deciding whether the Web component displays in the current page.

For a "drag out window" operation, the developer removes the Web component from the original window's NodeContainer and mounts the same node to the new window's NodeContainer. The reverse operation follows the same logic. Thus, window migration shifts from complex page recreation to clear dynamic node migration.

Critical Detail: A Web Component Cannot Be Cloned

A crucial principle: never mount the same Web component to two parent nodes simultaneously. Before mounting, check whether the FrameNode already has a parent. If the Web component is already mounted in one window's component tree, it must be removed first before mounting to another window.

Mounting the same component to different parents can cause unexpected behavior. The official example adds a parent-node check in attachWeb(). Therefore, the migration flow must follow a simple rule: remove first, then attach . This ensures correct migration across windows.

From Page Switching to Component Migration: Flexible Multi-Window Experience

With multi-window usage growing on PCs, tablets, and large screens, developers must consider how content flows between windows, not just how a page displays in one window. HarmonyOS decouples the Web component from fixed page structures using custom nodes, BuilderNode, NodeController, and NodeContainer. By controlling node mounting relationships, the same Web component can migrate across windows, providing a flexible implementation for browsers, multi-window productivity, and complex Web apps.

Developers adapting to multi-window interactions should master three key points:

Create dynamic Web nodes via BuilderNode.

Control node mount and unmount via NodeController.

Host the node in the page via NodeContainer.

Understanding this logic makes Web component window migration implementation clearer. For detailed example code, refer to the HarmonyOS developer documentation:

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

.