抖音小程序适配鸿蒙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及以上 | |
三、适配指引
鸿蒙环境识别
修改时间:2025.03.13
修改内容:鸿蒙环境识别新增 IDE 环境下判断方式,并建议调整为通用处理方式
不同适配进展的开发者:
- •已适配内容:建议调整采取新的环境判断方式
- •未适配内容:使用新的环境判断方式
鸿蒙环境识别 | UA识别 |
小程序内可调用接口tt.getSystemInfo 或 tt.getSystemInfoSync,目前有俩个字段可以识别当前小程序运行的操作系统
| 开发者可以通过读取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
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
|
支持情况
以下为 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 | 暂未支持 |
适配建议
情况 | 建议 |
|
|
|
|
| 抛出组件错误 binderror(不支持该操作系统的错误),并渲染失败(有宽高没内容) |
|
|
适配提效
为了帮助开发者更高效适配鸿蒙,抖音开发者工具提供动态运行时检测和本地静态代码扫描两个维度能力。工程分析中鸿蒙适配检测会扫描代码中存在"鸿蒙待适配的接口",模拟器提供鸿蒙机型模拟鸿蒙运行环境,从而帮助开发者检查和适配小程序代码符合鸿蒙规范,提高开发效率。
鸿蒙适配助手使用方法请参考:开发者工具鸿蒙适配助手使用文档
适配示例
// 方式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 版本后,未添加调试设备的开发者将不能使用预览、真机调试功能
由于抖音暂不支持扫码,请使用操作系统扫码,或浏览器扫码功能。打开选择页面,选择使用抖音打开即可跳转到对应小程序。
在抖音 33.7.0 及以上版本进行调试和真机预览时,可能出现「你没有该小程序测试权限」页面,导致无法调试。此时可以按照上述方法使用系统扫码或浏览器扫码扫描下列二维码,进入调试权限添加页面,并按照 Android/iOS 相同流程添加调试权限。
四、内测上线
2025年3月底开始面向开发者内测开放上线鸿蒙时,开发者完成前置适配和验证后,可在小程序控制台发版时,同时勾选“抖音-HarmonyOS”。审核通过后,即可在抖音鸿蒙版发布对用户可见。
五、Q&A
Q 鸿蒙支持的交易系统是什么?
通用交易系统 和 担保/非担保支付鸿蒙都已经支持,鸿蒙跟双端的现状是一致的
Q 多次通过浏览器重启小程序 会有概率报这个error
不影响,内部api没有实现
六、反馈收集
欢迎开发者给予我们适配体验反馈:
或者飞书扫码: