dev.md 16.5 KB
Newer Older
1 2
# uni-app 开发鸿蒙应用

VK1688's avatar
VK1688 已提交
3 4
> [uni-app鸿蒙化技术交流群](https://im.dcloud.net.cn/#/?joinGroup=668685db8185e1e6e7b7b15e)

VK1688's avatar
VK1688 已提交
5 6 7 8 9 10
## 兼容性说明

1. 鸿蒙开发只支持Vue3,不支持Vue2、不支持plus、但支持nvue
2. nvue编译到鸿蒙后非原生渲染,而是与web一样渲染(自动注入一些默认样式进行兼容)
3. Vue3也支持选项式代码风格,参考[Vue2升Vue3指南](https://uniapp.dcloud.net.cn/tutorial/migration-to-vue3.html )

11 12 13 14 15 16
## 开发环境要求@env

* DevEco-Studio 5.0.3.400 以上 [下载地址](https://developer.huawei.com/consumer/cn/deveco-developer-suite/enabling/kit?currentPage=1&pageSize=100)
* 鸿蒙系统版本 API 12 以上 (DevEco-Studio有内置鸿蒙模拟器)
* HBuilderX-alpha-4.22 以上

VK1688's avatar
VK1688 已提交
17
**Windows系统如使用模拟器则需要开启以下功能**
18 19 20 21 22 23 24 25 26 27 28 29 30

打开控制面板 - 程序与功能 - 开启以下功能

1. Hyper-V
2. Windows 虚拟机监控程序平台
3. 虚拟机平台

注意: 需要win10专业版或win11专业版才能开启以上功能,家庭版需先升级成专业版或企业版

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/dev/1720085210915b1knhu7l3u8.png)

## 配置鸿蒙离线SDK(鸿蒙项目模板)@harmonysdk

VK1688's avatar
VK1688 已提交
31
1. 下载 uni-app 鸿蒙离线SDK template-1.3.4.tgz [下载地址](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/zip/template-1.3.4.tgz)
32

VK1688's avatar
VK1688 已提交
33
2. 解压刚下载的压缩包,将解压后的模板工程在 DevEco-Studio 中打开
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58

3. 等待 Sync 结束,点击运行按钮可以将工程运行在真机或者模拟器中(如未配置签名信息可能需要先行配置)

### 启动鸿蒙模拟器@connectvirtually

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/dev/1720085379828ap3pkhhfmig.png)

如果没有登录华为账号,此时需要先登录,登录成功后看到如下页面

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/dev/17200854641084hsm583p5jo.png)

选择模拟器型号,选第一个即可

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/dev/17200855617759sfquhr1j0o.png)

安装完模拟器后,点击启动按钮启动模拟器

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/dev/17200856058101582lbghgf8.png)

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/dev/1720085712493il2ep17ldg8.png)

### 连接鸿蒙真机@connectmobile

**注意:真机需要鸿蒙系统版本 API 12 以上**

VK1688's avatar
VK1688 已提交
59
打开鸿蒙手机开发者模式,开启USB调试,通过USB线连接电脑,在此处选择你的手机名称,再启动项目即可,如果提示需要先签名,则进行[配置签名](#signature)
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/dev/1720091392422r91cpejpp7g.png)

### 配置签名@signature

**注意:配置签名需要先启动模拟器或连接真机后才能配置**

点击 DevEco-Studio 上方菜单 File - Project Structure... 

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/dev/1720087126462d9133uo0hmg.png)

在弹出的窗体中选择 Project - Signing Configs 并打钩 Automatically generate signature,即可自动生成签名

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/dev/17200873385940vk5oj9ihk.png)

VK1688's avatar
VK1688 已提交
75 76 77 78
最后依次点击 `Apply``OK` 使签名生效

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/dev/1720259265552t0m33hs637.png)

79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122
## 配置 HBuilderX settings.json@hbxsettings

打开HBuilderX,点击上方菜单 - 工具 - 设置,在出现的弹窗右侧窗体新增如下配置

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/dev/1720092016399okjuod823f.png)

注意:值填你自己的 DevEco-Studio 启动路径

```js
"harmony.devTools.path" : "D:/Huawei/DevEco Studio"
```

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/171981598089431le57049d.png)

## 配置 uni-app 工程@uniappproject

1. HBuilderX 新建一个空白的 uniapp 项目,选vue3

2. 在 manifest.json 文件中配置鸿蒙离线SDK路径

