uni-app x鸿蒙native-view原生组件绑定实战

鸿蒙专家

在 uni-app x 中，内置组件通常够用，但当需要接入鸿蒙原生 UI，例如 XComponent、Web 组件，或封装原生地图、视频播放器、图表库时，就需要 native-view。它本身不渲染内容，而是原生 View 的占位符，通过 UTS 插件把平台原生 View 绑定进来。官方 map 组件就是用 native-view 开发的。HarmonyOS 从 4.61 开始支持该组件，Web 和微信小程序不支持。

一、native-view 的定位与兼容性

native-view 是 uni-app x 与原生 UI 之间的桥梁。Android 可绑定 WebView、MapView，iOS 可绑定 WKWebView、MKMapView，鸿蒙可绑定 XComponent、Web 组件等。它只有一个 @init 事件，通过该事件获取 UniNativeViewElement，再绑定原生 View。

兼容性上，只支持 App 平台，即 Android、iOS、鸿蒙；不支持 Web 和微信小程序。native-view 自身没有渲染内容，不支持自定义属性，也不支持子组件。需要自定义属性时，应通过 UTS 插件标准模式组件的 defineProps 来实现。

二、使用流程

在页面放置 native-view，监听 @init 事件，获取 UniNativeViewElement；在 UTS 插件中创建原生 View；调用对应平台的绑定方法，把原生 View 绑定到 native-view。Android 使用 bindAndroidView，iOS 使用 bindIOSView，鸿蒙使用 bindHarmonyWrappedBuilder 或 bindHarmonyFrameNode。

鸿蒙平台绑定示例：

2. // 使用 WrappedBuilder 绑定
3. element.bindHarmonyWrappedBuilder(builder)

复制代码

2. // 使用 FrameNode 绑定
3. element.bindHarmonyFrameNode(node)

复制代码

鸿蒙平台的原生代码需要用 ArkTS 编写，并熟悉 WrappedBuilder 或 FrameNode 的用法。建议参考官方示例代码。

三、实战：封装鸿蒙原生按钮

下面以封装原生按钮为例，说明 native-view 在鸿蒙平台的接入方式。组件模板放置 native-view，并通过 @init 获取 element。UTS 插件目录可按以下结构组织：uni_modules/native-button/components/native-button/native-button.uvue，以及 utssdk/app-android/index.uts、utssdk/app-ios/index.uts、utssdk/app-harmony/index.uts。

鸿蒙侧 utssdk/app-harmony/index.uts 中，NativeButton 类接收 UniNativeViewElement，在构造函数里调用 bindView，再通过 this.element.bindHarmonyWrappedBuilder(builder) 绑定鸿蒙原生 UI。updateText 方法用于后续更新文本。

组件模板中，native-view 的 @init 事件用于创建 NativeButton 实例，并把 props.text 传入。可以在 watchEffect 中监听 text 变化，再调用 updateText 更新原生按钮文本。如果需要把原生事件透传给页面，可以在组件中声明 emit，例如 load 和 buttonTap，并让 @customClick 触发 onTap 后 emit(buttonTap, event)。页面使用时，通过 native-button 传入 text，监听 buttonTap 和 load，再用按钮修改文本触发原生按钮更新。

页面侧可这样组织逻辑：btnText 是响应式文本，onTap 调用 uni.showToast 提示原生按钮被点击，onLoad 打印原生按钮加载完成，changeText 修改 btnText，从而让 watchEffect 或属性更新逻辑把新文本同步到原生按钮。

四、鸿蒙平台注意事项与踩坑

1. 版本支持：HarmonyOS 4.61 版本开始支持 native-view 组件。
2. 绑定方式不同：鸿蒙使用 bindHarmonyWrappedBuilder 或 bindHarmonyFrameNode，Android 使用 bindAndroidView，iOS 使用 bindIOSView。
3. 原生代码语言：鸿蒙平台原生代码需要使用 ArkTS 编写，需要熟悉 WrappedBuilder 或 FrameNode 的用法。
4. 平台限制：native-view 不支持 Web 和微信小程序，只支持 App 平台。
5. 自定义属性：native-view 本身不支持自定义属性，需要通过 UTS 插件标准模式组件的 defineProps 实现。
6. 子组件限制：native-view 不能嵌套子组件。
7. iOS 释放：iOS 平台需要在 onUnmounted 中调用 destroy() 释放 UTS 实例，否则可能内存泄漏。
8. Android list-item 复用：Android 平台 native-view 不支持 list-item 复用机制，放在 list-item 中会影响复用性能。
9. Android 样式限制：Android 平台 native-view 不支持 background、border、boxshadow 属性；不支持 overflow: visible，仅支持 hidden。
10. 根节点建议：组件模板中建议 native-view 只存在一个根节点；如果存在兄弟节点，需要将其包裹处理。

五、什么时候用 native-view

简单判断：官方有现成组件就用现成的，没有的才考虑 native-view。native-view 是 uni-app x 中嵌入原生 UI 的终极方案，适用于集成原生 SDK，例如广告、支付、图表等。大多数开发者可能用不到，但一旦需要嵌入鸿蒙原生 UI，它就是必经之路。

总结关键点：native-view 本身没有渲染内容，是原生 View 的占位符；通过 @init 获取 UniNativeViewElement；Android 用 bindAndroidView，iOS 用 bindIOSView；鸿蒙用 bindHarmonyWrappedBuilder 或 bindHarmonyFrameNode；不支持 Web 和微信小程序；不支持自定义属性和子组件；iOS 需要手动 destroy；Android 有样式限制；鸿蒙 4.61 开始支持。