抖音小程序适配鸿蒙OS指南-短剧行业

收藏
我的收藏
请开发者阅读以下内容修改记录,关注对正在适配和准备适配不同阶段的影响:
    1.3 月 13 日,《三、1.鸿蒙环境识别》新增 IDE 环境下判断方式,并建议调整为通用处理方式。
    2.3 月 20 日,《三、6.调试方法》新增添加调试设备的方式,适用于抖音 33.7.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月底内测版本涉及的部分支持或暂不支持的能力列表,对使用到尚未支持的能力需做好兼容。随着抖音鸿蒙版本迭代,不支持能力会在后续几个月内逐渐减少,请持续关注文档更新情况。

框架

特性
支持情况
workers
暂未支持
页面
Page.onUploadDouyinVideo
Page.onLiveMount
暂未支持
七分屏场景 onResize
暂未支持
视频诊断工具
暂未支持

组件

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

接口

模块
接口
支持情况
地理位置
-
暂未支持
地图
-
暂未支持
行业开放-交易工具/交易系统/履约
-
暂未支持
基础-窗口尺寸变化
-
暂未支持
基础-线程-Worker
-
暂未支持
基础-性能
-
暂未支持
界面-交互反馈
tt.showActionSheet
tt.showInteractionBar
tt.hideInteractionBar
暂未支持
开放接口-AR/AI能力/web化/侧边栏能力/电商插件能力(即将废弃)/广告/拉端/评价能力/收货地址/小程序跳转/直播能力/转发和挂载
-
暂未支持
开放接口-授权
tt.showDouyinOpenAuth
tt.authorize
暂未支持
媒体-canvas录制/rtc-room 实时通信/录音
-
暂未支持
媒体-视频-LivePlayerContext
-
暂未支持
媒体-视频-PreloadVideoTask
-
暂未支持
媒体-视频
tt.preloadVideo
tt.chooseMedia
tt.saveVideoToPhotosAlbum
tt.chooseVideo
tt.createLivePlayerContext
tt.prerenderVideo
tt.canIUseVideoFormat
暂未支持
媒体-特效相机
-
暂未支持
媒体-图片
tt.chooseImage
tt.saveImageToPhotosAlbum
tt.previewImage
tt.compressImage
暂未支持
媒体-相机
-
暂未支持
媒体-音频-BackgroundAudioManager
-
暂未支持
设备-WiFi/拨打电话/短信/加密/加速度计/罗盘/日历/扫码/陀螺仪
-
暂未支持
设备-屏幕
tt.onUserScreenRecord
tt.offUserScreenRecord
暂未支持
设备-网络状态
tt.onGetWifiList
tt.offGetWifiList
tt.getWifiList
tt.onNetworkWeakChange
暂未支持
设备-系统信息
tt.getDeviceInfoSync
暂未支持
网络-EventSource/WebSocket
-
暂未支持
文件
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=uploadDouyinVideo
    openType=joinGroup
    openType=privateMessage
    openType=platformIm
    openType=navigateToVideoView
    openType=authorizePrivateMessage
    openType=addCalendarEvent
    openType=addShortcut

适配提效

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

适配示例

// 方式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.03.20
修改内容:新增添加调试设备的方式
不同适配进展的开发者:抖音 33.7.0 版本后,未添加调试设备的开发者将不能使用预览、真机调试功能
在开放鸿蒙内测时,支持开发者通过小程序开发者工具(IDE)进行真机预览和调试。建议开发者提前准备支持鸿蒙Next系统的手机设备,可查看支持设备列表
由于抖音暂不支持扫码,请使用操作系统扫码,或浏览器扫码功能。打开选择页面,选择使用抖音打开即可跳转到对应小程序。
在抖音 33.7.0 及以上版本进行调试和真机预览时,可能出现「你没有该小程序测试权限」页面,导致无法调试。此时可以按照上述方法使用系统扫码或浏览器扫码扫描下列二维码,进入调试权限添加页面,并按照 Android/iOS 相同流程添加调试权限。

四、内测上线

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

五、Q&A

Q 鸿蒙支持的交易系统是什么?
通用交易系统 和 担保/非担保支付鸿蒙都已经支持,鸿蒙跟双端的现状是一致的
Q 多次通过浏览器重启小程序 会有概率报这个error
不影响,内部api没有实现

六、反馈收集

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