mapview-demo

Reference implementation of a plugin-authored native-view kind. Read this alongside §17 of the plugin authoring guide for the walkthrough that produced these files.

What's here

examples/mapview-demo/
├── package.json                 # ump.native multi-language entries
├── src/index.ts                 # MapView component (createNativeViewComponent)
├── native/
│   ├── mapview_register.cpp     # Kind spec — static init at process start
│   ├── android/
│   │   ├── MapViewHost.java     # Per-instance UMPNativeViewHost
│   │   └── MapViewHostFactory.java
│   ├── ios/
│   │   └── UMPMapViewHost.m     # UMPNativeViewHostInstance + factory
│   └── harmony/
│       └── MapViewHost.ets      # @Observed state + @Builder build()
├── App.tsx                      # demo consumer
└── index.tsx                    # AppRegistry.runApplication entry

What the hosts actually do

Each host renders a coloured placeholder view (light blue rectangle). Replace with your real map SDK at the points the inline comments call out:

• Android: instantiate YourMapSDKView, add it to the FrameLayout, forward props through it.
• iOS: instantiate MKMapView (or your SDK's view), constrain it to the wrapper UIView's bounds, forward props.
• Harmony: replace the empty Stack() body in @Builder build() with your map ArkUI element.

Wiring

This demo lives under examples/ so reading it is friction-free, but npx ump autolink discovers plugins under packages/ump-plugins/<name> and installed node_modules/<name> only — it does NOT scan examples/. To actually run the demo against a host build, copy or symlink examples/mapview-demo/ into packages/ump-plugins/mapview/ and re-run autolink.

1. Re-run npx ump autolink to pick up package.json's ump.native entries. The CLI emits the per-platform manifests:

   • Android cpp -> CMakeLists.gen.cmake
   • Android java -> app/build.gen.gradle (sets srcDirs)
   • iOS cpp -> UMPPlugins.filelist
   • iOS objc -> UMPPluginsObjC.filelist
   • Harmony cpp -> CMakeLists.gen.cmake
   • Harmony ets -> imports.gen.ets (side-effect imports)

2. Android only: in UMPActivity.onCreate, after UMPNativeViewRegistry.attach(below, above), register the factory:

   UMPNativeViewRegistry.register("MapView", new com.example.mapview.MapViewHostFactory());

3. iOS only: in UMPViewController.viewDidLoad, after the wireNativeViewRegistryWithBelow:above: call:

   [UMPNativeViewRegistry registerKind:@"MapView"
                               factory:[[UMPMapViewHostFactory alloc] init]];

4. Harmony only: nothing extra. The side-effect register call at the bottom of MapViewHost.ets runs when imports.gen.ets (generated by autolink) imports the file at module load. Make sure EntryAbility.onCreate calls umpInstallPlugins() before bundle eval — see chapter §17.3 of the guide for that one-time wiring.

V1 limitations

See guide §17.7. The two limitations most likely to surprise plugin authors:

• No event channel for plugin authors yet. The hosts in this example have TODO(events) markers where event firing would go through dispatch_native_view_event_from_ui. That C++ surface exists; the platform-specific JNI / NAPI / C-extern bridge for plugins is reconnected in a follow-up. Built-in Video uses UMPNativeViewRegistry.fireIntrinsicSize as the only event today.

• Sync methods are gated. Methods that block the JS thread must be in spec.sync_methods. MapView declares sync_methods = {} so any sync handle method would silently downgrade to fire-and-forget; add the method name there if you want the blocking behaviour. Read guide §17.6 first — the bar is high.