How WYNavigation Unifies RN and Native Navigation Stacks for Seamless Hybrid Apps

WYNavigation

Main Concepts

We adopt a single‑engine, multiple‑container model. The existing RN code is split into a common package and several business packages. Each native page navigates via a RouteUrl, similar to a browser address. The common package shares one RN engine, and RouteUrl allows navigation without caring whether the target is native or RN.

Navigation.registerComponent("Test", () => TestScreen)

When the native app starts, the common package is pre‑loaded. To open an RN page, the native side creates an RN container, loads the corresponding business package based on the PageName, and passes the PageName to RN. RN then renders the matching page, and the container initializes the native navigation bar using static variables from the RN page. Because each RN container hosts exactly one RN page, the RN page becomes a native page, integrating RN navigation into the native stack.

Understanding Components, Screens, and Containers

Three concepts are defined:

Component : an independent functional unit in RN; a screen consists of multiple components.

Screen : a UI page, including navigation bar and content.

RNContainer : a native container that hosts an RN page.

Our solution maps multiple components → one screen → one container → one native page, so RN push/pop operations are handled by the native container, making RN navigation indistinguishable from native navigation.

Routing and Navigation

Native → RN

Pass a pageName parameter (and optional param) to the RN container.

// Native to RN
NSDictionary *params = @{ "pageName": @"MyPost", "param": param };
[WYMediator routeURL:WYURL(@"xxx/rncontainer") withParams:params];

// Android example
ExtParams param = new ExtParams();
param.putStringExtra("PageName", "MyPost");
param.putStringExtra("PageParam", pageParams);
Router.startRoute(activity, "xxx/rncontainer", param);

RN → Native

Use Navigation.push with the native route name and passProps. A callback can be supplied to handle data when the native page is closed.

Navigation.push(this.props.componentId, {
    name: "xxxx",
    passProps: { patientId: '11111', patientName: '张三' }
}, (componentId, params) => {
    // callback after native page returns
});

RN → RN

Push another RN screen by specifying the registered component name.

Navigation.registerComponent("Test", () => TestScreen);

RN Page Pop

Close the current RN page with Navigation.pop, optionally passing data back via passProps.

Navigation.pop(this.props.componentId, passProps: {});

Container Lifecycle

In addition to the standard RN component lifecycle, the container provides its own lifecycle callbacks:

containerWillAppear – container is about to appear

containerDidAppear – container is now visible

containerWillDisappear – container is about to disappear

containerDidDisappear – container has been hidden

These callbacks are useful for data refresh when the container becomes visible again.

Navigation Bar Configuration

The navigation bar follows the same tree‑style configuration as react‑native‑navigation. Define static options in the screen component and the native side renders the bar accordingly.

class MyScreen extends Component {
  static options(passProps) {
    return {
      topBar: {
        title: { text: 'My Page' },
        leftButtons: [{ id: 'buttonOne', icon: require('icon.png') }],
        rightButtons: []
      }
    };
  }
}

When the RN page loads, the framework retrieves the component by its PageName, reads the static options, and generates the native navigation bar, eliminating the need for extra bridge code.

Conclusion and Open Issues

WYNavigation is already used in the WeDoctor project and has effectively solved navigation stack chaos in complex hybrid scenarios. However, it has only been tested with simple page types; handling multiple RN pages at the same level (e.g., tabs, modals) remains future work. The team invites interested developers to collaborate and extend the solution.