抖音小程序适配鸿蒙 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及以上 | |
三、适配指引
鸿蒙环境识别
修改时间: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月底内测版本涉及的部分支持或暂不支持的能力列表,使用到尚未支持的能力时需做好兼容。随着抖音鸿蒙版本迭代,不支持能力会在后续几个月内逐渐减少,请持续关注文档更新情况。
框架
特性 | 支持情况 |
页面 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 | 暂未支持 |
适配建议
情况 | 建议 |
|
|
|
|
| 抛出组件错误 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.09.23
修改内容:新增扫一扫打开小程序的方法,适用于抖音36.2.0及以上版本。新增扫一扫绑定调试设备的方法,适用于抖音36.3.0及以上版本。
对于不同适配进展的开发者:在抖音 33.7.0 版本后,未添加调试设备的开发者将无法使用预览和真机调试功能。
从抖音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 暂未实现相关功能。
六、反馈收集
欢迎开发者给予我们适配体验反馈:
或者飞书扫码:
