# ArkUIX-Modify-Guide

**Repository Path**: chaoskobe/ArkUIX-Modify-Guide

## Basic Information

- **Project Name**: ArkUIX-Modify-Guide
- **Description**: 主要介绍跨平台基础环境搭建，工程结构如何改造，应用不支持跨平台的API如何评估，Bridge方案参考示例工程
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-11-25
- **Last Updated**: 2025-04-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 跨平台改造指导

ArkUI跨平台框架(ArkUI-X)将ArkUI开发框架扩展到了多个OS平台：目前支持OpenHarmony、Android、 iOS，后续会逐步增加更多平台支持。开发者基于一套主代码，就可以构建支持多平台的精美、高性能应用。

## 环境搭建

#### DevEco Studio环境搭建

1. DevEco Studio为ArkUI-X应用构建提供了简单的集成开发环境，建议版本：V5.0.0 Release及以上。请从官网进行DevEco Studio的下载和安装：

    https://developer.huawei.com/consumer/cn/download/
2. 配置DevEco Studio开发环境相关指导：https://gitee.com/arkui-x/docs/blob/ArkUI-X-5.0.1-Release/zh-cn/application-dev/quick-start/start-with-deveco-studio.md

    DevEco Studio仅支持ArkUI-X源码开发和调试，各平台Native代码请使用对应平台的IDE编辑器进行开发和调试

#### AceTools环境搭建

1、Ace Tools默认随ArkUI-X SDK发布，有三种ArkUI-X SDK的获取方式，推荐使用DevEco Studio进行ArkUI-X SDK下载。具体的下载途径以及SDK内容组成说明如下：

https://gitee.com/arkui-x/docs/blob/ArkUI-X-5.0.1-Release/zh-cn/application-dev/tools/how-to-use-arkui-x-sdk.md

2、配置Ace Tools的环境指南：

https://gitee.com/arkui-x/docs/blob/ArkUI-X-5.0.1-Release/zh-cn/application-dev/quick-start/start-with-ace-tools.md

## 跨平台改造

Q1：开发者经常遇到的问题便是如何对现有的鸿蒙工程做跨平台改造？

A1：我们为大家提供了一键式改造的脚本，可以直接运行脚本，进行工程结构的跨平台改造。

脚本文件位置./project_modify.py，脚本使用指导：

##### 环境准备：

依赖本地安装有python环境

##### 工程目录

```shell
modify
  ├── ...                     
  ├── project_modify.py                     // 跨平台配置文件改造脚本
  ├── templates                             // 工程基础模板
```

##### 脚本运行参考

```shell
python project_modify.py ${鸿蒙工程文件夹的路径} ${要转换为跨平台模块的ModuleName}

// 参考示例
python ./project_modify.py /Users/arkuix/DevEcoStudioProjects/firstDemo entry
```

##### 注意事项

当前要转换为跨平台模块的ModuleName暂时只支持输入一个

##### 最终结果

经过工程改造，工程结构会增加.arkui-x目录，同时支持用Build APP(s)进行apk或者iOS应用包的编译

​![image](assets/image-20241121141400-7vgqchq.png)​

## 跨平台API支持能力评估脚本

Q2：当前哪些OH上的API和组件支持跨平台：

A2：

支持跨平台的API：https://gitee.com/arkui-x/docs/blob/master/zh-cn/application-dev/reference/apis/README.md

支持跨平台的组件及属性：https://gitee.com/arkui-x/docs/blob/master/zh-cn/application-dev/reference/arkui-ts

Q3：如何判断该api是否支持跨平台：

A2：

点击使用的api，跳转到对应的.d.ts文件中，标记@crossplatform则表示支持跨平台：

​![image](assets/image-20240715201056-xr3jz0z.png)​

‍

##### 遇到的问题：

经过上面的跨平台改造之后，执行Build APP(s)大概率会遇到以下错误：

​![image](assets/image-20241121155116-pighnwj.png)​

##### 应用不支持跨平台API能力评估结果：

那么如何查看报错的api都分布在哪些.d.ts中，来进行下一步的改造，我们也提供了跨平台能力评估脚本，观察当前应用不支持的api的具体分布，参考结果如下：

​![image](assets/image-20241122090930-himsbky.png)​

##### 应用不支持跨平台API评估脚本使用指导：

###### 环境准备：

依赖本地安装有python环境

###### 工程目录：

```shell
modify
  ├── ...                     
  ├── eval_cross.py                     // 跨平台能力评估脚本
  ├── log.txt                             // 不支持跨平台的api报错日志
```

###### 脚本运行参考：

```shell
python eval_cross.py 不支持跨平台的api报错日志 鸿蒙sdk路径

// Mac参考示例
python eval_cross.py ./log.txt /Applications/DevEco-Studio.app/Contents/sdk

// Windows参考示例，windows上运行时sdk路径需要用双引号引用
python .\eval_cross.py .\log.txt.txt "C:\Program Files\Huawei\DevEco Studio\sdk"
```

###### 注意事项：

1、需要check下，不支持跨平台的api报错日志中显示的具体代码路径是实际应用工程的路径

2、sdk是5.0.0 release及以上IDE配套的HarmonyOS NEXT SDK，sdk下的第一级目录需要是default文件夹

​![image](assets/image-20241122181349-0ecp27c.png)​

3、运行eval_cross.py脚本前，本地需要先安装pyecharts，安装命令如下

pip install pyecharts

## 如何解决部分API不支持跨平台的问题

##### 主要思路 **：**

ArkUI-X提供bridge能力，用于ArkTS和原生侧的通信，可以借助原生侧能力实现当前不支持跨平台API的功能

##### Bridge开发者文档：

总指南：https://gitee.com/arkui-x/docs/blob/ArkUI-X-5.0.1-Release/zh-cn/application-dev/quick-start/platform-bridge-introduction.md

Android侧平台桥接开发指南：https://gitee.com/arkui-x/docs/blob/ArkUI-X-5.0.1-Release/zh-cn/application-dev/tutorial/how-to-use-bridge-on-android.md

iOS侧平台桥接开发指南：https://gitee.com/arkui-x/docs/blob/ArkUI-X-5.0.1-Release/zh-cn/application-dev/tutorial/how-to-use-bridge-on-ios.md

##### 一码三平台参考demo工程：

主要介绍如何引入host_bridge公共桥接module，管理鸿蒙原生和iOS以及安卓之间的实现差异，让上层业务不再感知通道差异，专注自身业务实现。

https://gitee.com/chaoskobe/ArkUIX-Modify-Guide/tree/master/project