简体中文
HBuilderX 版本需 ≥ 4.24
Windows系统如使用模拟器则需要开启以下功能
打开控制面板 - 程序与功能 - 开启以下功能
注意: 需要win10专业版或win11专业版才能开启以上功能,家庭版需先升级成专业版或企业版
HBuilderX 4.24 版本开始支持【运行到鸿蒙】,具体的方式是开发者下载鸿蒙工程模板并创建独立的鸿蒙工程目录,
然后在 uni-app 项目中的 manifest.json
里面设置 app-harmony.projectPath
属性来指向这个鸿蒙工程目录,
uni-app 项目在编译时把编译产物输出到鸿蒙工程目录,然后调起 DevEco Studio 打开鸿蒙工程目录,由开发者手动完成后续的运行调试工作。
HBuilderX 4.27+ 开始已经把鸿蒙工程模板内置到 HBuilderX 中,【运行到鸿蒙】时自动创建鸿蒙工程目录,与 uni-app 项目的编译产物合并, 然后调用鸿蒙工具链完成打包和安装、运行等操作,同时从运行设备上收集输出的日志显示到 HBuilderX 的控制台。
新的内置模板的方式虽然在调试运行过程中不再调起 DevEco Studio,但一般来说仍然需要安装 DevEco Studio,因为:
在 DevEco Studio 中打开任意一个项目(也可以新建一个空项目),然后在下图的位置进入设备管理器:
如果没有登录华为账号,此时需要先登录,登录成功后看到如下页面
选择模拟器型号,选第一个即可
安装完模拟器后,点击启动按钮启动模拟器
注意:真机需要鸿蒙系统版本 API 12 以上
打开鸿蒙手机开发者模式,开启USB调试,通过USB线连接电脑,在此处能看到对应的设备标识符则表示连接成功
注意:配置签名需要先启动模拟器或连接真机后才能配置
点击 DevEco-Studio 上方菜单 File - Project Structure...
生成运行调试证书和签名
在弹出的窗体中选择 Project - Signing Configs,并打钩 Automatically generate signature,即可自动生成签名
使用发布证书生成发布用的签名
需要先申请发布证书
在弹出的窗体中选择 Project - Signing Configs,并手动填写证书信息和密钥
依次点击 Apply
和 OK
使签名生效
如果是运行证书还是发布证书,生成的签名在文件 build-profile.json5 内
将它复制到你的 uni-app 项目根目录的 harmony-configs/build-profile.json5
的 signingConfigs 配置中
打开HBuilderX,点击上方菜单 - 工具 - 设置,再点击 运行配置,在鸿蒙运行配置中设置 DevEco Studio 的路径
HBuilderX 新建一个空白的 uni-app 项目,选vue3(也可使用已有的uni-app vue3项目)
编译 uni-app 到鸿蒙
点击 HBuilderX 上方【运行】菜单 - 运行到手机或模拟器 - 运行到鸿蒙
参考:修改鸿蒙工程配置
项目第一次发行时,会出现如下提示
部分API需要在配置文件显示声明权限才能调用,权限的配置文件路径为:/harmony-configs/entry/src/main/module.json5
,配置节点为:requestPermissions
,如下图所示
具体请查看以下文档
项目的根目录下有一个 harmony-configs
目录,每当执行跟鸿蒙相关的操作时,HX 都会检查这个目录,如果目录不存在则会自动创建。该目录中初始会存在几个常用的配置文件。
在执行运行或者发行到鸿蒙的操作过程中,HX 会根据内置模板生成一个鸿蒙工程目录(一般在 unpackage
目录下游),然后把 harmony-configs
目录下的所有内容都原样覆盖过去,
然后再调用鸿蒙的工具链进行编译打包等操作。
所以,harmony-configs
目录中的所有文件最终都会原样进入鸿蒙工程目录参与项目构建,所有需要对鸿蒙工程的定制化配置都可以写在这个目录下(注意:在 manifest.json
的【鸿蒙配置】中设置的选项将具有更高的优先级)。
关于 harmony-configs
目录的使用要遵守鸿蒙的技术规范,具体可参考 鸿蒙官方文档
Unexpected token (Note that you need plugins to import files that are not JavaScript)
或 Please make sure that the splash page has one and only one '@Entry' decorator
请将 HBuilderX 项目向上层目录移动,直到运行成功。这是因为鸿蒙在编译 ArkTs 时,.ets
文件路径总长不能大于 255 个字符。
参考鸿蒙官方文档:应用/组件级配置
为保证图标在系统内显示的一致性,应用预置的图标资源应满足以下要素:
启动页可以配置背景色代码(默认为#FFFFFF)和一张启动图,启动图没有尺寸要求,但建议为正方形logo图
仅 APP-HARMONY 和 APP 可以条件编译命中鸿蒙平台,APP-PLUS 不能命中中鸿蒙平台
// #ifdef APP-HARMONY
console.log("仅鸿蒙会编译")
// #endif
// #ifndef APP-HARMONY
console.log("仅非鸿蒙会编译")
// #endif
// #ifdef APP
console.log("安卓、苹果、鸿蒙会编译,小程序和Web不会编译")
// #endif
// #ifndef APP
console.log("安卓、苹果、鸿蒙不会编译,小程序和Web会编译")
// #endif
// #ifdef APP-PLUS
console.log("安卓、苹果会编译,鸿蒙不会编译,小程序和Web也不会编译")
// #endif
// #ifndef APP-PLUS
console.log("安卓、苹果不会编译,鸿蒙会编译,小程序和Web也会编译")
// #endif
虽然鸿蒙官方文档提供了如何开启热重载,详见文档,但目前只能针对ets文件的修改进行热更,还无法针对uniapp打包的js文件进行热更。
目前编译到鸿蒙时,在uniapp页面通过console.log打印日志可以直接在 HBuilderX 查看
注意:在uniapp页面打印对象或数组时,需要 JSON.stringify
,如 console.log("obj", JSON.stringify(obj))
首先尝试重新编译uniapp项目,并重启模拟器或真机,如果依然白屏或闪退,那可能是你项目中有用到了鸿蒙不支持的组件或者api,可以尝试pages.json进行代码二分法排查(删除一半页面如果正常了代表被删除的那一半页面中有造成白屏或闪退的页面)
确保签名没有问题的情况下,尝试重启电脑
Windows系统
Windows系统快速复制路径方法
注意:复制后的 \
要改成 /
原路径后面添加 /bin/devecostudio64.exe
,然后重启 HBuilderX
Mac系统
Mac系统快速复制路径方法
原路径后面添加 /Contents/MacOS/devecostudio
,然后重启 HBuilderX
当前导航栏未支持,可以尝试关闭原生导航栏,使用自己的自定义导航栏组件实现。
HBuilderX 4.31起支持uniPush推送,具体配置请参考文档
Cannot read property route of undefined
此问题由于arkTs的混淆Bug引发,即使进入到一个空的组合式api页面也会出现这个报错,已反馈给鸿蒙团队处理。
临时解决方案:在鸿蒙项目entry/obfuscation-rules.txt
文件中增加一行-disable-obfuscation
来禁用混淆。
Install Failed: error: failed to install bundle
此章节仅针对HBuilderX 4.29及之前版本,4.31及之后的版本暂不支持在x86_64平台的模拟器上运行。
此问题是由于支付宝sdk兼容性造成的,目前只能删除支付宝sdk依赖,如下图所示操作,删除后需要点右上角的 Sync Now,并等待 Sync 结束
删除后还需要点右上角的 Sync Now,并等待 Sync 结束
可以参考鸿蒙的文档 使用DevTools工具调试前端页面 进行处理。
在 uni-app 的开发模式 setWebDebuggingAccess
会自动开启,此步骤可以跳过。