title: 原生项目使用 Taro

:::info Taro v3.0.25 开始支持 :::

基础混合用法

示例项目

blended-basic

用法

1. 开发环境

1.1 推荐在 Taro 项目中进行开发调试，在生产环境下再把产物移动到原生小程序中进行预览。

  1. # 和编译普通 Taro 项目一样
  2. $ taro build --type [platform] --watch

1.2 小程序开发者工具导入 Taro 项目进行预览。

2. 生产环境

1.1 编译项目时使用 --blended 参数以输出混合模式的代码。

  1. # 以混合模式进行打包
  2. $ taro build --type [platform] --blended

1.2 移动 Taro 项目的输出目录到原生项目内

也可以编写一个 Taro 插件自动移动，可以参考 plugin-mv。

1.3 原生项目的 app.js 中引用 Taro 入口文件

```js title=”app.config.js” {2,7,12} // 必须引用 Taro 项目的入口文件 const taroApp = require(‘./taro/app.js’).taroApp

App({ onShow () { // 可选，调用 Taro 项目 app 的 onShow 生命周期 taroApp.onShow() },

onHide () { // 可选，调用 Taro 项目 app 的 onHide 生命周期 taroApp.onHide() } })

  2. ### Taro 项目引用原生项目的 JS 文件
  4. 有时我们需要在 Taro 项目中引用原生项目中的公共 JS 模块（如上报 sdk）。但是 Webpack 会把这些公共模块一并打包，导致公共模块存在两份（Taro 产物中一份，原生项目中一份）。
  6. 为了优化包体积大小，我们希望不要打包到 Taro 产物中，而是直接引用原生项目中的代码，可以使用 Webpack 的 [externals](https://webpack.js.org/configuration/externals/) 配置去实现。
  8. #### 例子
  10. 假设以下项目结构：
  12.     ├── miniapp           原生项目
  13.     |   └── utils
  14.     |       └── util.js
  15.     └── taro-project      Taro 项目
  16.         ├── config
  17.         |   └── index.js 
  18.         └── src
  19.             └── pages
  20.                 └── index 此页面中希望引用 miniapp/utils/util.js
  22. 1. 配置 `alias`，目的是让 `externals` 更方便地筛选出不需要打包的依赖。
  23. 2. 配置 Webpack `externals`，选择出不需要打包的依赖，并计算好相对路径。
  24. 3. 设置环境变量 `process.env.NODE_ENV` 为 `production` 时，externals 生效。（当没有手动设置环境变量时，默认在 `watch` 模式时环境变量为 `development`，否则为 `production`）
  26. ```js title="config/index.js" {3,8,10,15-29}
  27. const config = {
  28.   alias: {
  29.     '@/utils': process.env.NODE_ENV === 'production'
  30.       // 生产环境路径计算：
  31.       // Webpack 编译发生在 taro-project 下，假设编译后的 taro-project/dist 会被移到到 miniapp/taro。
  32.       // path.resolve(__dirname, '..') 为 taro-project。taro-project/dist 之于 taro-project，相当于 miniapp/taro 之于 miniapp。
  33.       // 再根据 miniapp/utils 与 miniapp 的相对路径，得出 path.resolve(__dirname, '../utils')
  34.       ? path.resolve(__dirname, '../utils')
  35.       // 开发环境直接引用原生项目下的依赖，方便开发
  36.       : path.resolve(__dirname, '../../miniapp/utils')
  37.   },
  38.   mini: {
  39.     webpackChain (chain) {
  40.       chain.merge({
  41.         externals: [
  42.           (context, request, callback) => {
  43.             const externalDirs = ['@/utils']
  44.             const externalDir = externalDirs.find(dir => request.startsWith(dir))
  46.             if (process.env.NODE_ENV === 'production' && externalDir) {
  47.               const externalDirPath = config.alias[externalDir]
  48.               const res = request.replace('@/utils', path.relative(context, externalDirPath))
  50.               return callback(null, `commonjs ${res}`)
  51.             }
  53.             callback()
  54.           },
  55.         ]
  56.       })
  57.     }
  58.   }
  59. }

效果

```js title=”taro-project/src/pages/index/index.js” import { logSomething } from ‘@/utils/util’ logSomething()

  2. ```js title="webpack 打包结果"
  3. {
  4.   "./src/pages/index/index.jsx": (function(m, e, __webpack_require__) {
  5.     var _utils_util = __webpack_require__("@/utils/util");
  6.     // ...
  7.   }),
  8.   "@/utils/util": (function(module, exports) {
  9.     // 成功 external
  10.     module.exports = require("../../../utils/util");
  11.   })
  12. }

