Taro中使用原生组件、页面和插件的完整指南

Question

Taro 使用原生模块

Taro 框架支持使用小程序原生的页面、组件和插件。但需要注意的是，一旦在 Taro 项目中引用了原生模块，该项目将失去多端转换的能力。例如，使用微信小程序原生组件后，项目只能转换为微信小程序，无法适配其他平台。

示例项目可供参考：

React 版本：https://github.com/NervJS/taro-sample-weapp/tree/next
Vue 版本：https://github.com/NervJS/taro-sample-weapp/tree/vue

使用原生组件

使用方法

1. 在 app 或页面配置文件中配置 `usingComponents` 属性

在页面配置文件（如 page.config.js）中定义需要引入的第三方组件：

export default {
  usingComponents: {
    'ec-canvas': '../../components/ec-canvas/ec-canvas',
  },
}

注意：Taro3 的组件没有配置文件，因此 usingComponents 必须配置在页面的配置文件中。

2. 使用组件

在 React 中，可以这样使用原生组件：

import React, { Component } from 'react'
import { View } from '@tarojs/components'

export default class Index extends Component {
  state = {
    ec: {
      onInit: function () {}
    }
  }

  render() {
    return (
      
        
      
    )
  }
}

Vue 的用法类似，使用相应的模板语法。

属性绑定

属性名与原生语法保持一致。例如，在 React 中：


  Button

注意：在 Vue 中，如果组件的某些属性默认值为 true，在 Taro 中仍需显式设置为 true。

事件绑定

原生组件派发的事件名称格式多样，影响 React 和 Vue 的绑定语法。以下是一些规则：

对于事件名如 myevent，React 使用 onMyevent，Vue 使用 @myevent。
对于大小写敏感的事件名，如 myEvent，需要在 React 中使用 bind 属性 hack 处理，例如。
对于带连字符的事件名，如 my-event，Vue 中直接使用 @my-event，React 中对应 onMyEvent 生成 bind:my-event。

例如：

// 对应 bind:click 事件
Button
// 对应 bind:after-read 事件

使用 Slot

在 React 中，使用组件实现插槽；在 Vue 中，使用组件。

React 示例：

import React, { Component } from 'react'
import { View, Slot } from '@tarojs/components'

export default class Index extends Component {
  render() {
    return (
      
        
          
            Hello world
          
        
      
    )
  }
}

selectComponent

可以使用小程序页面实例的 selectComponent API 获取第三方原生组件的实例：

import { getCurrentInstance } from '@tarojs/taro'

const { page } = getCurrentInstance()
page.selectComponent('#mychart-dom-area')

使用 vant-weapp

关于使用 vant-weapp 的详细文档，请参考官方文档。

常见问题

1. Vue3 出现警告 "Failed to resolve component"

在 Vue3 中，使用原生组件时可能出现此警告，原因是 Vue 将其误解析为 Vue 组件。解决方案是修改 VueLoader 的编译配置 compilerOptions.isCustomElement，将该组件声明为原生组件。

Taro v3.4 之前：通过 WebpackChain 修改配置。
Taro v3.4 之后：通过配置 Taro Vue3 插件的选项修改。
此外，传递函数类型的属性可能失败，需参考相关 issue 中的写法。

使用原生页面

只需在 app 配置中设置原生页面的路由。例如，在 app.config.js 中：

export default {
  pages: ['pages/native/native'],
}

使用小程序插件

引入插件

在 app.config.js 中声明需要使用的插件：

export default {
  plugins: {
    myPlugin: {
      version: '1.0.0',
      provider: 'wxidxxxxxxxxxxxxxxxx',
    },
  },
}

使用插件组件

配置使用

在页面配置文件中定义插件组件：

export default {
  usingComponents: {
    'hello-component': 'plugin://myPlugin/hello-component',
  },
}

组件写法

与使用原生组件一致，参考前述部分。

限制

出于保护，插件自定义组件有一些限制：

页面中的 this.$scope.selectComponent 可能无法获取插件组件实例。
Taro.createSelectorQuery 的 >>> 选择器无法选入插件内部。

使用插件页面

跳转到插件页面时，url 使用 plugin:// 前缀，例如：

Go to pages/hello-page!

使用 js 接口

使用 Taro.requirePlugin 调用插件的 js 接口：

import { requirePlugin } from '@tarojs/taro'

const myPluginInterface = requirePlugin('myPlugin')
const myWorld = myPluginInterface.world
myPluginInterface.hello()