ArkUI-X概覽

項目介紹

ArkUI是一套構建分布式應用的聲明式UI開發框架。它具備簡潔自然的UI信息語法、豐富的UI組件、多維的狀態管理，以及實時界面預覽等相關能力，幫助您提升應用開發效率，并能在多種設備上實現生動而流暢的用戶體驗。

ArkUI-X進一步將ArkUI擴展到了多個OS平臺：目前支持OpenHarmony、HarmonyOS、Android、 iOS，后續會逐步增加更多平臺支持。開發者基于一套主代碼，就可以構建支持多平臺的精美、高性能應用。

熟悉鴻蒙開發指導文檔：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

關鍵特征

ArKUI跨平臺框架關鍵特征如下：

1. 簡潔自然的聲明式語法。
2. 高效的渲染管線以及平臺一致性的渲染機制。
3. 高效的方舟編譯器以及運行時。
4. 統一的跨平臺API能力集以及擴展機制。
5. 動態化特性

技術架構

ArkUI跨平臺框架整體架構如下圖所示。

簡介

本文檔描述ArkUI開發框架跨平臺運行能力相關的總體技術方案。

范圍

ArkUI是面向全設備的UI開發框架，已通過OpenHarmony代碼倉開源，其關鍵組成包括：

• 開發模型;
• 應用界面&交互;
• 擴展機制-使能三方組件&平臺API擴展機制。

ArkUI-X旨在將ArkUI開發框架擴展至其他OS平臺（Android/iOS/Windows等），使開發者能夠基于ArkUI開發框架，復用絕大部分的應用代碼（UI以及主要應用邏輯），即可部署到不同OS平臺上。

假設和約束

本文提到的跨平臺是指UI部分的跨平臺，其UI代碼可以重用，其它應用對平臺依賴的能力，需要應用層面進行適配，或通過JS API封裝機制（NAPI），進行實現暴露到JS層。

涉及平臺能力的JS API（比如網絡、存儲等）請參考OpenHarmony中的定義，需要通過在不同平臺的封裝實現達到復用的目的。

本文主要是通用方案設計說明，并以Android平臺做為示例說明，其他平臺的基本設計思路類似，但相關設計需進一步細化補充。

總體視圖

從設計之初，跨平臺就作為ArkUI最基本的設計目標之一，當前已支持基礎的跨平臺架構。相關的設計思路如下：

1. 采用 C++ 編寫整體后端引擎代碼，保持在多平臺的可移植性，最小化平臺依賴，降低平臺移植成本。
2. 整體繪制采用自渲染機制，降低平臺依賴，同時進一步提升繪制效果的一致性。
3. 抽象出平臺適配層以及平臺橋接層，以便不同平臺的適配。

模塊功能介紹

ArkUI主要包括以下幾個模塊：

1. 研發模型，兼容OpenHarmony應用的Stage開發模型，支持基于ArkTS的聲明式開發范式，可跨平臺。
2. 聲明式UI后端引擎，包括布局，渲染，C++ UI組件，事件機制等，可跨平臺。
3. API擴展機制，基于NAPI機制，可跨平臺。 不同平臺需要各自擴展具體的API實現。
4. 工具鏈/SDK, 工具鏈可跨平臺，SDK需基于不同平臺構建。

另外，ArkUI依賴的ArkTS引擎以及圖形引擎，也可跨平臺。

ArkUI聲明式UI后端引擎，主要完成整體pipeline流程控制、視圖更新、布局系統、多頁面管理、事件分發和回調、焦點管理、動畫機制、主題機制、資源管理/緩存/provider等。 其中的UI組件，主要通過顯示相關組件細粒度化，動畫、事件、焦點等機制組件化，滿足適配不同前端所需要的靈活性。

整體的跨平臺需求，就是擴展ArkUI開發框架到其他OS平臺，幫助開發者降低多平臺應用開發成本。

通過ACE Tools命令行工具創建跨平臺應用工程，開發者基于一套主代碼，就可以構建支持多平臺的精美、高性能應用。

方案設計

跨平臺應用包結構設計

跨平臺應用目錄結構，包含一套為ArkUI-X開發者提供的應用工程模板，提供構建OpenHarmony應用、Android應用、iOS應用的能力。應用工程包結構設計如下：

ArkUI-X應用工程
  ├── .arkui-x
  │   ├── android                 // Android平臺相關代碼
  │   └── ios                     // iOS平臺相關代碼
  ├── .hvigor
  ├── .idea
  ├── AppScope
  ├── entry
  ├── hvigor
  ├── oh_modules
  ├── build-profile.json5
  ├── hvigorfile.ts
  ├── local.properties
  └── oh-package.json5

ArkUI-X應用目錄結構設計思想是從OpenHarmony應用工程原生支持跨平臺角度出發，在OpenHarmony應用工程之上疊加Android和iOS應用工程，ArkTS代碼和resources資源編輯仍在OpenHarmony側完成，Native代碼在各自平臺應用工程中完成。詳細包結構設計。

ArkUI-X應用工程結構說明

簡介

本文檔配套ArkUI-X，將OpenHarmony ArkUI開發框架擴展到不同的OS平臺，比如Android和iOS平臺，讓開發者基于ArkUI，可復用大部分的應用代碼（UI以及主要應用邏輯）并可以部署到相應的OS平臺，降低跨平臺應用開發成本。

應用工程目錄結構介紹

跨平臺應用工程目錄結構，包含一套為ArkUI開發者提供的應用工程模板，提供構建OpenHarmony應用，HarmonyOS應用，Android應用，iOS應用的能力。

ArkUI-X應用工程目錄結構
  ├── .arkui-x
  │   ├── android                 // Android平臺相關代碼
  │   └── ios                     // iOS平臺相關代碼
  ├── AppScope
  ├── entry
  ├── hvigor
  ├── build-profile.json5
  ├── hvigorfile.ts
  ├── hvigorw
  ├── hvigorw.bat
  ├── local.properties
  └── oh-package.json5

此應用目錄結構設計思想是從OpenHarmony應用工程原生支持跨平臺角度出發，在OpenHarmony應用工程之上疊加Android和iOS應用工程，ArkTS代碼和resources資源在OpenHarmony側完成編譯，Native代碼仍在各自平臺應用工程中完成編譯。

編譯構建說明

• ArkTS源碼

ArkTS源碼通過OpenHarmony SDK工具鏈生成abc（Ark Byte Code），并分別拷貝到Android和iOS應用工程，作為平臺應用資源進行管理。

• ArkUI應用資源

ArkUI Resources資源也通過OpenHarmony SDK工具鏈進行編譯，編譯后的ArkUI資源分別拷貝到Android和iOS應用工程，作為平臺應用資源進行管理。

• ArkUI框架資源

ArkUI框架資源隨ArkUI-X SDK進行發布，應用構建時會自動打包到ArkUI-X應用中，可保證ArkUI-X應用在各平臺上UX渲染一致性。

綜上所述，Android平臺上通過assets管理ArkTS編譯產物、ArkUI應用資源和ArkUI框架資源，iOS平臺上通過Bundle Resources管理ArkTS編譯產物、ArkUI應用資源和ArkUI框架資源。

Android應用工程結構

ArkUI-X Android應用工程
├── app
│   ├── libs
│   │   ├── arkui_android_adapter.jar                   // ArkUI-X跨平臺適配層，在SDK中發布
│   │   └── arm64-v8a
│   │       └── libarkui_android.so                     // ArkUI-X跨平臺引擎庫，在SDK中發布
│   │       └── libhilog.so                             // ArkUI-X日志庫，在SDK中發布
│   │       └── libresourcemanager.so                   // ArkUI-X資源管理庫，在SDK中發布
│   ├── src
│   │   ├── androidTest
│   │   ├── main
│   │   │   ├── assets
│   │   │   │   └── arkui-x                             // ArkUI應用編譯后的字節碼文件和Resources，作為資源文件存放在assets/arkui-x中
│   │   │   │       ├── entry                           // ArkUI單個模塊的編譯結果
│   │   │   │       │   ├── ets                         // ArkUI單個模塊代碼的編譯結果：包括字節碼文件以及sourceMap文件
│   │   │   │       │   │   ├── sourceMaps.map
│   │   │   │       │   │   └── modules.abc
│   │   │   │       │   ├── resources.index             // ArkUI單個模塊資源的編譯結果：resources資源的編譯結果
│   │   │   │       │   ├── resources                   // resources資源中的rawfile資源，不會進行編譯。
│   │   │   │       │   └── module.json
│   │   │   │       ├── entry_test                      // ohosTest，僅僅Debug模式構建包含。
│   │   │   │       └── systemres                       // ArkUI框架自帶的系統資源
│   │   │   ├── java/com/example/mayapp
│   │   │   │   ├── MyApplication.java                  // 基于StageApplication擴展MyApplication
│   │   │   │   └── EntryEntryAbilityActivity.java      // 基于StageActivity擴展EntryEntryAbilityActivity
│   │   │   ├── res
│   │   │   └── AndroidManifest.xml
│   │   └── test
│   ├── build.gradle
│   └── proguard-rules.pro
├── gradle/wrapper
├── build.gradle
├── gradle.properties
├── gradlew
├── gradlew.bat
└── settings.gradle

iOS應用工程結構

ArkUI-X iOS應用工程
├── app.xcodeproj
│   ├── project.xcworkspace
│   ├── xcuserdata
│   └── project.pbxproj
├── app
│   ├── Assets.xcassets
│   ├── Base.Iproj
│   ├── AppDelegate.h
│   ├── AppDelegate.m                               // 應用入口, 驅動StageApplication的生命周期
│   ├── EntryEntryAbilityViewController.h           
│   ├── EntryEntryAbilityViewController.m           // 基于StageViewController擴展EntryEntryViewController
│   ├── Info.plist
│   └── main.m
├── arkui-x                                         // ArkUI應用編譯后的字節碼文件和Resources，作為資源文件存放在assets/arkui-x中
│   ├── entry                                       // ArkUI單個模塊的編譯結果
│   │   ├── ets                                     // ArkUI單個模塊代碼的編譯結果：包括字節碼文件以及sourceMap文件
│   │   │   ├── sourceMaps.map
│   │   │   └── modules.abc
│   │   ├── resources.index                         // ArkUI單個模塊資源的編譯結果：resources資源的編譯結果
│   │   ├── resources                               // resources資源中的rawfile資源，不會進行編譯。
│   │   └── module.json
│   ├── entry_test                                  // ohosTest，僅僅Debug模式構建包含。
│   └── systemres                                   // ArkUI框架自帶的系統資源
└── frameworks                                      // ArkUI跨平臺Framework動態庫：包含ArkUI-X的框架以及插件

跨平臺框架構建系統

ArkUI-X編譯構建提供了一套基于GN和Ninja的編譯構建框架，基礎構建基于OpenHarmony的build倉，并在OpenHarmony構建基礎上新增Android和iOS編譯工具鏈，以支持ArkUI跨平臺SDK編譯輸出。

跨平臺SDK結構設計

跨平臺SDK主要用于支持ACE Tools命令行跨平臺應用構建和DevEco StudioAndroid StudioXcode集成跨平臺應用開發。內容范圍主要包括：

1. 提供ArkUI跨平臺開發框架基礎引擎動態庫，API插件動態庫。
2. 提供ArkUI跨平臺應用構建命令行工具。
3. 提供ArkUI組件渲染一致性系統資源包，應用資源編譯工具。

ArkUI-X SDK組成結構如下：

arkui-x
  ├── engine                   // ArkUI-X的引擎庫
  │   ├── lib                  // ArkUI-X的引擎庫：包括Android平臺及架構的動態庫
  │   ├── framework            // ArkUI-X的引擎庫：包括iOS平臺及架構的Framework庫
  │   ├── xcframework          // ArkUI-X的引擎庫：包括iOS平臺及架構的XCFramework庫
  │   ├── ets                  // ArkUI-X增量接口，比如：@arkui-x.bridge
  │   ├── apiConfig.json       // engine庫配置文件，用于IDE和ACE Tools解析，以支持應用構建按需打包。
  │   └── systemres            // ArkUI-X框架自帶的資源
  ├── plugins                  // ArkUI-X官方提供的插件庫
  │   ├── component            // ArkUI組件插件庫，apiConfig.json
  │   └── api                  // @ohos接口插件庫，apiConfig.json
  ├── toolchains               // ArkUI-X應用開發工具，比如：ACE Tools。
  ├── sdkConfig.json           // 增量d.ts路徑和接口前綴配置
  ├── arkui-x.json             // SDK管理配置，流水線自動生成
  └── NOTICE.txt

操作系統抽象層

基于C++實現的OS Abstract Layer (下文縮寫為OSAL)，屏蔽不同平臺的OS相關的實現，主要包含功能列表：