Taro 项目引用原生项目的原生组件

有时我们需要在 Taro 项目中引用原生项目中的公共自定义组件。

和引用原生项目的 js 文件一样，我们希望在开发环境能正确解析组件路径，在生产环境则直接引用原生项目的组件而不是重复打包，可以使用 Taro 的 alias 配置去实现。

例子

假设以下项目结构：

  1. ├── miniapp                原生项目
  2. |   └── components
  3. |       └── title
  4. |           ├── index.js
  5. |           ├── index.wxml
  6. |           ├── index.wxss
  7. |           └── index.json
  8. └── taro-project           Taro 项目
  9.     ├── config
  10.     |   └── index.js 
  11.     └── src
  12.         ├── components     小程序不支持引用根目录之外的组件，因此只能把原生项目的组件拷贝过来，让开发环境能正确解析组件
  13.         |   └── title      
  14.         └── pages
  15.             └── index      此页面中希望引用 miniapp/components/title
  1. 把原生项目的组件拷贝到 Taro 项目，让开发环境能正确解析组件。
  2. 根据开发环境和生产环境，正确配置 alias

```js title=”config/index.js” {3,8,10} const config = { alias: { ‘@/components’: process.env.NODE_ENV === ‘production’ // 生产环境路径计算： // Webpack 编译发生在 taro-project 下，假设编译后的 taro-project/dist 会被移到到 miniapp/taro。 // path.resolve(dirname, ‘..’) 为 taro-project。taro-project/dist 之于 taro-project，相当于 miniapp/taro 之于 miniapp。 // 再根据 miniapp/components 与 miniapp 的相对路径，得出 path.resolve(dirname, ‘../components’) ? path.resolve(dirname, ‘../components’) // 开发环境引用 taro-project/src 下的组件 : path.resolve(dirname, ‘../src/components’) } }

  2. ```js title="taro-project/src/pages/index/index.config.js" {3}
  3. export default {
  4.   usingComponents: {
  5.     title: '@/components/title/index'
  6.   }
  7. }

对 Taro 项目的部分页面分包

在原生项目中直接配置 subPackages 指向 Taro 编译后的页面即可。

依赖细分

Taro 默认会把页面共用的普通依赖打包为主包里的 common.js，node_modules 依赖打包为主包里的 vendor.js。

但是在分包时，我们会希望把只有在分包中共用的依赖打包到分包中，而不是打在主包的 common.js 和 vendor.js 中。这就需要我们对依赖进行细分。可以借助 Webpack 的 splitChunk 和 Taro 的 addChunkPages 配置去实现。

例子

假设以下项目结构：

  1. ├── dist
  2. |   |── common.js     公共依赖
  3. |   |── vendors.js    node_modules 依赖
  4. |   └── subPackages
  5. |       ├── foo
  6. |       ├── bar
  7. |       └── common.js 只有 subPackages 子包中使用的公共依赖
  8. └── src
  9.     └── subPackages
  10.         ├── foo
  11.         └── bar
  1. 使用 Webpack splitChunks 把只有 subpackages 子包独有的依赖打包到 subpackages/common.js 中。
  2. 使用 Taro addChunkPages 配置，在子包中所有页面的头部添加对 subpackages/common.js 的引用。

```js title=”config/index.js” {3-6,12-20} const config = { mini: { addChunkPages (pages) { pages.set(‘subpackages/bar/index’, [‘subpackages/common’]), pages.set(‘subpackages/foo/index’, [‘subpackages/common’]) }, webpackChain (chain) { chain.merge({ optimization: { splitChunks: { cacheGroups: { subpackagesCommon: { name: ‘subpackages/common’, minChunks: 2, test: (module, chunks) => { const isNoOnlySubpackRequired = chunks.find(chunk => !(/\bsubpackages\b/.test(chunk.name))) return !isNoOnlySubpackRequired }, priority: 200 } } } } }) } } }

  2. ## 把 Taro 项目作为一个完整分包
  4. ### 示例项目
  6. [blended-apart](https://github.com/NervJS/taro/tree/next/examples/blended-apart)
  8. ### 使用方法
  10. #### 1. 安装使用插件
  12. 安装插件 [@tarojs/plugin-indie](https://github.com/NervJS/taro-plugin-indie)
  14. ```bash
  15. npm i @tarojs/plugin-indie --save-dev

