兼容性说明
收藏
我的收藏

抖音小程序目前迭代比较快，各个 App 之间差异也比较大，开发者需要做好兼容工作，避免因为在低版本上使用了一个不兼容的 API 或组件而出现体验问题。一般可以通过版本号比较、API 存在判断、tt.canIUse、区分宿主 App 三种方式进行兼容处理。另外上线发布的时候也可以选择支持小程序的最低基础库版本。推荐使用 tt.canIUse 进行兼容性处理。

版本号比较

可以通过 tt.getSystemInfo 或者 tt.getSystemInfoSync 得到 SDKVersion。SDKVersion 是三位版本号，由[主版本号].[次版本号].[修订版本号]三部分组成，例如：1.11.1。一般会在 API 文档上标注支持该 API 的最低版本，或者在组件文档上标注支持某个属性的最低版本。版本号比较适用于所有情况。部分场景下也可以使用后面提到的方法完成。

API 存在判断

一般新增的 API 在低版本基础库上是不存在的，贸然调用会导致错误。建议做如下判断：

if (tt.navigateToMiniProgram) {
  tt.navigateToMiniProgram(); 
} else {
  tt.showModal({
    title: "提示",
    content:
      "当前客户端版本过低，无法使用该功能，请升级客户端或关闭后重启更新。",
  });
}

tt.canIUse

除了直接通过版本号判断，也通过 tt.canIUse 来判断 API、组件是否可以在该基础库版本下直接使用。

API 参数或返回值对于 API 的参数或者返回值有新增的参数，可以用以下代码判断。

tt.getImageInfo({
    src: '../images/test.jpg',
    success: (e) {
        if (tt.canIUse('getImageInfo.success.type')) {
            console.log(e.type);
        }
    } 
});

组件对于组件，新增的组件或属性在旧版本上不会被处理，不过也不会报错。如果特殊场景需要对旧版本做一些降级处理，可以判断用以下代码支持：

<open-data type="userAvatarUrl" tt:if="canIUse"></open-data>

Page({
  data: {
     canIUse: tt.canIUse("open-data"),
  },
});

区分 app

目前字节小程序已经集成到了多款 App，可以通过如下方法判断小程序运行于哪个 App。

const info = tt.getSystemInfoSync();
console.log(info.appName); 
if (info.appName.toUpperCase() === "DOUYIN") {
  // do something
}

info.appName对应的 App 如下：

值	说明
Toutiao	今日头条
Toutiao_Pro	今日头条专业版
news_article_lite	今日头条极速版
Douyin	抖音
douyin_lite	抖音极速版
aweme_hotsoon	抖音火山版
Tiktok	TikTok
Musically	TikTok.M
XiGua	西瓜视频
PPX	皮皮虾
automobile	懂车帝
DeliverManager	巨量引擎
Reading	番茄小说
xiaohe	小荷

基础库最低版本限制

为覆盖更多用户，功能性问题建议通过以上 canIUse 等手段兼容，兼容成本过高时可以登录小程序管理后台为小程序设置最低基础库版本要求。

开发者可以登录小程序管理后台，「设置 - 基础设置 - 小程序基础库版本」进行配置。建议您使用用户占比累计在 85% 以上的基础库版本号中的最低版本，基础库占比详见版本分布。

若用户客户端内的基础库版本低于开发者设置的小程序最低基础库版本，用户客户端会提示用户立即升级最新版本客户端。

Android	iOS

请引导用户按提示进行 App 升级便可以正确打开小程序。