编辑 manifest.json 文件,新增如下配置:

```json
"app-harmony": {
  "projectPath": "鸿蒙离线SDK路径"
}
```

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/1719816197812rg4fsafg2io.png)

3. 编译 uni-app 到鸿蒙

点击 HBuilderX 上方【运行】菜单,运行到鸿蒙 DevEco Studio

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/17183338900070pjn2uj49t8.png)

如果没有出现此菜单,请确认你的 HBuilderX 版本是否是 4.22 及以上

4. 在 DevEco-Studio 重新编译或运行

先等待 HBuilderX 编译完成,然后打开 DevEco-Studio,点击运行

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/dev/1720086018931faq60pigq9g.png)

VK1688's avatar
VK1688 已提交
123 124
## 使用uts调用鸿蒙原生API@nativeapi

DCloud_Heavensoft's avatar
DCloud_Heavensoft 已提交
125 126 127 128 129 130 131 132
uni-app在Android和iOS平台,支持uts插件和App原生语言插件。目前App原生语言插件已经停止维护。uts插件是主推的扩展方式。

鸿蒙系统有很多原生API,可以通过uts插件方式接入,被uni-app调用。

详细的教程见:
- [uts插件介绍](https://doc.dcloud.net.cn/uni-app-x/plugin/uts-plugin.html)
- [uts插件鸿蒙开发专题](https://doc.dcloud.net.cn/uni-app-x/plugin/uts-for-harmony.html)

VK1688's avatar
VK1688 已提交
133 134
这里以打开华为应用市场详情页为例

VK1688's avatar
VK1688 已提交
135
定义API名称为:openAppProduct
VK1688's avatar
VK1688 已提交
136 137 138 139 140 141

1. 右键 uni_modules 目录(没有则新建目录)点击 `新建uni_modules插件`

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/dev/1720150080112op9li2g0i1o.png)

2. 插件名称为 `uni-openAppProduct`(注意,开发者自己创建时,不可以使用 `uni-` 开头,应以自己名字或昵称的缩写命令,如:`wq-openAppProduct`
VK1688's avatar
VK1688 已提交
142
3. 修改插件根目录的 `package.json` 中的 `uni_modules` 节点,新增如下配置,arkts 为 true 代表支持鸿蒙
VK1688's avatar
VK1688 已提交
143 144 145

**注意:下方的属性名中包含的 `uni` 请勿更改成自己的名字或昵称缩写,只能用 `uni`**

VK1688's avatar
VK1688 已提交
146
```js
VK1688's avatar
VK1688 已提交
147 148 149 150 151 152 153 154 155 156 157 158 159 160 161
{
	...其他属性
	
	"uni_modules": {
		"uni-ext-api": {
			"uni": {
				"openAppProduct": {
					"name": "openAppProduct",
					"app": {
						"js": false,
						"kotlin": false,
						"swift": false,
						"arkts": true
					}
				}
VK1688's avatar
VK1688 已提交
162
			}
VK1688's avatar
VK1688 已提交
163 164 165
		},
		
		...其他属性
VK1688's avatar
VK1688 已提交
166
	}
VK1688's avatar
VK1688 已提交
167
}
VK1688's avatar
VK1688 已提交
168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306
```

4. 编写插件根目录下的 `/utssdk/interface.uts` 文件,内容如下

````js
export interface Uni {
	/**
		* openAppProduct()
		* @description
		* 跳转应用市场详情页
		* @param {OpenAppProductOptions}  options
		* @return {void}
		* @example
		 ```typescript
			uni.openAppProduct({});
		 ```
		*/
	openAppProduct(options : OpenAppProductOptions) : void;
}

export type OpenAppProduct = (options : OpenAppProductOptions) => void;
export type OpenAppProductSuccess = {
	/**
	 * 错误信息
	 */
	errMsg : string
};
export type OpenAppProductSuccessCallback = (result : OpenAppProductSuccess) => void;
export type OpenAppProductFail = {
	/**
	 * 错误信息
	 */
	errMsg : string
};
export type OpenAppProductFailCallback = (result : OpenAppProductFail) => void;
export type OpenAppProductComplete = {
	/**
	 * 错误信息
	 */
	errMsg : string
};
export type OpenAppProductCompleteCallback = (result : OpenAppProductComplete) => void;
export type OpenAppProductOptions = {
	/**
	 * 接口调用成功的回调函数
	 * @defaultValue null
	 */
	success ?: OpenAppProductSuccessCallback | null,
	/**
	 * 接口调用失败的回调函数
	 * @defaultValue null
	 */
	fail ?: OpenAppProductFailCallback | null,
	/**
	 * 接口调用结束的回调函数(调用成功、失败都会执行)
	 * @defaultValue null
	 */
	complete ?: OpenAppProductCompleteCallback | null
};
````

5. 编写插件根目录下的 `/utssdk/app-harmony/index.uts` 文件(没有则新建),内容如下

```js
import {
	OpenAppProduct,
	OpenAppProductOptions,
	OpenAppProductSuccess,
	OpenAppProductFail,
	OpenAppProductComplete
} from '../interface.uts'

import bundleManager from '@ohos.bundle.bundleManager';

export {
	OpenAppProduct,
	OpenAppProductOptions,
	OpenAppProductSuccess,
	OpenAppProductFail,
	OpenAppProductComplete
}

import { productViewManager } from '@kit.StoreKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import type { common, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export function openAppProduct(options : OpenAppProductOptions) {
	let isSuccess = true;
	try {
		const request : Want = {
			parameters: {
				// 此处填入要加载的应用包名,例如: bundleName: "com.huawei.hmsapp.appgallery"
				bundleName: bundleManager.getBundleInfoForSelfSync(bundleManager.BundleFlag.GET_BUNDLE_INFO_DEFAULT).name // 加载当前包名
			}
		};
		productViewManager.loadProduct(getContext() as common.UIAbilityContext, request, {
			onError: (err : BusinessError) => {
				isSuccess = false;
				hilog.info(0, 'TAG', `loadProduct onError. code is ${err.code}, message is ${err.message}`);
				let result : OpenAppProductFail = {
					errMsg: err.message ?? ""
				};
				const completeResult : OpenAppProductComplete = {
					errMsg: err.message ?? ""
				}
				options?.fail?.(result);
				options?.complete?.(completeResult);
			}
		} as productViewManager.ProductViewCallback);
	} catch (err) {
		isSuccess = false;
		hilog.error(0, 'TAG', `loadProduct failed. code is ${err.code}, message is ${err.message}`);
		let result : OpenAppProductFail = {
			errMsg: err.message ?? ""
		};
		const completeResult : OpenAppProductComplete = {
			errMsg: err.message ?? ""
		}
		options?.fail?.(result);
		options?.complete?.(completeResult);
	}

	// productViewManager.loadProduct 没有成功回调,故以此方式判断是否成功执行
	if (isSuccess) {
		let result : OpenAppProductSuccess = {
			errMsg: "ok"
		};
		const completeResult : OpenAppProductComplete = {
			errMsg: "ok"
		}
		options?.success?.(result);
		options?.complete?.(completeResult);
	}
}
```

6. 编写演示页面,项目根目录下 `/pages/index/index.vue` 内容如下

VK1688's avatar
VK1688 已提交
307 308
**方式一(挂载到uni全局对象)**

VK1688's avatar
VK1688 已提交
309 310 311
```vue
<template>
	<view class="content">
VK1688's avatar
VK1688 已提交
312
		<button class="button" @click="openAppProductBtn">打开应用市场</button>
VK1688's avatar
VK1688 已提交
313 314 315 316 317 318 319 320 321 322 323 324 325 326
	</view>
</template>

<script lang="uts">
	export default {
		data() {
			return {

			}
		},
		onLoad() {

		},
		methods: {
VK1688's avatar
VK1688 已提交
327
			openAppProductBtn() {
VK1688's avatar
VK1688 已提交
328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350
				uni.openAppProduct({
					success: (res) => {
						console.log('success: ', JSON.stringify(res));
					},
					fail: (err) => {
						console.error('fail: ', JSON.stringify(err));
					},
					complete: (res) => {
						console.log('complete: ', JSON.stringify(res));
					}
				});
			}
		}
	}
</script>

<style>
	.content {
		display: flex;
		flex-direction: column;
		align-items: center;
		justify-content: center;
	}
VK1688's avatar
VK1688 已提交
351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407
	
	.button{
		width: 100%;
		margin: 10px;
	}
</style>
```

**方式二(使用import引入)**

```vue
<template>
	<view class="content">
		<button class="button" @click="openAppProductBtn">打开应用市场</button>
	</view>
</template>

<script lang="uts">
	import { openAppProduct } from "@/uni_modules/xxx-openAppProduct"
	export default {
		data() {
			return {

			}
		},
		onLoad() {

		},
		methods: {
			openAppProductBtn() {
				openAppProduct({
					success: (res : any) => {
						console.log('success: ', JSON.stringify(res));
					},
					fail: (err : any) => {
						console.error('fail: ', JSON.stringify(err));
					},
					complete: (res : any) => {
						console.log('complete: ', JSON.stringify(res));
					}
				});
			}
		}
	}
</script>

<style>
	.content {
		display: flex;
		flex-direction: column;
		align-items: center;
		justify-content: center;
	}
	.button{
		width: 100%;
		margin: 10px;
	}
VK1688's avatar
VK1688 已提交
408 409 410 411 412 413 414 415 416
</style>
```

7. 点击 HBuilderX 上方【运行】菜单,运行到鸿蒙 DevEco Studio

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/17183338900070pjn2uj49t8.png)

8. 鸿蒙 DevEco Studio 启动项目

VK1688's avatar
VK1688 已提交
417 418
## 使用uts调用鸿蒙第三方库的API@nativelibs

419 420
> 新增于HBuilderX 4.25

VK1688's avatar
VK1688 已提交
421 422 423 424 425 426
鸿蒙的包用法和npm包差不多,在鸿蒙项目里面用ohpm安装三方库后,在 `/uni_modules/uts插件名/utssdk/app-harmony/index.uts` 内即可直接 import

注意:只能在满足uts插件 `/uni_modules/*/utssdk/app-harmony/*.uts` 的文件下使用,无法直接在项目的pages中使用

具体使用流程:在项目的pages引入uts插件,uts插件内再引入鸿蒙第三方库调用

427
以调用 `@cashier_alipay/cashiersdk` 为例,代码如下
VK1688's avatar
VK1688 已提交
428

VK1688's avatar
VK1688 已提交
429 430 431 432
`page` 内代码

```js
// 导入要使用的插件
433 434 435 436
import { requestPayment } from "@/uni_modules/test-alipay";
requestPayment({
	orderInfo: "xxxx"
});
VK1688's avatar
VK1688 已提交
437 438 439 440
```

`/uni_modules/*/utssdk/app-harmony/*.uts` 内的代码

VK1688's avatar
VK1688 已提交
441
```js
442 443 444 445 446 447
import { Pay } from '@cashier_alipay/cashiersdk'
export interface RequestPaymentOptions {
    orderInfo: string
}
export function requestPayment(options : RequestPaymentOptions) {
		return new Pay().pay(options.orderInfo, true)
VK1688's avatar
VK1688 已提交
448
}
VK1688's avatar
VK1688 已提交
449 450
```

VK1688's avatar
VK1688 已提交
451
## 发布鸿蒙应用@publish
VK1688's avatar
VK1688 已提交
452 453 454

鸿蒙官方文档提供了如何发布鸿蒙应用,详见[文档](https://developer.huawei.com/consumer/cn/doc/app/agc-help-releaseharmony-0000001933963166)

455 456
## 注意事项@tips

VK1688's avatar
VK1688 已提交
457 458 459 460 461 462 463 464 465 466 467
1. 移植已有的 uni-app 项目源码时,如有其他 npm 依赖,请自行安装
2. 现阶段条件编译仅 APP-HARMONY、APP 可以命中鸿蒙平台
3. 每次HBuilderX改动源码后,DevEco-Studio 内需要点重新运行才能生效
4. 如果模拟器白屏了,尝试重启软件 DevEco-Studio,再重启项目
5. 如果模拟器无法连接了,尝试重启电脑
6. 在HBuilderX里运行后,需要再去鸿蒙 DevEco Studio里运行
7. 在HBuilderX里修改代码后,需要去鸿蒙 DevEco Studio里重新运行
8. 如果有多个uni-app项目要编译到鸿蒙,那么鸿蒙离线sdk需要放置多份,每个uni-app的manifest中配置不同的离线sdk地址,否则会冲突,鸿蒙设备上目前没有基座概念

## 常见问题@question

VK1688's avatar
VK1688 已提交
468
### 如何修改应用包名@q1
VK1688's avatar
VK1688 已提交
469

VK1688's avatar
VK1688 已提交
470
1. 打开 `AppScope\app.json5` 修改 `bundleName`
VK1688's avatar
VK1688 已提交
471 472 473

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/dev/17202578113708uo26uaj0vg.png)

VK1688's avatar
VK1688 已提交
474 475 476
2. 删除 `build-profile.json5` 内旧的签名信息

3. 重启鸿蒙 DevEco Studio,启动模拟器或连接真机后,重新[配置签名](#signature)
VK1688's avatar
VK1688 已提交
477

VK1688's avatar
VK1688 已提交
478
### 如何修改应用名称@q2
VK1688's avatar
VK1688 已提交
479 480 481 482 483 484

1. 打开 `AppScope\resources\base\element\string.json` 修改数组元素 name 值为 app_name 对应的 value 的值
2. 打开 `entry\src\main\resources\base\element\string.json` 修改数组元素 name 值为 EntryAbility_label 对应的 value 的值
3. 打开 `entry\src\main\resources\en_US\element\string.json` 修改数组元素 name 值为 EntryAbility_label 对应的 value 的值
4. 打开 `entry\src\main\resources\zh_CN\element\string.json` 修改数组元素 name 值为 EntryAbility_label 对应的 value 的值

VK1688's avatar
VK1688 已提交
485
### 如何修改应用图标@q3
VK1688's avatar
VK1688 已提交
486 487 488 489 490 491 492

替换以下文件,注意文件不要改名

1. AppScope\resources\base\media\app_icon.png
2. entry\src\main\resources\base\media\foreground.png
3. entry\src\main\resources\base\media\startIcon.png

VK1688's avatar
VK1688 已提交
493
### 鸿蒙DevEco Studio如何开启热重载@q4
VK1688's avatar
VK1688 已提交
494

VK1688's avatar
VK1688 已提交
495
虽然鸿蒙官方文档提供了如何开启热重载,详见[文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-hot-reload-0000001527628941-V5),但目前只能针对ets文件的修改进行热更,还无法针对uniapp打包的js文件进行热更。
VK1688's avatar
VK1688 已提交
496 497 498 499 500 501 502 503

### 如何查看console打印的日志@q5

目前编译到鸿蒙时,在uniapp页面通过console.log打印日志无法在 HBuilderX 直接查看,需要在鸿蒙DevEco Studio内查看,具体查看方法如下图所示

注意:在uniapp页面打印对象或数组时,需要 `JSON.stringify` ,如 `console.log("obj", JSON.stringify(obj))`

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/dev/17210155750168uc4maboupo.png)
VK1688's avatar
VK1688 已提交
504

VK1688's avatar
VK1688 已提交
505
### 运行出现白屏或闪退怎么解决?@q6
VK1688's avatar
VK1688 已提交
506

VK1688's avatar
VK1688 已提交
507
首先尝试重新编译uniapp项目,并重启模拟器或真机,如果依然白屏或闪退,那可能是你项目中有用到了鸿蒙不支持的组件或者api,可以尝试pages.json进行代码二分法排查(删除一半页面如果正常了代表被删除的那一半页面中有造成白屏或闪退的页面)
VK1688's avatar
VK1688 已提交
508 509 510

### 模拟器已启动,但无法连接?@q7

VK1688's avatar
VK1688 已提交
511 512 513 514
确保[签名](#signature)没有问题的情况下,尝试重启电脑

### 报启动鸿蒙失败,请手动启动鸿蒙@q8

VK1688's avatar
VK1688 已提交
515 516
**Windows系统**

VK1688's avatar
VK1688 已提交
517 518 519 520 521 522 523 524
1. 确保路径是正确的

Windows系统快速复制路径方法

![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/dev/1721024978448hkblu60vadg.png)

注意:复制后的 `\` 要改成 `/`

VK1688's avatar
VK1688 已提交
525 526
2. 如果步骤1操作完还是不行,请尝试

VK1688's avatar
VK1688 已提交
527
原路径后面添加 `/bin/devecostudio64.exe`,然后重启 HBuilderX
VK1688's avatar
VK1688 已提交
528 529 530 531 532

**Mac系统**

1. 确保路径是正确的

VK1688's avatar
VK1688 已提交
533 534
Mac系统快速复制路径方法

VK1688's avatar
VK1688 已提交
535
![](https://web-ext-storage.dcloud.net.cn/uni-app/harmony/dev/ee1f4941-3736-4df8-a35c-bb3929fb124f.png)
VK1688's avatar
VK1688 已提交
536

VK1688's avatar
VK1688 已提交
537 538 539 540
2. 如果步骤1操作完还是不行,请尝试

原路径后面添加 `/Contents/MacOS/devecostudio`,然后重启 HBuilderX

VK1688's avatar
VK1688 已提交
541