一、 环境准备与 CLI 安装

在创建项目前，需确保本地已安装 Node.js（建议 16.x 或以上版本），并配置好 Java 环境（建议 JDK 11.0.2 以上）。随后，需要全局安装 ArkUI-X 的命令行工具 ACE Tools。

安装命令：

# 1. 修改 npm 源（推荐华为云源，提升下载速度）
# 在用户目录的 .npmrc 文件中添加：
# @ohos:registry=https://repo.harmonyos.com/npm/
# registry=https://repo.huaweicloud.com/repository/npm/

# 2. 全局安装 ACE 命令
npm install -g @ohos/ace-cli

二、 创建跨平台工程

安装完成后，即可使用 ace create 命令初始化项目。在执行过程中，CLI 会引导开发者依次输入工程名称、包名称（Bundle Name）、目标系统（OpenHarmony 或 HarmonyOS）以及项目类型（Application 或 Library）。

创建命令：

# 执行创建命令
ace create project

# 交互式输入示例：
# ? Please enter the project name: MyCrossApp
# ? Please enter the bundle name (com.example.MyCrossApp): com.example.mycrossapp
# ? Please enter the system (1: OpenHarmony, 2: HarmonyOS): 1
# ? Please enter the project type (1: Application, 2: Library): 1
# ? Please enter the template (1: Empty Ability, 2: Native C++): 1

三、 工程目录结构解析

项目创建成功后，会生成一套标准化的跨平台工程目录。核心业务代码位于 entry 目录下，各平台的原生代码则被隔离在各自的文件夹中。

目录结构示例：

MyCrossApp/
├── entry/                 # 主业务模块（ArkTS 代码）
│   ├── src/
│   │   ├── main/
│   │   │   ├── ets/       # ArkTS 声明式 UI 与业务逻辑
│   │   │   ├── resources/ # 跨平台资源文件
│   │   │   └── module.json5 # 模块配置
│   └── build-profile.json5 # 构建配置
├── ios/                   # iOS 平台原生代码
│   ├── AppDelegate.swift
│   └── Info.plist
├── android/               # Android 平台原生代码
└── arkui-x.config.json5   # 跨平台核心配置文件

四、 多平台构建与运行

ACE Tools 提供了统一的命令来编译和打包不同平台的安装包。开发者只需进入项目根目录，即可一键构建并安装到对应的真机或模拟器中。

构建与运行命令：

cd MyCrossApp

# 安装并运行到 Android 设备（构建 APK）
ace run apk

# 安装并运行到 iOS 设备（构建 App，需在 macOS 上并配置 Xcode）
ace run app

# 安装并运行到 OpenHarmony 设备（构建 HAP）
ace run hap

五、 多平台适配配置与依赖管理

在跨平台开发中，不同平台的最低 SDK 版本、编译参数以及依赖库往往存在差异。ArkUI-X 允许开发者在 oh-package.json5 或 build-profile.json5 中精细配置各平台的构建参数，确保工程在多端顺利编译。

核心配置示例（oh-package.json5）：

{
  "arkui-x": {
    "targets": ["android", "ios", "web"],
    "android": {
      "minSdkVersion": 21,
      "compileSdkVersion": 33
    },
    "ios": {
      "deploymentTarget": "12.0",
      "enableBitcode": false
    }
  }
}

六、 编写跨平台 UI 组件与状态管理

ArkUI-X 沿用鸿蒙 ArkUI 的组件化开发思想，开发者可以使用声明式语法构建 UI，并通过状态管理装饰器（如 @State、@ObjectLink）实现跨组件的数据同步。这些组件最终会被编译为多端统一渲染的指令。

核心代码示例（ArkTS）：

@Entry
@Component
struct Index {
  @State message: string = 'Hello ArkUI-X'
  build( ) {
    Column() {
      Text(this.message)
        .fontSize(24)
        .fontColor(Color.Blue)
      Button('Click Me')
        .onClick(() => {
          this.message = '跨平台交互成功'
        })
    }
    .width('100%')
    .height('100%')
  }
}

七、 跨平台设备能力调用与权限适配

在调用相机等原生设备能力时，ArkUI-X 提供了统一的 Kit 接口。但需要注意的是，跨平台项目必须在各个平台（HarmonyOS、Android、iOS）的配置文件中分别声明对应的权限，否则会导致调用失败。

核心代码示例（相机调用）：

import camera from '@kit.DeviceCapabilityKit'

@Entry
@Component
struct CameraPage {
  controller: camera.CameraController = new camera.CameraController()
  build( ) {
    Stack() {
      CameraPreview(this.controller)
        .width('100%')
        .height('100%')
      Button('拍照')
        .onClick(() => {
          this.controller.takePhoto()
        })
    }
  }
}

注：HarmonyOS 需在 module.json5 中声明 ohos.permission.CAMERA；Android 需在 AndroidManifest.xml 中添加对应权限声明。

八、 多平台构建、调试与性能分析

除了基础的 ace run 命令，开发者还可以使用更精细的构建指令，并结合平台特定的调试工具来排查问题。

构建与调试指令：

# 构建 Android 调试包
ace build android --mode debug

# 构建 iOS 应用（需指定 Scheme）
ace build ios --scheme YourAppScheme

# 指定设备 ID 运行调试
ace run android --device [设备ID]

在调试过程中，可以使用 @arkui-x/debug 模块输出跨平台日志，并在 DevEco Studio 中切换平台预览模式。上线前，建议通过 DevEco Profiler 分析各平台的性能差异，并定期执行 ace lint 进行代码规范检查。

1. 优先使用声明式布局：替代传统的命令式 UI 操作，利用框架的差分更新算法保证多端性能。
2. 样式统一管理：使用 @Styles 或媒体查询（Media Query）来统一多平台样式，并适配不同分辨率与异形屏（如使用 SafeArea 组件避开刘海屏）。
3. 复杂逻辑原生复用：对于极度复杂的业务逻辑，建议通过 Native C++ 实现跨平台复用，以获得最佳性能。
4. 原生能力桥接：对于 ArkUI-X 尚未内置的原生能力，通过 ArkUI-X Bridge 桥接实现，并在鸿蒙预览环境中做好 Bridge 调用的异常保护。