• 日志、Trace抽象層
• 網絡接口抽象層
• 文件/資源讀寫抽象層
• 基礎線程抽象層
• 系統資源管理抽象及實現
• 系統Prop配置讀取抽象層
• 打點能力抽象層

以Log調用流程為例，整體交互流程如下：

如上述流程，Core模塊直接使用Base提供的接口，Base模塊對接口進行定義，對于依賴平臺的能力，在編譯期就選擇了對應OS的平臺抽象層OSAL。運行時，直接通過OSAL的實現，調用到具體平臺相關的庫中。

跨平臺啟動入口

開發框架對應平臺語言實現的Entrance，提供不同平臺的基礎入口環境，跨平臺啟動入口功能列表：

• 提供多個平臺的加載入口，如OpenHarmony側為一個Ability，Android側為一個Activity。
• 對接不同平臺的生命周期、事件輸入、Vsync。
• 對接不同平臺的窗口系統、硬件渲染加速。
• 對接不同平臺的應用信息。
• 不同平臺的原生語言轉換到統一的C++后端，公共代碼復用。

以Android的啟動流程為例，整體交互流程如下：

Stage模型下，Ability聲明周期的入口為StageAbility，生命周期一直會通知到JsAbility，執行用戶的生命周期回調方法，UI的頁面是在onWindowStageCreated的生命周期中，調用Window的loadContent接口進行加載，創建ArkUI的實例并初始化渲染管線，將頁面進行渲染顯示。

跨平臺能力橋接

跨平臺能力橋接包含框架內部需要用到的不同的平臺能力模塊，如：剪切板、輸入法、視頻等，提供基礎能力模塊的定義，不同平臺按照定義實現對應的功能模塊。功能列表：

• 剪切板抽象接口，及不同平臺的實現。
• 輸入法抽象接口，及不同平臺的實現。
• 視頻媒體等抽象接口，及不同平臺的實現。
• 其它框架內部需要用到的不同的平臺能力模塊。

以剪切板ClipBoard為例，整體交互流程如下：

如上圖，例如在框架核心層的TextField組件中，需要用到剪切板的能力，通過Proxy創建具體的ClipBoard實現，返回抽象的ClipBoard接口。在組件實現層即可實現平臺無關的調用。以Android平臺為例，GetData的調用會通過JNI調用到平臺實現的Plugin中，然后Plugin通過訪問剪切板服務實現對應的功能。

API擴展機制

1、JS API擴展機制，用于Native接口能力暴露到JS層，該機制直接復用OpenHarmony上的統一封裝機制，擴展API （C++實現），并實現部分內置API，NAPI的整體結構如下圖。

對于不同平臺， JS API需要遵循OpenHarmony的API定義 ，在不同平臺上通過API擴展機制進行擴展。

跨平臺命令行工具ACE Tools

ACE Tools命令行工具作為ArkUI-X跨平臺應用構建工具，具有創建/編譯/安裝/運行調試OpenHarmony、Android和iOS應用的能力。

`HarmonyOS與OpenHarmony鴻蒙文檔籽料：mau123789是v直接拿`

ACE Tools代碼結構
 cli
  ├─node_modules
  ├─src
  │  ├─ace-build                 // 構建跨平臺應用安裝包
  │  │  ├─ace-compiler
  │  │  └─ace-packager
  │  ├─ace-check                 // 查驗ArkUI跨平臺應用開發依賴的的庫和工具鏈是否完整
  │  ├─ace-clean                 // 清理跨平臺應用編譯結果
  │  ├─ace-config                // 配置ArkUI跨平臺應用開發環境
  │  ├─ace-create                // 創建ArkUI跨平臺應用工程
  │  │  ├─aar
  │  │  ├─ability
  │  │  ├─component
  │  │  ├─framework
  │  │  ├─module
  │  │  └─project
  │  ├─ace-devices               // 列出當前PC所鏈接的各平臺設備
  │  ├─ace-install               // 將跨平臺應用安裝到連接的設備上
  │  ├─ace-launch                // 在設備上運行跨平臺應用
  │  ├─ace-log                   // 滾動展示正在運行的跨平臺應用的日志
  │  ├─ace-run                   // 運行跨平臺應用包
  │  ├─ace-test                  // 執行測試代碼
  │  ├─ace-uninstall             // 將跨平臺應用從設備上卸載
  │  ├─bin                       // 命令行入口腳本
  │  └─util
  └─templates                    // 跨平臺應用工程模板

審核編輯 黃宇