使用插件

```js title=”config/index.js” const config = { plugins: [ ‘@tarojs/plugin-indie’ ] }

  2. #### 2. 开发环境
  4. 2.1 推荐在 Taro 项目中进行开发调试，在生产环境下再把产物移动到原生小程序中进行预览。
  6. ```bash
  7. # 和编译普通 Taro 项目一样
  8. $ taro build --type [platform] --watch

2.2 小程序开发者工具导入 Taro 项目进行预览。

3. 生产环境

3.1 编译项目时使用 --blended 参数以输出混合模式的代码。

  1. # 以混合模式进行打包
  2. $ taro build --type [platform] --blended

3.2 移动 Taro 项目的输出目录到原生项目内

也可以编写一个 Taro 插件自动移动，可以参考 plugin-mv。

3.3 设置原生项目的分包配置

把 Taro 项目拆分到多个分包

假设有一个 Taro 项目，它含有页面 A 和页面 B。我们需要把页面 A 加入原生项目的其中一个分包 M，把页面 B 加入到另一个分包 N。

为此，和普通打出一个分包不同的是，首先需要配置 Webpack 的 output.jsonpFunction 配置，避免 chunkid 的冲突。

```js title=”config/index.js” {7} config = { mini: { webpackChain (chain) { chain.merge({ output: { // 可以配合 npm script 和环境变量来动态修改 jsonpFunction: process.env.JSONP_NAME || “webpackJsonp” } }) } } }

  2. 然后分别对 A、B 页面使用混合模式打包，步骤和[把 Taro 项目作为一个完整分包](./taro-in-miniapp#把-taro-项目作为一个完整分包)一致。
  4. ## 把 Taro 组件编译为原生自定义组件
  6. :::info
  7. Taro v3.1.2 开始支持，且暂时只支持 React
  8. :::
  10. Taro 支持把组件编译为**原生小程序自定义组件**，供原生项目使用。
  12. ### 示例项目
  14. [blended-taro-component](https://github.com/NervJS/taro/tree/next/examples/blended-taro-component)
  16. ### 使用方法
  18. #### 1. 配置组件路径
  20. 修改 `app.config.js`，增加 `components` 配置，指向组件入口文件的路径：
  22. ```js title="app.config.js"
  23. export default {
  24.   // ...
  25.   components: [
  26.     'pages/index/index',
  27.     'components/picker/index'
  28.   ]
  29. }

2. 开始编译

使用 taro build native-components 命令，配合参数 type，即可编译出对应平台的自定义组件。

  1. taro build native-components --type [platform] [--watch]

props 传递

传递 props 给 Taro 编译出来的原生自定义组件时，需要统一通过 props 参数来传递：

```js title=”page/index/index.js” Page({ data: { pickerProps: { mode: ‘format’, value: [0, 0, 0], onInitial (value, index) { console.log(‘onInitial’) } } } })

  2. ```xml title="page/index/index.wxml"
  3. <!--index.wxml-->
  4. <view>
  5.   <picker props="{{pickerProps}}"></picker>
  6. </view>

```jsx title=”Taro 组件 - Picker” function Picker ({ mode, value, onInitial }) { return ( // … ) }

  2. ### 小程序自定义组件对象实例
  4. 开发者可以通过 `props.$scope` 获取到小程序的自定义组件对象实例。
  6. 使用某些小程序 API 时可能需要使用此实例，如获取视图层 DOM：
  8. `Taro.createSelectorQuery().in(props.$scope)`
  10. ### 组件间通信与事件
  12. 支持使用两种方式进行组件间通信。
  14. #### 使用小程序的 triggerEvent
  16. 和小程序原生自定义组件的[组件间通信与事件](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/events.html)一样，子组件使用 `triggerEvent` 发送事件。
  18. ```js title="子组件"
  19. props.$scope.triggerEvent('myevent', myEventDetail, myEventOption)

通过 props 传递事件回调

```js title=”父组件” Page({ data: { childProps: { // props 里可以传递函数 onMyEvent (value, index) { console.log(value, index) } } } }) // 和普通 props 传递一样

  2. ```js title="子组件"
  3. props.onMyEvent(value, index)

组件配置

:::info Taro v3.3.20 开始支持 :::

微信小程序的自定义组件支持配置 styleIsolation、virtualHost 等特性。在 Taro 中可以通过修改组件的配置文件进行设置：

js title="index.config.js" export default { styleIsolation: 'isolated', virtualHost: true }