---
title: native-component - 原生组件
---

## native-component

#### 小程序中的部分组件是基于异层渲染的，由客户端创建的原生组件。

### 原生组件

小程序中基于异层渲染的原生组件，这些组件有：

- [map](/cn/miniapp/develop/miniapp/component/map/map)
- [ipc-player](/cn/miniapp/develop/miniapp/component/media-component/ipc-player)
- [camera](/cn/miniapp/develop/miniapp/component/media-component/camera)
- [native-video](/cn/miniapp/develop/miniapp/component/media-component/native-video)
- [web-view](/cn/miniapp/develop/miniapp/component/open/web-view)

### 注意事项

原生组件在开发使用时最好通过真机调试来查看，因为 Tuya MiniApp IDE 中是通过 WebView 来模拟的原生组件，所以与真机的原生组件会有些差异，因此，开发者需要在真机上查看下功能样式，确保上线后运行效果正确。

### 原生组件异层渲染

异层渲染是为了解决 WebView 中一些复杂组件（如地图, 视频）的渲染性能比较差的问题。异层渲染是在 WebView 层之下再渲染一层 Native 层，通过配合通信来达到目的。

<Image src="/images/component/render.png"/>

在上层的 WebView 层我们会空出一个区域让视觉穿透到下面的 Native 层，另外如果是覆盖在上面的元素，我们通过计算来获取到热区的占位区域。然后是经过计算来分发事件。

<Image src="/images/component/bridge.png"/>

#### 原生组件的使用限制

由于异层渲染模式下，页面分为上下两层，上层是 WebView 层渲染 WebView 组件节点及其子节点，下层是 Native 层渲染原生组件，因此在使用时有以下限制：

1. 基于异层渲染的原生组件及其父节点不能设置背景色、背景图等, 如果设置则会导致底层原生视图被遮挡。
2. 如果需要设置背景色和边框，请通过 `background-color` 和 `border` 相关属性进行设置，请参考下图以 `<map/>` 组件为例进行样式设置。因为原生组件区域是由 Natvie 层原生渲染的，所以背景色和边框样式需要传给 Native 层由原生来处理渲染。原生组件可设置的样式属性如下:

| 属性名                     | 类型   | 默认值  | 必填 | 说明                                |
| -------------------------- | ------ | ------- | ---- | ----------------------------------- |
| border-width               | number | 0       | 否   | 边框的宽度, 单位 px                 |
| border-style               | string | solid   | 否   | 边框的样式, 可选值: solid 和 dashed |
| border-color               | string | #ffffff | 否   | 边框的颜色, 必须为十六进制格式      |
| border-radius              | number | 0       | 否   | 边框的圆角, 单位 px                 |
| border-radius-top-left     | number |         | 否   | 边框的左上角圆角大小, 单位 px       |
| border-radius-top-right    | number |         | 否   | 边框的右上角圆角大小, 单位 px       |
| border-radius-bottom-left  | number |         | 否   | 边框的左下角圆角大小, 单位 px       |
| border-radius-bottom-right | number |         | 否   | 边框的右下角圆角大小, 单位 px       |
| background-color           | string | #ffffff | 否   | 背景颜色, 必须为十六进制格式        |

3. 需要覆盖在地图上的节点必须作为原生组件的子节点，弹窗类型除外。因为只有原生组件的子节点会作为异层渲染的热区，热区内的手势事件由 WebView 层接管，原生组件标签内除热区外的其它区域手势事件都由 Native 层处理，原生组件标签外的节点不会作为热区，这样覆盖到原生组件上的 WebView 手势就会失效。
4. 需要覆盖在地图上并且需要监听手势事件的弹窗，在显示时需要调用 [ty.nativeDisabled(true)](/cn/miniapp/develop/miniapp/api/other/nativeDisabled) 使地图不接管手势事件，在收起时需要调用 [ty.nativeDisabled(false)](/cn/miniapp/develop/miniapp/api/other/nativeDisabled) 使地图继续接管手势事件。因为弹窗是在显示和隐藏之间切换，调用手势接管 API 来控制，这样会减少对弹窗热区的监听，性能比作为原生组件子节点热区会好。
5. 需要修改布局样式或者是通过 ty:if 切换显示隐藏时，需要把变化的属性加在原生组件本身才能生效，因为原生组件只有在自身组件上的属性发生变化才会发送消息到 Native 层，触发 Native 层视图同步变化。
6. 不能将原生组件放在局部滚动区域中，外层不能嵌套如 `scroll-view`、`swiper`等可滚动的组件。因为 Native 层无法监听到局部滚动事件，无法实时更新组件视图位置。

<Image src="/images/component/map.png"/>

### cover-view

为了解决覆盖在原生组件之上的其它组件手势被原生拦截的限制。小程序专门提供了 [cover-view](/cn/miniapp/develop/miniapp/component/view-container/cover-view) 组件，可以覆盖在部分原生组件上面。