Troubleshooting
不支持的小程序特性#
入口 App 对象#
| 属性 | 说明 |
|---|---|
| onError | |
| onPageNotFound | |
| onUnhandledRejection | |
| onThemeChange |
页面 Page 对象#
| 属性 | 说明 |
|---|---|
| selectComponent | 建议使用 React ref 重构 |
| selectAllComponents | 建议使用 React ref 重构 |
| selectOwnerComponent | 建议使用 React ref 重构 |
| groupSetData |
自定义组件#
| 属性 | 说明 |
|---|---|
| moved | |
| externalClasses | Taro 3 不存在自定义组件，建议规范类名或使用 CSS Module 代替 |
| relations | |
| options | |
| definitionFilter |
wxml 语法#
| 属性 | 说明 |
|---|---|
| 循环 | [部分语法有限制] |
| 事件 | 部分语法有限制 |
| 引用 | 部分语法有限制 |
| wxs | 部分语法有限制 |
关键问题#
1. 没有处理基类#
原生开发中，常常会把 App、Page、Component 构造对象的公共逻辑整合到基类中。
如 Vant-weapp 中：
Taro 在编译时只能识别出入口、页面、组件文件中存在的 App()、Page()、Component() 调用，使用基类对配置封装后就不存在这些调用。因此编译后的 withWeapp 获得的参数是 {}。
因此我们需要手动修改：
2. 样式作用域#
微信小程序中的自定义组件，转换后会生成一个 Taro 中的 React/Vue 组件。
但是 Taro 中使用 React/Vue 开发的组件，编译到小程序平台时，并不会生成对应的小程序自定义组件。
因此微信小程序自定义组件的样式隔离特性，在转换为 Taro 后就会丢失。
解决办法：#
- 修改冲突的选择器。
- 使用 CSS Modules 进行改写。
常见问题#
1. wxml 语法转换问题#
把 wxml 转换为 JSX 是通过操作 AST 实现的，有一些写法可能没有考虑到，或难以适配，从而导致报错。
以下是一些已知问题，需要手动修复：
1.1 组件同时使用 wx:for 和 wx:if 语句时转换错误#
当组件上同时使用了 wx:for 和 wx:if 语句，并且使用了当前循环元素 item 或循环下标 index 做判断条件时，转换后会报错。
例如：
上例可见，对于条件语句的转换，目前的处理会把条件提取到组件外部。但是如果条件使用了 item 或 index 时，这样的提取逻辑会导致变量未定义的报错。
暂时可以通过手动修复解决：
方法一，修改编译前的代码，把循环和条件语句拆开到两个组件中：
方法二，修改编译后的代码,把条件判断放进循环体中：
1.2 根元素不能含有 hidden 属性。#
1.3 编译时报错：SyntaxError: Unexpected token#
尖括号 “<” 右侧需要留一个空格，#4243
解决办法：#
检查是否存在以下写法：
改为：
1.4 运行时报错：ReferenceError: item is not defined#
查看编译后的 JSX，是否因为漏了从 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#
- 一定要在
onReady、ready生命周期中才能调用小程序 API 获取 DOM。 - 不需要调用
.in(this)方法。
5. Image 没有处理动态拼接的 src#
Taro 会对 Image 组件的 src 进行处理：
但如果 src 是动态拼接的字符串，则需要手动修改：
6. require 的参数不能是变量#
可能遇到的报错信息：
- The "path" argument must be of type string. Received type undefined
不支持转换以下写法，#4749：
Taro 目前只能转换 require 字符串的写法。
7. 没有处理 export from 语法#
暂时手动处理，#5131。
8. Issues#
反向转换的更多问题，请查阅 Taroize 相关 Issues。