抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台

抖音小程序适配鸿蒙 OS 指南

收藏
我的收藏
请开发者阅读以下内容修改记录,关注对正在适配和准备适配不同阶段的影响:
    1.2025 年 3 月 13 日,《三、1.鸿蒙环境识别》新增 IDE 环境下判断方式,并建议调整为通用处理方式。
    2.2025 年 3 月 20 日,《三、6.调试方法》新增添加调试设备的方式,适用于抖音 33.7.0 及以上版本。
    3.5月21日,《三、2. 支持情况 - 接口》抖音 34.5.0 版本以后,支持背景音频、getLocation、makePhoneCall、saveImageToPhotosAlbum、chooseImage、showDouyinOpenAuth
    4.7月14日,《三、 7. 入口与展示》补充入口展示和打开处理方法说明
    5.8月13日,《三、2. 支持情况 - 接口》抖音35.5.0 版本以后,支持激励视频广告,七分屏场景
    6.8月18日,《三、2. 支持情况 - 接口》抖音35.7.0 版本以后,支持wifi模块、罗盘、加速器、短信、陀螺仪、ActionSheet
    7.9月11日,《三、2. 支持情况 - 接口》抖音36.1.0 版本以后,支持选择地址chooseAddress
    8.9月23日,《三、6. 调试方法》新增扫一扫打开小程序的方式,适用于抖音36.2.0及以上版本
    9.11月19日,《三、2. 支持情况 - 接口》抖音36.8.0版本以后,支持
    地理位置
    地图
    窗口尺寸变化
    选择媒体
    媒体-canvas录制
    Workers
    Aweme-data
    拍抖音Page.onUploadDouyinVideo
    button.openType=uploadDouyinVideo
    button.openType=navigateToVideoView
    button.openType=openAwemeUserProfile
    map
    camera
    拉端卡片
    评价能力
    EventSource/WebSocket
    抖音云
    10.11月25日,《三、2. 支持情况 - 接口》抖音36.9.0版本以后,支持录音
    11.12月4日,《三、2. 支持情况 - 接口》抖音37.0.0版本以后,支持加桌

一、鸿蒙概览

鸿蒙 Next(HarmonyOS NEXT,HarmonyOS 5.0)系统是华为基于 OpenHarmony 开发的新操作系统,独立于Android/iOS。鸿蒙版抖音小程序框架目前在适配中,预计在2025年3月底开始面向开发者开放内测。届时存在部分能力未支持,或同Android/iOS表现有差异的情况,因此需要开发者做针对性适配,以保证小程序在鸿蒙端可正常运行。

二、鸿蒙设备

鸿蒙Next 指Harmony 5.0.0.115及以上版本的鸿蒙系统。开发者可参考官网说明,采购合适的手机用于测试验证。
鸿蒙Next系统
支持手机型号
Harmony 5.0.0.115及以上
Mate60系列、Mate70系列、Pure70等,详细见 HarmonyOS NEXT 支持机型(动态更新)

三、适配指引

鸿蒙环境识别

修改时间:2025.03.13
修改内容:鸿蒙环境识别新增 IDE 环境下判断方式,并建议调整为通用处理方式
不同适配进展的开发者
    已适配内容:建议调整为新的环境判断方式
    未适配内容:请使用新的环境判断方式
鸿蒙环境识别
UA识别
小程序内可调用接口tt.getSystemInfo 或 tt.getSystemInfoSync,目前有两个字段可以识别当前小程序运行的操作系统
    在真机与 IDE 上(建议)
