@arkui-x.platformview(平台视图)

本模块是ArkUI-X框架提供的平台视图接口,其核心机制在于实现原生视图与ArkUI组件的混合渲染。
通过直接嵌入原生平台(Android、iOS)的UI组件,开发者能够在跨平台应用中复用现有原生平台的功能与视图,提升跨平台开发效率。

说明:

平台视图渲染模式分为:

  1. Surface 模式

    ArkUI-X将原生视图作为一个独立的图层(Surface)直接叠加在自身组件树之上,在相应区域为原生组件"开洞",使得下方的原生视图得以直接显示。这提供了近乎原生的渲染性能。

    渲染路径最短,接近纯原生性能,尤其适用于视频播放、地图、相机预览等对帧率要求极高的场景。

    平台约束:由于是独立的图层,在深度嵌套的可滚动组件(如 ListScroll)中使用时,可能出现触摸事件“不跟手”与ArkUI-X组件动画/滚动不同步,以及设备旋转时布局可能不同步的问题。因此,不建议在复杂的嵌套滚动容器中使用此模式

  2. Texture 模式

    原生视图被渲染到一个纹理(Texture)中,随后该纹理作为一张普通的"图片"被集成到ArkUI-X的组件树中进行合成与渲染。原生视图在渲染层面上与ArkUI-X组件成为一体。

    由于已成为UI树的一部分,因此能够完美跟随ArkUI-X的布局、动画、滚动和旋转,无同步问题。

    相比Surface模式,需要额外的纹理复制和合成步骤,会带来一定的性能开销,在极端复杂的UI或高频更新的场景中可能影响流畅度,适用于静态视图对帧率、性能要求不高的场景。

    平台约束:因iOS平台能力限制,不支持WKWebView中有内嵌视频的场景,推荐使用Surface模式

平台视图渲染模式默认为:Texture模式。

ArkTS 侧在构造平台视图时,无法向原生侧传递参数。解决方案请参考:ArkUI-X 解决平台视图从 ArkTS 侧向原生侧传值

导入模块

import PlatformView, { PlatformViewAttribute, PlatformViewType } from '@arkui-x.platformview';

PlatformViewType

此枚举定义了平台视图的渲染模式。

系统能力: SystemCapability.ArkUI.ArkUI.Full

支持平台: Android、iOS

名称 说明
TEXTURE_TYPE 0 Surface 模式
SURFACE_TYPE 1 Texture 模式

PlatformView

PlatformView(value: {id: string, data?: string, type?: PlatformViewType})

用于在ArkUI中创建并嵌入原生平台视图(Android或iOS原生组件)的接口组件,通过指定唯一标识、渲染模式和初始化数据,实现高性能或高兼容性的混合渲染。

系统能力: SystemCapability.ArkUI.ArkUI.Full

支持平台: Android、iOS

参数:

参数名 类型 必填 说明
id string 视图的唯一标识符。
在同一应用中,每个PlatformView实例的ID应保持唯一,用于在视图树中正确识别和管理该实例。
type PlatformViewType 指定视图的渲染模式,这直接影响性能和表现。包括Surface模式和Texture模式。
默认模式为:Texture 模式。
data string 传递给原生视图的初始化数据。

返回值:

类型 描述
PlatformViewAttribute 返回一个平台视图属性配置对象。

示例:

PlatformView({id:'MapView', data:'text', type:PlatformViewType.SURFACE_TYPE})
  .width('90%')
  .height('90%')

开发指南

Android平台视图开发指南

iOS平台视图开发指南