---
title: 社区生态兼容
summary: "介绍涂鸦小程序对微信生态的兼容适配，支持引入 vant-weapp 等社区组件库。"
questions:
  - 涂鸦小程序兼容模式支持哪些微信生态能力？
  - 启用兼容模式需要满足哪些基础库和开发者工具版本要求？
  - 如何在 project.tuya.json 中开启微信兼容模式？
  - 开启兼容模式后支持哪些微信相关的文件格式和语法指令？
  - 在涂鸦小程序中如何引入 @vant/weapp 组件？
  - 涂鸦小程序引入微信社区组件库与微信小程序有什么路径区别？
  - 如何在涂鸦小程序中引入微信 recycle-view 组件？
  - 微信社区组件库引入路径调整的依据是什么？
  - 兼容适配 Beta 阶段存在哪些已知不兼容的情况？
  - 开启兼容模式后 wx 对象的 API 有什么使用限制？
---

## 介绍

小程序框架已存在几大厂商，微信、支付宝、抖音等，社区上经过几年成熟的发展，已经沉淀出一大批优秀的组件以及方案。为了提高开发者效率，沿用社区成熟方案，涂鸦小程序基础框架经过几次渐进迭代，在运行时上已适配微信生态（除原生接口外）`基础库版本 >= 2.12.0`。可实现组件的复用。

## 抢先体验

社区中较为成熟的组件库 [vant-weapp](https://youzan.github.io/vant-weapp/#/home) 已无缝接入智能小程序，使用涂鸦 App 扫码体验：

<Image src="/images/guide/vant-weapp.png" style={{width: '200px'}} />

- 原生小程序语法

<DemoBlock 
  githubUrl="https://github.com/Tuya-Community/tuya-miniapp-demo/tree/master/vant-weapp" 
  qrCodeUrl="/images/qrCode/vant-weapp.png" 
  lang="zh">
</DemoBlock>

- Ray语法

<DemoBlock 
  githubUrl="https://github.com/Tuya-Community/tuya-miniapp-demo/tree/master/rayUseWX" 
  qrCodeUrl="/images/qrCode/rayWx.png" 
  lang="zh">
</DemoBlock>

## 适配步骤

- 基础库 >= 2.12.0
- 开发者工具 >= 0.5.4

### 1. 项目配置

默认不启用兼容模式，由开发者自行启用，在 project.tuya.json 文件中配置 `compilerOptions.compatible`

```diff
{
  "projectname": "your-app",
  "dependencies": {
    "BaseKit": "3.0.0",
    "MiniKit": "3.0.0",
    "BizKit": "3.0.1"
  },
+  "compilerOptions": {
+    "compatible": ["wx"]
+  },
  "baseversion": "2.12.0",
}
```

> 目前仅支持 wx 兼容模式

开启后则支持 `.wxml` `.wxs` 等文件，及 `wx:` 模板语法指令，同时也会存在 `wx` 对象， 例如 `wx.showToast()` 等基础 API。

### 2. 组件引入

智能小程序默认支持 npm 三方包导入，无需单独构建，此处与微信小程序有所不同，因此导入方式也有所不同，在 usingComponents 导入时需要做相应的调整。

#### 使用 @vant/weapp 组件

[@vant/weapp](https://youzan.github.io/vant-weapp/#/intro) 是一套基于微信小程序开发的 UI 组件库，涂鸦智能小程序也已适配，使用方式与微信小程序一致。

在微信小程序中 usingComponents 使用以下方式引入：

```json
{
  "usingComponents": {
    "van-button": "@vant/weapp/button/index"
  }
}
```

查看 [@vant/weapp/package.json](https://unpkg.com/browse/@vant/weapp/package.json) 中 miniprogram 字段声明。

在智能小程序中，使用以下方式引入，直接引用 `lib` 目录下的文件：

```json
{
  "usingComponents": {
    "van-button": "@vant/weapp/lib/button/index"
  }
}
```

#### 使用微信 recycle-view 组件

[recycle-view](https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/extended/component-plus/recycle-view.html) 是微信小程序提供的高性能列表组件，涂鸦智能小程序也已适配，使用方式与微信小程序一致。

在微信小程序中 usingComponents 使用以下方式引入：

```json
{
  "usingComponents": {
    "recycle-view": "miniprogram-recycle-view/recycle-view",
    "recycle-item": "miniprogram-recycle-view/recycle-item"
  }
}
```

查看 [miniprogram-recycle-view/package.json](https://unpkg.com/browse/miniprogram-recycle-view/package.json) 中 miniprogram 字段声明。

在智能小程序中，使用以下方式引入，直接引用 `miniprogram_dist` 目录下的文件：

```json
{
  "usingComponents": {
    "recycle-view": "miniprogram-recycle-view/miniprogram_dist/recycle-view",
    "recycle-item": "miniprogram-recycle-view/miniprogram_dist/recycle-item"
  }
}
```

### 小结

对于微信社区中的组件库，只需要在 `usingComponents` 中引入时对路径做相应的调整即可，其他使用方式与微信小程序一致。

如何调整取决于对应组件库的 package.json 中 miniprogram 字段的值。

## 注意事项

兼容适配处于 Beta 阶段，对于大部分 UI 组件库可直接使用，但也存在一些不兼容的情况，例如：

- [内置 behavior](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/behaviors.html#%E5%86%85%E7%BD%AE-behaviors)
- 抽象节点、占位组件
- 插件 `requirePlugin` `requireMiniProgram`
- 双向绑定
- canvasContext
- 事件系统：`longpress` `longtap` `touchforcechange` `animationiteration`
- 使用了 `wx` 对象的 API，例如 `wx.revokeBufferURL` 等智能小程序不存在的 API 方法。