let systemInfo = tt.getSystemInfoSync() if (systemInfo.system.toLowerCase().includes('openharmony')) { // 适配鸿蒙 console.log('当前运行在鸿蒙环境') }
    只能在真机上使用的字段
let systemInfo = tt.getSystemInfoSync() if (systemInfo.platform == "openHarmony") { // 适配鸿蒙 console.log('当前运行在鸿蒙环境') }
开发者可以通过读取user-agent,判断页面运行的容器环境。如下所示,其中各种版本数字仅供参考,具体版本可能随抖音或鸿蒙版本升级发生变化
    1.渲染webview的user-agent
Mozilla/5.0 (Phone; OpenHarmony 5.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 ArkWeb/4.1.6.1 Mobile aweme/32.9.0 ToutiaoMicroApp/3.54.0
    2.小程序内嵌的web-view的user-agent
Mozilla/5.0 (Phone; OpenHarmony 5.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 ArkWeb/4.1.6.1 Mobile aweme/32.9.0 ToutiaoMicroApp/3.54.0
    3.tt.request/upload/download也会带上user-agent

支持情况

以下为 2025年3月底内测版本涉及的部分支持或暂不支持的能力列表,使用到尚未支持的能力时需做好兼容。随着抖音鸿蒙版本迭代,不支持能力会在后续几个月内逐渐减少,请持续关注文档更新情况。

框架

特性
支持情况
页面
Page.onLiveMount
暂未支持
视频诊断工具
暂未支持

组件

模块
组件
支持情况
video
show-casting-button 属性暂未支持,表现为不展示投屏按钮。不抛错,不阻塞video播放
开放能力
ad
aweme-data
live-preview
draw-ad
暂未支持
开放能力button.openType
button.openType=joinGroup
button.openType=privateMessage
button.openType=platformIm
button.openType=authorizePrivateMessage
button.openType=addCalendarEvent
button.openType=openWebcastRoom
button.openType=byteHi
暂未支持
媒体组件
rtc-room
live-player
live-preview
暂未支持
行业开放
consume-card
member-button
暂未支持

接口

模块
接口
支持情况
行业开放-交易工具/交易系统/履约
-
暂未支持
界面-交互反馈
tt.showInteractionBar
tt.hideInteractionBar
暂未支持
开放接口-AR/AI能力/web化/侧边栏能力/电商插件能力(即将废弃)/插屏广告/直播能力/直播挂载/视频挂载
-
暂未支持
rtc-room 实时通信/录音
-
暂未支持
媒体-视频-LivePlayerContext
-
暂未支持
媒体-视频
tt.createLivePlayerContext
tt.prerenderVideo
tt.canIUseVideoFormat
暂未支持
媒体-特效相机
-
暂未支持
媒体-相机
-
暂未支持
设备-日历/扫码
-
暂未支持
设备-屏幕
tt.onUserScreenRecord
tt.offUserScreenRecord
暂未支持
文件
tt.openDocument
暂未支持

适配建议

情况
建议
    1.对于不支持的API/组件
    先通过caniuse判断是否支持。如果不支持,尽量避免直接调用
    2.如直接调用不支持的API/组件
    会统一抛出错误信息(onfail、throw Error、binderror)
{ errNo: 10302, errorCode: 88, errMsg: 'xxx_api:fail The feature is not available in current operating system', }
    需要提前做好异常处理,尽量避免阻塞业务流程
    对于调用不支持的同步API,如tt.getStorage(同步返回),throw Error 阻塞后续同步执行
    对于调用不支持的事件监听类API,如tt.onWindowResize,throw Error 阻塞后续同步执行
    对于调用不支持的异步API,如tt.getLocation,触发onfail回调
    3.对于不支持的组件
抛出组件错误 binderror(不支持该操作系统的错误),并渲染失败(有宽高没内容)
    4.部分API组件没有支持的属性或参数,尽量避免调用
    video,show-casting-button 属性暂未支持,表现为不展示投屏按钮。控制台打印使用了不支持的属性日志,不阻塞video播放
    web-view,JSSDK tt.miniprogram api暂未支持getlocation/compressImage/openLocation,触发onfail回调
    button组件,以下openType暂未支持,点击触发时,在binderror抛错
    openType=joinGroup
    openType=privateMessage
    openType=platformIm
    openType=authorizePrivateMessage
    openType=addCalendarEvent

适配提效

为了帮助开发者更高效适配鸿蒙,抖音开发者工具提供动态运行时检测和本地静态代码扫描两个维度能力。工程分析中的鸿蒙适配检测会扫描代码中存在的"鸿蒙待适配接口",同时模拟器提供鸿蒙机型以模拟运行环境,帮助开发者检查并适配小程序代码使其符合鸿蒙规范,从而提高开发效率。
鸿蒙适配助手使用方法请参考:开发者工具鸿蒙适配助手使用文档

适配示例

// 方式1:提前通过 canIUse 判断 let canIUseLocation = tt.canIUse("getLocation") if (canIUseLocation) { tt.getLocation({ success(res) { console.log(`经度${res.longitude}纬度${res.latitude}`); }, fail(res) { console.log("getLocation调用失败", res); } }) } else { // 系统未实现能力,需要适配,尽量避免阻塞业务流程 } // 特定的 openType 的 button 组件 tt.canIUse("button.open-type.uploadDouyinVideo")
// 方式2:提前通过错误码判断 //异步API tt.getLocation({ success(res) { console.log(`经度${res.longitude}纬度${res.latitude}`); }, fail(res) { console.log("getLocation调用失败", res); // 通过 errNo 捕获全局唯一的通用错误 if (res.errNo === 10302) { // 系统未实现能力,需要适配,尽量避免阻塞业务流程 } // 也可以通过 errorCode 进行捕获 // 下方的 AAAA 为 getLocation 该 API 对应的能力 ID // 这样捕获更加精确 if (res.errorCode === AAAA88) { // 系统未实现能力,需要适配,尽量避免阻塞业务流程 } // 也可以通过 errorCode 去除前四位能力 ID 部分并进行对比 if (String(res.errorCode).slice(4) === '88') { // 系统未实现能力,需要适配,尽量避免阻塞业务流程 } } }) //同步API try { tt.getDeviceInfoSync(...) } catch(e) { if (res.errNo === 10302) { ... // 系统未实现能力,需要适配,尽量避免阻塞业务流程 return } throw e }

调试方法

修改时间:2025.09.23
修改内容:新增扫一扫打开小程序的方法,适用于抖音36.2.0及以上版本。新增扫一扫绑定调试设备的方法,适用于抖音36.3.0及以上版本。
对于不同适配进展的开发者:在抖音 33.7.0 版本后,未添加调试设备的开发者将无法使用预览和真机调试功能。
在开放鸿蒙内测时,支持开发者通过小程序开发者工具(IDE)进行真机预览和调试。建议开发者提前准备支持鸿蒙Next系统的手机设备,可查看支持设备列表
从抖音36.2.0开始,支持抖音内扫一扫打开小程序。开发者可通过侧边栏或搜索的扫一扫入口扫码打开小程序。
推荐页侧边栏扫一扫入口
搜索扫一扫入口
个人页侧边栏扫一扫入口
低于36.2.0的版本,暂不支持抖音内扫码打开小程序,请使用操作系统扫码,或浏览器扫码功能。打开选择页面,选择使用抖音打开即可跳转到对应小程序。
在抖音 33.7.0 及以上版本进行调试和真机预览时,可能出现「你没有该小程序测试权限」页面,导致无法调试。
从抖音36.3.0开始,支持抖音内扫一扫绑定测试设备,可以通过抖音内扫一扫按照 Android/iOS 相同流程添加调试权限。
低于36.3.0的版本,暂不支持抖音内扫一扫绑定测试设备。请使用系统扫码或浏览器扫码扫描下列二维码,进入调试权限添加页面,并按照 Android/iOS 相同流程添加调试权限。

入口与展示

当前支持展示或打开小程序的入口:
    短视频锚点
    首页侧边栏-常用小程序
    首页侧边栏-通知消息
    小程序落地页-最近使用
    小程序落地页-我的常用
    小程序落地页-我的收藏
    小程序落地页-搜索
    小程序落地页-订单
    直播间观众端-小雪花
    直播间观众端-讲解卡
    直播间观众端-货架卡片
    扫码
    链接分享
    IM会话
当前鸿蒙对于不同入口打开时的处理有几种情况:
    1.对于已经适配的小程序,入口正常展示,小程序正常打开
    2.对于未适配的小程序:
    a.在受小程序可见性管控的入口(侧边栏、侧边栏-落地页、视频锚点推荐、 直播间等),不展示。
    b.在未受可见性管控的入口,可以展示,可以打开。平台不做打开拦截,至于业务能否跑通,取决于开发者有没有调用未实现的API或其他需要适配鸿蒙端的逻辑
    3.对于平台有显式配置拦截的小程序(黑名单),在受管控的入口不展示,在所有入口打开时客户端也会进行拦截,拉起兜底页
长期来看,在平台大部分的小程序已经完成鸿蒙适配后,可能会考虑在所有入口打开未适配的小程序时,客户端会进行拦截弹出兜底页。建议开发者尽快适配鸿蒙

四、内测上线

2025年3月底开始面向开发者内测开放上线鸿蒙时,开发者完成前置适配和验证后,可在小程序控制台发版时,同时勾选“抖音-HarmonyOS”。审核通过后,即可在抖音鸿蒙版发布对用户可见。

五、Q&A

Q:鸿蒙支持的交易系统是什么?
鸿蒙系统已支持通用交易系统及担保/非担保支付,相关支持现状与双端保持一致。
Q:多次通过浏览器重启小程序会有概率报这个 error 吗?
该报错可忽略,系统内部 API 暂未实现相关功能。

六、反馈收集

欢迎开发者给予我们适配体验反馈:
或者飞书扫码: