跳到主要内容
版本：3.x

Troubleshooting

不支持的小程序特性​

入口 App 对象​

属性说明
onError
onPageNotFound
onUnhandledRejection
onThemeChange

页面 Page 对象​

属性说明
selectComponent建议使用 React ref 重构
selectAllComponents建议使用 React ref 重构
selectOwnerComponent建议使用 React ref 重构
groupSetData

自定义组件​

属性说明
moved
externalClassesTaro 3 不存在自定义组件，建议规范类名或使用 CSS Module 代替
relations
options
definitionFilter

wxml 语法​

属性说明
循环[部分语法有限制]
事件部分语法有限制
引用部分语法有限制
wxs部分语法有限制

关键问题​

1. 没有处理基类​

原生开发中，常常会把 App、Page、Component 构造对象的公共逻辑整合到基类中。

如 Vant-weapp 中：

// 组件
VantComponent({
  data: {},
})
// 基类
function VantComponent(vantOptions = {}) {
  // 整合组件独有配置 vantOptions 和公共配置到最终的配置对象 options 中
  // ...

  // 调用小程序的 Component 方法构造自定义组件
  Component(options)
}

Taro 在编译时只能识别出入口、页面、组件文件中存在的 App()、Page()、Component() 调用，使用基类对配置封装后就不存在这些调用。因此编译后的 withWeapp 获得的参数是 {}。

VantComponent({
  data: {},
})
// withWeapp 中应该传入小程序配置对象
@withWeapp({})
class _C extends React.Component {}

因此我们需要手动修改：

// 基类
function VantComponent(vantOptions = {}) {
  // 整合组件独有配置 vantOptions 和公共配置到最终的配置对象 options 中
  // ...

  // 调用小程序的 Component 方法构造自定义组件
  // Component(options);

  // 1. 基类直接返回整合后的 options
  return options
}
// 2. 把基类创建的配置传入 withWeapp：
const options = VantComponent({
  data: {},
})
@withWeapp(options)
class _C extends React.Component {}

2. 样式作用域​

微信小程序中的自定义组件，转换后会生成一个 Taro 中的 React/Vue 组件。

但是 Taro 中使用 React/Vue 开发的组件，编译到小程序平台时，并不会生成对应的小程序自定义组件。

因此微信小程序自定义组件的样式隔离特性，在转换为 Taro 后就会丢失。

解决办法：​

  1. 修改冲突的选择器。
  2. 使用 CSS Modules 进行改写。

常见问题​

1. wxml 语法转换问题​

把 wxml 转换为 JSX 是通过操作 AST 实现的，有一些写法可能没有考虑到，或难以适配，从而导致报错。

以下是一些已知问题，需要手动修复：

1.1 组件同时使用 wx:for 和 wx:if 语句时转换错误​

当组件上同时使用了 wx:for 和 wx:if 语句，并且使用了当前循环元素 item 或循环下标 index 做判断条件时，转换后会报错。

例如：

// 转换前（注意判断条件使用了循环下标 index）：
<block wx:for="{{objectArray}}" wx:if="{{index % 2 !== 0}}">
  <view>objectArray item: {{item.id}}</view>
</block>
// 转换后：
{
  index % 2 !== 0 && (
    <Block>
      {objectArray.map((item, index) => {
        return (
          <Block>
            <View>{'objectArray item: ' + item.id}</View>
          </Block>
        )
      })}
    </Block>
  )
}

上例可见，对于条件语句的转换，目前的处理会把条件提取到组件外部。但是如果条件使用了 item 或 index 时，这样的提取逻辑会导致变量未定义的报错。

暂时可以通过手动修复解决：

方法一，修改编译前的代码，把循环和条件语句拆开到两个组件中：

<block wx:for="{{objectArray}}">
  <block wx:if="{{index % 2 !== 0}}">
    <view>objectArray item: {{item.id}}</view>
  </block>
</block>

方法二，修改编译后的代码,把条件判断放进循环体中：

<Block>
  {objectArray.map((item, index) => {
    return <Block>{index % 2 !== 0 && <View>{'objectArray item: ' + item.id}</View>}</Block>
  })}
</Block>

1.2 根元素不能含有 hidden 属性。​

1.3 编译时报错：SyntaxError: Unexpected token​

尖括号 “<” 右侧需要留一个空格，#4243

解决办法：​

检查是否存在以下写法：

<view>{{a <4? "1": "2"}}</view>

改为：

<view>{{a < 4? "1": "2"}}</view>

1.4 运行时报错：ReferenceError: item is not defined​

查看编译后的 JSX，是否因为漏了从 this.data 中取出变量，如：

// 下面的代码没有引用 item
const { a, b, c } = this.data
解决办法：​

this.data 中的变量名，不要和用于指定数组当前下标的变量名，默认值为 item，或由 wx:for-index 具体指定的变量名相同。

1.5 不支持 WXS 里的 GetRegExp 方法​

使用 RegExp 构造正则表达式。

1.6 <include> 里不支持使用 <template>​

1.7 template 里暂不支持使用 catch 事件​

2. 事件​

  • 事件不支持绑定字符串。
  • catchtouchmove 转换后只能停止回调函数的冒泡，不能阻止滚动穿透。如要阻止滚动穿透，可以手动给编译后的 View 组件加上 catchMove 属性。
  • 不支持事件捕获阶段。
  • 不支持使用 WXS 函数响应事件。
  • 不支持互斥事件绑定 mut-bind。
  • 不支持 mark 来识别具体触发事件的 target 节点。

3. CommonJS 和 ES 模块化语法不能混用​

可能遇到的报错信息：

  • Cannot assign to read only property 'exports' of object
  • export '[something]' (imported as '[name]') was not found in '[somePath]'

在使用到小程序 API 的地方，Taro 会把 wx.api() 转换为 Taro.api()，同时在文件的头部加上 import Taro from '@tarjs/taro。

如果此文件原本是使用 CommonJS 组织模块，可能会出现问题，需要手动修复。

4. selectorQuery API 获取不到 DOM​

  1. 一定要在 onReady、ready 生命周期中才能调用小程序 API 获取 DOM。
  2. 不需要调用 .in(this) 方法。

5. Image 没有处理动态拼接的 src​

Taro 会对 Image 组件的 src 进行处理：

// 转换前：
<Image src='../../img/icons/0.png' />
// 转换后：
<Image src={require('../../img/icons/0.png')} />

但如果 src 是动态拼接的字符串，则需要手动修改：

// 转换前：
<Image src='../../img/icons/' + chart.id + '.png' />
// 转换后：
<Image src='../../img/icons/' + chart.id + '.png' />
// 手动修改，图片也需要手动拷贝到 taroConert/src 对应目录下：
<Image src={require('../../img/icons/' + chart.id + '.png')} />

6. require 的参数不能是变量​

可能遇到的报错信息：

  • The "path" argument must be of type string. Received type undefined

不支持转换以下写法，#4749：

var pathTest = './test.js'
var test = require(pathTest)

Taro 目前只能转换 require 字符串的写法。

7. 没有处理 export from 语法​

暂时手动处理，#5131。

8. Issues​

反向转换的更多问题，请查阅 Taroize 相关 Issues。