native-view

展示全部

# native-view

组件类型：UniNativeViewElement

自定义原生View组件

native-view自身没有渲染内容，开发者可以通过DOM API获取到native-view对应的原生view，然后提供平台原生view与native-view进行绑定，native-view将展示该view的渲染内容。

<native-view>组件是uni-app x下扩展原生组件（如map）的重要方式。事实上官方的map组件就是使用<native-view>开发的。详见下方的使用场景章节。

# 兼容性

Web	微信小程序	Android	iOS
x	x	4.31	4.31

# 属性

名称

类型

默认值

兼容性

描述

@init

(event: UniNativeViewInitEvent) => void

native-view初始化时回调，event.detail = { element: 'native-view元素实例对象'}

# 事件

# UniNativeViewInitEvent

native-view 组件 init事件event

# UniNativeViewInitEvent 的属性值

名称

类型

必填

默认值

兼容性

描述

detail

UniNativeViewInitEventDetail

是

名称	类型	必备	默认值	兼容性	描述
element	UniNativeViewElement	是	-	-	-

type

string

是

# UniNativeViewInitEventDetail

# UniNativeViewInitEventDetail 的属性值

名称	类型	必填	默认值	兼容性	描述
element	UniNativeViewElement	是	-	-	-

# 使用场景

native-view 适用于开发uts插件-标准模式组件

# 使用教程

# 获取 UniNativeViewElement

native-view提供 @init 监听元素初始化，通过事件UniNativeViewInitEvent的 detail.element 获取到 UniNativeViewElement。

# UniNativeViewElement绑定原生view

Android 平台：

UniNativeViewElement 提供bindAndroidView函数与native-view绑定android平台原生view

IOS 平台：

UniNativeViewElement 提供bindIOSView函数与native-view绑定ios平台原生view

# 分发自定义事件

UniNativeViewElement 提供了dispatchEvent分发event事件API，注意：事件数据类型暂时只支持UniNativeViewEvent。

具体示例请参考：native-button插件，该插件使用native-view封装原生button实现的native-button。

# 注意事项

app平台native-view组件绑定原生view后自动适配组件全局属性
app平台native-view组件不支持自定义属性，使用uts插件-标准模式组件-声明属性props实现自定义属性目的
app平台native-view组件不支持子组件
android平台native-view组件不支持list-item复用机制，list-item其他子组件不受影响正常启动复用业务。
android平台native-view组件不支持background、border、boxshadow属性
android平台native-view组件不支持overflow属性设置visible，仅支持hidden

# 子组件

不可以嵌套组件

# 示例

# native-view

展示使用 native-view 封装的原生view的UTS插件-标准模式组件

hello uni-app x

该 API 不支持 Web，请运行 hello uni-app x 到 App 平台体验

<template>
  <view>
    <text class="tips">说明：如果本地无 uts 插件编译环境请提交打包自定义基座查看效果</text>
    <!-- native-button 通过 native-view 绑定原生button 实现的UTS插件-标准模式组件 -->
    <native-button class="native-button" style="width: 200px; height: 100px;" :text="buttonText" @buttonTap="ontap"
      @load="onload"></native-button>
    <!-- native-time-picker 通过 native-view 绑定原生time-picker 实现的UTS插件-标准模式组件 -->
    <native-time-picker class="native-time-picker" :hour=2 :minute=3 @changed="onChanged"></native-time-picker>
  </view>
</template>

<script>
  export default {
    data() {
      return {
        title: 'Hello',
        buttonText: "native-button",
        isLoad: false,
        clickCount: 0
      }
    },
    onLoad() {

    },
    methods: {
      ontap(e : UniNativeViewEvent) {
        uni.showToast({
          title: "按钮被点击了"
        })
        this.clickCount ++
        this.buttonText = "native-button"+this.clickCount
      },
      onload() {
        //标记已初始化 用于自动化测试
        this.isLoad = true
      },
      onChanged(e : UniNativeViewEvent) {
        console.log("onchanged-----", e.detail)
      }
    }
  }
</script>

<style>

  .tips {
    font-size: 14px;
    color: #BEBEBE;
    margin: 25px auto 25px auto;
    text-align: center;
  }

  .native-button {
    height: 100px;
    width: 100px;
    margin: 25px auto 25px auto;
  }

  .native-time-picker {
    margin: 10px auto 25px auto;
    border-style: solid;
    border-radius: 5px;
  }
</style>

# native-button

通过 native-view 绑定原生 button 实现的UTS插件-标准模式组件

hello uni-app x

该 API 不支持 Web，请运行 hello uni-app x 到 App 平台体验

<template>
	<native-view @init="onviewinit" @customClick="ontap"></native-view>
</template>
<script setup lang="uts">
	import { NativeButton } from "@/uni_modules/native-button";
	let button : NativeButton | null = null

	//声明属性
	const props = defineProps<{ text : string }>()

	//声明事件
	const emit = defineEmits<{
		(e : "load") : void
		(e : "buttonTap", event : UniNativeViewEvent) : void
	}>()

	//声明方法
	function updateText(value : string) {
		button?.updateText(value)
	}

	//监听属性变化
	watchEffect(() => {
		const text = props.text
		updateText(text)
	})

	//native-view初始化时触发此方法
	function onviewinit(e : UniNativeViewInitEvent) {
		//获取UniNativeViewElement 传递给NativeButton对象
		button = new NativeButton(e.detail.element);
		updateText(props.text)
		emit("load")
	}

	function ontap(e : UniNativeViewEvent) {
		emit("buttonTap", e)
	}

	function onUnmounted() {
		// iOS平台需要主动释放 uts 实例
		button?.destroy()
	}
</script>

NativeButton原生对象代码如下：

Android

iOS

import { Button } from "android.widget"

export class NativeButton {
	$element: UniNativeViewElement;

	constructor(element: UniNativeViewElement) {
		this.$element = element;
		this.bindView();
	}

	button: Button | null = null;
	bindView() {
		//通过UniElement.getAndroidActivity()获取android平台activity 用于创建view的上下文
		this.button = new Button(this.$element.getAndroidActivity()!);  //构建原生view
		//限制原生Button 文案描述不自动大写
		this.button?.setAllCaps(false)
		//监听原生Button点击事件
		this.button?.setOnClickListener(_ => {
			const detail = {}
			//构建自定义UniNativeViewEvent返回对象
			const event = new UniNativeViewEvent("customClick", detail)
			//响应分发原生Button的点击事件
			this.$element.dispatchEvent(event)
		})
		//UniNativeViewEvent 绑定 安卓原生view
		this.$element.bindAndroidView(this.button!);
	}

	updateText(text: string) {
		//更新原生Button 文案描述
		this.button?.setText(text)
	}

	destroy() {
		//数据回收
	}
}