Troubleshooting

不支持的小程序特性

入口 App 对象

页面 Page 对象

自定义组件

wxml 语法

关键问题

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。