diff --git a/en/ArkUI-X-Overview.md b/en/ArkUI-X-Overview.md index 9ca3bfd835926255700e7fa3450c6d7bfe59030d..657b5cc3ddce21e699e2f2edc3b4cbd699fb139e 100644 --- a/en/ArkUI-X-Overview.md +++ b/en/ArkUI-X-Overview.md @@ -1,66 +1,63 @@ -# ArkUI-X Project +# ArkUI-X Overview ## Introduction -ArkUI is a declarative UI development framework for building distributed applications. It provides simple and natural UI syntax, diverse array of UI components, multi-dimensional status management, and real-time UI preview tools, helping you improve application development efficiency and achieve vivid and smooth user experience across devices. +ArkUI is a declarative UI development framework for building distributed applications. It provides simple and natural UI syntax, diverse UI components, multi-dimensional status management, and real-time UI preview capabilities, helping you improve application development efficiency and achieve vivid and smooth user experience across devices. For details, see [ArkUI Overview](https://gitee.com/openharmony/docs/blob/master/en/application-dev/ui/arkui-overview.md). -The ArkUI-X project further extends the ArkUI framework to multiple OS platforms. Currently, it supports OpenHarmony, Android, and iOS. More OS platforms will be supported in the future. The ArkUI-X project allows you to develop high-performance applications supporting multiple platforms by using a set of main code. +ArkUI-X further extends the ArkUI framework to multiple OS platforms. Currently, it supports OpenHarmony, HarmonyOS, Android, and iOS. More OS platforms will be supported in the future. With ArkUI-X, you can use a set of main code to develop high-performance applications supporting multiple platforms. -## Key Characteristics +## Key Features -ArKUI-X shines in the following key characteristics: +The ArkUI-X framework has the following key features: -1. Simple and natural declarative syntax -2. Efficient rendering pipeline and platform-specific rendering mechanism -3. High-performance ArkCompiler and runtime -4. Unified cross-platform API capability set and extension mechanism +- Concise and natural declarative syntax. +- Efficient rendering pipeline and platform-consistent rendering mechanism. +- Efficient ArkCompiler and Runtime. +- Unified cross-platform API capability set and extension mechanism. ## Technical Architecture -Below is the overall architecture of ArkUI-X. For details about the design, see [ArkUI Cross-Platform Design](./framework-dev/design/design-overview.md). +The figure below shows the overall architecture of the ArkUI-X framework. For details about the design, see [ArkUI Cross-Platform Design](./framework-dev/design/design-overview.md). -ArkUI -X Architecture +ArkUI-X architecture -## Using ArkUI-X +## Getting Started -* [Application Development](application-dev/quick-start/start-overview.md) +* [Getting Started for Application Development](application-dev/quick-start/start-overview.md) -* [Framework Development](framework-dev/quick-start/start-overview.md) +* [Getting Started for Framework Development](framework-dev/quick-start/start-overview.md) -## Code Repository Addresses +## Code Repository Address -ArkUI-X main repository: https://gitee.com/arkui-x +ArkUI-X project: https://gitee.com/arkui-x ## ArkUI-X Documentation -[Chinese version](../zh-cn/readme.md) +[Chinese version](../zh-cn/README.md) -[English version](./readme.md) +[English version](README.md) -## Evolution Roadmap -[ArkUI-X Roadmap](roadmap/ArkUI-X-roadmap.md) - -## Source Code Downloading +## Source Code For details about how to obtain the source code of ArkUI-X, see [ArkUI-X Source Code](https://gitee.com/arkui-x/manifest/blob/master/README-EN.md). ## Hands-On Tutorials -[ArkUI-X App Samples](https://gitee.com/arkui-x/samples) +[Samples](https://gitee.com/arkui-x/samples) ## How to Participate For details about how to join the ArkUI-X community, see [ArkUI-X Community](https://gitee.com/arkui-x/community). -For details about how to contribute, see [How to Contribute](contribute/README.md). +For details about how to contribute, see [Contribution Guide](contribute/README.md). ## License Agreement ArkUI-X complies with Apache License Version 2.0. For details, see the LICENSE in each repository. -ArkUI-X uses third-party open-source software and licenses. For details, see [Open-Source Software and License Notice](contribute/open-source-software-and-license-notice.md). +Third-party open-source software referenced by ArkUI-X complies with their respective original license. -## Contact Info +## Contact Information For details, see [Communication in Community](contribute/communication-in-community.md). diff --git a/en/readme.md b/en/README.md similarity index 100% rename from en/readme.md rename to en/README.md diff --git a/en/application-dev/quick-start/figures/StageiOS.png b/en/application-dev/quick-start/figures/StageiOS.png new file mode 100644 index 0000000000000000000000000000000000000000..e6c602624b468a4d6f755d3fb27e67faaa26f2d8 Binary files /dev/null and b/en/application-dev/quick-start/figures/StageiOS.png differ diff --git a/en/application-dev/quick-start/figures/stage_android.png b/en/application-dev/quick-start/figures/stage_android.png new file mode 100644 index 0000000000000000000000000000000000000000..b6eda7c4606ffe490e4b48ed8434aaecc3d472ce Binary files /dev/null and b/en/application-dev/quick-start/figures/stage_android.png differ diff --git a/en/application-dev/quick-start/platform-bridge-introduction.md b/en/application-dev/quick-start/platform-bridge-introduction.md new file mode 100644 index 0000000000000000000000000000000000000000..f2c6618528a951cf121684165cba75278764178b --- /dev/null +++ b/en/application-dev/quick-start/platform-bridge-introduction.md @@ -0,0 +1,53 @@ +# Platform Bridge (@arkui-x.bridge) + +## Overview + +Platform bridge is used for interaction between the client (ArkUI) and the platform (Android or iOS). It allows you to exchange messages between ArkUI and the platform, call platform APIs on ArkUI, and call ArkUI APIs on the platform. + +For example, ArkTS and Java code do not support bidirectional invoking. To implement interaction between ArkTS and Java code, ArkTS code must interact with C++ code, and then the C++ code interacts with Java code, and vice versa. However, this looks like direct interaction between ArkTS and Java code from the perspective of developers. + +This top describes how to compile custom Android and iOS platform code through platform bridge. For details about the usage on ArkUI, Android, and iOS, see [Bridge API](../reference/apis/js-apis-bridge.md), [BridgePlugin](../reference/arkui-for-android/BridgePlugin.md), and [BridgePlugin](../reference/arkui-for-ios/BridgePlugin.md), respectively. + + +## Use Cases and Capabilities + +### Use Cases + +Platform bridge is mainly used in the following scenario: An application need to reuse platform code, but OpenHarmony does not provide corresponding cross-platform APIs (excluding UI-related APIs). + +Platform bridge can be used in the following scenarios: + +- Transmitting data such as JSON data and images between ArkUI and the platform. +- Calling platform APIs on ArkUI, for example, calling APIs to obtain the battery level of an Android or iOS device or reusing third-party libraries on the platform. +- Calling ArkUI APIs on the platform, for example, reusing third-party libraries of JavaScript. + +> **NOTE** +> +> Platform bridge allows ArkUI to call Android Java APIs and iOS Objective-C APIs. OpenHarmony also provides [APIs with cross-platform support](../reference/apis/README.md) to implement some platform-related features. + + +### Data Types Supported + +Platform bridge transfers data through serialization, encoding, and decoding in JSON format. Basic data types, array types, and structured data are supported, as described in the table below. + +| ArkTS | Java | Objective-C | +| --------------------- | ------------------- | ------------------------- | +| string | java.lang.String | NSString | +| number(32bit integer) | java.lang.Integer | NSNumber numberWithInt | +| number(double) | java.lang.Double | NSNumber numberWithDouble | +| boolean | java.lang.Boolean | NSNumber numberWithBool | +| null | null | NSNull | +| Array\ | java.util.ArrayList | NSArray | +| Map\ | java.util.HashMap | NSDictionary | + +> **NOTE** +> +> S indicates the string, number, or boolean type. T indicates S and its corresponding array type. +> The Map type supports only keys of the string type and is used only in return values. + + +## Developer Guide + +[Platform Bridge Development (Android)](../tutorial/how-to-use-bridge-on-android.md) + +[Platform Bridge Development (iOS)](../tutorial/how-to-use-bridge-on-ios.md) \ No newline at end of file diff --git a/en/application-dev/quick-start/sdk-structure-guide.md b/en/application-dev/quick-start/sdk-structure-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..9f89b135b04a30d6be8dfb227062fe752a14dbdc --- /dev/null +++ b/en/application-dev/quick-start/sdk-structure-guide.md @@ -0,0 +1,593 @@ +# ArkUI-X SDK Directory Structure + +# Overview + +ArkUI-X extends the OpenHarmony ArkUI development framework to different OS platforms like Android and iOS. This way, you can reuse most of the application code (UI and main application logic) based on ArkUI and deploy the code on the corresponding OS platform. + +# Obtaining the SDK + +For details about how to obtain the SDK, see [ArkUI-X Release Notes](../../release-notes/README.md). + +# Development Tool Integration + +* ACE Tools integration + + ACE Tools is a command line tool for building ArkUI cross-platform applications. By integrating the ArkUI-X SDK, ACE Tools can create, compile, and build OpenHarmony/HarmonyOS, Android, and iOS applications. + +* DevEco Studio integration + + DevEco Studio is an Integrated Development Environment (IDE) for building ArkUI cross-platform applications. By integrating the ArkUI-X SDK, DevEco Studio supports one-click building of OpenHarmony/HarmonyOS, Android, and iOS applications. + +# ArkUI-X SDK Building Rules + +## Naming Rules for SDK Packages + +The SDK package built is named in the following format: + +``` +path_osType_cpuArchitectureType_version_releaseType.zip +``` + +**Table 1** SDK rule fields + +| Field| Description.| +| --- | --- | +| path | The value is the **path** tag value in the **arkui-x.json** file in the SDK root directory.| +| osType| The value can be **windows**, **darwin**, or **linux**.| +| cpuArchitectureType| The value can be **x64** (x86 architecture) or **arm64** (Arm architecture).| +| version| The build version must comply with the OpenHarmony SDK version rule.| +| releaseType | The value can be **Alpha**, **Beta**, or **Release**. A digit can be appended to **releaseType** to identify the number of iterations, for example, Beta1.| + +**Example** + +arkui-x_windows_x64_1.0.0.0_Alpha.zip + +## Internal Structure of the SDK Package +The following uses the ArkUI-X SDK package on macOS as an example to describe the SDK directory structure and content specifications. For details, see [ArkUI-X SDK Content Specifications](#arkui-x-sdk-content-specifications). + +``` +arkui-x_darwin_x64_1.0.0.0_Alpha.zip +└── arkui-x + ├── engine // ArkUI-X engine library + │ ├── lib // Dynamic library of the Android platform and architecture + │ ├── framework // Framework libraries of the iOS platform and architecture + │ ├── xcframework // XCFramework libraries of the iOS platform and architecture + │ ├── ets // ArkUI-X incremental APIs, for example, @arkui-x.bridge + │ ├── apiConfig.json // Engine library configuration file, which is parsed by DevEco Studio and ACE Tools to support on-demand packing during application build + │ └── systemres // System resources provided by the ArkUI-X framework + ├── plugins // Plug-in libraries provided by ArkUI-X + │ ├── component // ArkUI component plug-in libraries + │ └── api // @ohos API plug-in library and the apiConfig.json file + ├── toolchains // ArkUI-X application development tool, for example, ACE Tools + ├── sdkConfig.json // Incremental d.ts path and API prefix configuration + ├── arkui-x.json // SDK management configuration, which is automatically generated by the pipeline + └── NOTICE.txt +``` + +### Directory Structure of the ArkUI-X SDK Engine + +The minimum dependency set for building an ArkUI-X application is stored in the **arkui-x_darwin_x64_1.0.0.0_Alpha.zip/arkui-x/engine** directory. + +``` +engine +├── lib +│ ├── include +│ ├── arkui +│ │ ├── arkui_android_adapter.jar +│ │ ├── android-arm +│ │ ├── android-arm-profile +│ │ ├── android-arm-release +│ │ ├── android-arm64 +│ │ ├── android-arm64-profile +│ │ ├── android-arm64-release +│ │ └── android-x86_64 +│ ├── third_party // The internal directory is the same as that of ArkUI. +│ └── utils // The internal directory is the same as that of ArkUI. +├── framework +│ ├── arkui +│ │ ├── ios-arm64 +│ │ ├── ios-arm64-profile +│ │ ├── ios-arm64-release +│ │ ├── ios-arm64-simulator +│ │ └── ios-x86_64-simulator +│ ├── third_party +│ └── utils +├── xcframework +│ ├── arkui +│ │ ├── ios +│ │ │ └── libarkui_ios.xcframework +│ │ │ ├── Info.plist +│ │ │ ├── ios-arm64 +│ │ │ └── ios-arm64_x86_64-simulator +│ │ ├── ios-profile +│ │ │ └── libarkui_ios.xcframework +│ │ │ ├── Info.plist +│ │ │ ├── ios-arm64 +│ │ │ └── ios-arm64_x86_64-simulator +│ │ └── ios-release +│ │ └── libarkui_ios.xcframework +│ │ ├── Info.plist +│ │ ├── ios-arm64 +│ │ └── ios-arm64_x86_64-simulator +│ ├── third_party // The internal directory is the same as that of ArkUI. +│ └── utils // The internal directory is the same as that of ArkUI. +├── ets +│ └── @arkui-x.bridge.d.ts +├── apiConfig.json +└── systemres +``` + +### Directory Structure of the ArkUI-X SDK Plug-Ins + +The on-demand plug-in libraries for building an ArkUI-X application are stored in the **arkui-x_darwin_x64_1.0.0.0_Alpha.zip/arkui-x/plugins** directory. + +``` +plugins +├── component +│ ├── lib +│ │ ├── include +│ │ └── ${ui-name} // One directory for one UI component. +│ │ ├── ${ui-name}.jar +│ │ ├── android-arm +│ │ ├── android-arm-profile +│ │ ├── android-arm-release +│ │ ├── android-arm64 +│ │ ├── android-arm64-profile +│ │ ├── android-arm64-release +│ │ │ └── lib${ui-name}.so +│ │ └── android-x86_64 +│ ├── framework +│ │ ├── ios-arm64 +│ │ ├── ios-arm64-profile +│ │ │ └── lib${ui-name}.framework +│ │ ├── ios-arm64-release +│ │ ├── ios-arm64-simulator +│ │ └── ios-x86_64-simulator +│ ├── xcframework +│ │ ├── ios +│ │ │ └── lib${ui-name}.xcframework +│ │ │ ├── Info.plist +│ │ │ ├── ios-arm64 +│ │ │ └── ios-arm64_x86_64-simulator +│ │ ├── ios-profile +│ │ │ └── lib${ui-name}.xcframework +│ │ │ ├── Info.plist +│ │ │ ├── ios-arm64 +│ │ │ └── ios-arm64_x86_64-simulator +│ │ └── ios-release +│ │ └── lib${ui-name}.xcframework +│ │ ├── Info.plist +│ │ ├── ios-arm64 +│ │ └── ios-arm64_x86_64-simulator +│ └── apiConfig.json +└── api + ├── lib + │ ├── include + │ └── ${module-name}_${submodule-name} // One directory for one API module. + │ ├── ${module-name}_${submodule-name}.jar + │ ├── android-arm + │ ├── android-arm-profile + │ ├── android-arm-release + │ ├── android-arm64 + │ ├── android-arm64-profile + │ ├── android-arm64-release + │ │ └── lib${module-name}_${submodule-name}.so + │ └── android-x86_64 + ├── framework + │ ├── ios-arm64 + │ ├── ios-arm64-profile + │ │ └── lib${module-name}_${submodule-name}.framework + │ ├── ios-arm64-release + │ ├── ios-arm64-simulator + │ └── ios-x86_64-simulator + ├── xcframework + │ ├── ios + │ │ └── lib${module-name}_${submodule-name}.xcframework + │ │ ├── Info.plist + │ │ ├── ios-arm64 + │ │ └── ios-arm64_x86_64-simulator + │ ├── ios-profile + │ │ └── lib${module-name}_${submodule-name}.xcframework + │ │ ├── Info.plist + │ │ ├── ios-arm64 + │ │ └── ios-arm64_x86_64-simulator + │ └── ios-release + │ └── lib${module-name}_${submodule-name}.xcframework + │ ├── Info.plist + │ ├── ios-arm64 + │ └── ios-arm64_x86_64-simulator + └── apiConfig.json +``` + +### **arkui-x.json** Configuration Description + +```json +{ + "apiVersion": "10", + "displayName": "ArkUI-X", + "meta": { + "metaVersion": "1.0.0" + }, + "path": "arkui-x", + "releaseType": "Beta", + "version": "1.0.0.0" +} +``` + +Some fields in the file are described as follows: + +- **apiVersion**: version of the OpenHarmony SDK on which the ArkUI-X SDK depends. +- **displayName**: display name of the ArkUI-X SDK in DevEco Studio. +- **path**: path of the downloaded ArkUI-X SDK. +- **version**: ArkUI-X SDK build version, which is used for test. + +# ArkUI-X SDK Content Specifications + +## Windows + +### Directory Structure of the ArkUI-X SDK Engine + +* **lib** directory: cross-platform implementation of the ArkUI-X basic framework. +* **ets** directory: definition of ArkUI-X unique APIs and configuration description of basic APIs related to the ArkUI cross-platform stage model. +* **systemres** directory: system resource package for ArkUI rendering consistency. + +``` +arkui-x_windows_x64_1.0.0.0_Alpha.zip/arkui-x/engine +├── lib // ArkUI cross-platform engine and platform adaptation layer. +│ ├── include // NAPIs and auxiliary C APIs. +│ ├── arkui +│ │ ├── arkui_android_adapter.jar +│ │ ├── android-arm +│ │ ├── android-arm-profile +│ │ ├── android-arm-release +│ │ ├── android-arm64 +│ │ ├── android-arm64-profile +│ │ ├── android-arm64-release +│ │ │ └── libarkui_android.so // ArkUI cross-platform engine, including ArkUI, NAPI, and ARK. +│ │ └── android-x86_64 +│ ├── third_party +│ └── utils +├── ets // Definition of the ArkUI-X unique APIs and configuration description of the basic APIs related to the ArkUI cross-platform stage model. +│ └── @arkui-x.bridge.d.ts +├── apiConfig.json +└── systemres // System resource package for ArkUI component rendering consistency. +``` + +### Directory Structure of the ArkUI-X SDK Plug-Ins + +* **component** directory: dynamic libraries of ArkUI component plug-ins. +* **api** directory: dynamic libraries of the ArkTS API plug-ins. + +``` +arkui-x_windows_x64_1.0.0.0_Alpha.zip/arkui-x/plugins +├── component // Dynamic library of ArkUI component plug-ins. +│ ├── lib +│ │ ├── include +│ │ └── ${ui-name} +│ │ ├── ${ui-name}_android_adapter.jar // Dependent Android APIs for the implementation of some components. +│ │ ├── android-arm +│ │ ├── android-arm-profile +│ │ ├── android-arm-release +│ │ ├── android-arm64 +│ │ ├── android-arm64-profile +│ │ ├── android-arm64-release +│ │ │ └── lib${ui-name}.so // Implementation of ArkUI components. +│ │ └── android-x86_64 +│ └── apiconfig.json // Configuration of the cross-platform implementation of ArkUI components. +└── api // Dynamic library of ArkTS API plug-ins. + ├── lib + │ ├── include + │ └── ${module-name}_${submodule-name} + │ ├── ${module-name}_${submodule-name}.jar // Independent Android APIs for the implementation of some ArkTS APIs. + │ ├── android-arm + │ ├── android-arm-profile + │ ├── android-arm-release + │ ├── android-arm64 + │ ├── android-arm64-profile + │ ├── android-arm64-release + │ │ └── lib${module-name}_${submodule-name}.so // ArkTS API implementation. + │ └── android-x86_64 + └── apiConfig.json // Configuration of the cross-platform implementation of ArkTS @ohos APIs. +``` + +## Linux + +### Directory Structure of the ArkUI-X SDK Engine + +* **lib** directory: cross-platform implementation of the ArkUI-X basic framework. +* **ets** directory: definition of ArkUI-X unique APIs and configuration description of basic APIs related to the ArkUI cross-platform stage model. +* **systemres** directory: system resource package for ArkUI rendering consistency. + +``` +arkui-x_linux_x64_1.0.0.0_Alpha.zip/arkui-x/engine +├── lib // ArkUI cross-platform engine and platform adaptation layer. +│ ├── include // NAPIs and auxiliary C APIs. +│ ├── arkui +│ │ ├── arkui_android_adapter.jar // ArkUI adaptation layer for the Android platform. +│ │ ├── android-arm +│ │ ├── android-arm-profile +│ │ ├── android-arm-release +│ │ ├── android-arm64 +│ │ ├── android-arm64-profile +│ │ ├── android-arm64-release +│ │ │ └── libarkui_android.so // ArkUI cross-platform engine, including ArkUI, NAPI, and ARK. +│ │ └── android-x86_64 +│ ├── third_party +│ └── utils +├── ets // Definition of the ArkUI-X unique APIs and configuration description of the basic APIs related to the ArkUI cross-platform stage model. +│ └── @arkui-x.bridge.d.ts +├── apiConfig.json +└── systemres // System resource package for ArkUI component rendering consistency. +``` + +### Directory Structure of the ArkUI-X SDK Plug-Ins + +* **component** directory: dynamic libraries of ArkUI component plug-ins. +* **api** directory: dynamic libraries of the ArkTS API plug-ins. + +``` +arkui-x_linux_x64_1.0.0.0_Alpha.zip/arkui-x/plugins +├── component // Dynamic library of ArkUI component plug-ins. +│ ├── lib +│ │ ├── include +│ │ └── ${ui-name} +│ │ ├── ${ui-name}_android_adapter.jar // Dependent Android APIs for the implementation of some components. +│ │ ├── android-arm +│ │ ├── android-arm-profile +│ │ ├── android-arm-release +│ │ ├── android-arm64 +│ │ ├── android-arm64-profile +│ │ ├── android-arm64-release +│ │ │ └── lib${ui-name}.so // Implementation of ArkUI components. +│ │ └── android-x86_64 +│ └── apiconfig.json // Configuration of the cross-platform implementation of ArkUI components. +└── api // Dynamic library of ArkTS API plug-ins. + ├── lib + │ ├── include + │ └── ${module-name}_${submodule-name} + │ ├── ${module-name}_${submodule-name}.jar // Independent Android APIs for the implementation of some ArkTS APIs. + │ ├── android-arm + │ ├── android-arm-profile + │ ├── android-arm-release + │ ├── android-arm64 + │ ├── android-arm64-profile + │ ├── android-arm64-release + │ │ └── lib${module-name}_${submodule-name}.so // ArkTS API implementation. + │ └── android-x86_64 + └── apiConfig.json // Configuration of the cross-platform implementation of ArkTS @ohos APIs. +``` + +## macOS + +### Directory Structure of the ArkUI-X SDK Engine + +* **lib**, **framework**, and **xcframework** directories: cross-platform implementation of the ArkUI-X basic framework. +* **ets** directory: definition of ArkUI-X unique APIs and configuration description of basic APIs related to the ArkUI cross-platform stage model. +* **systemres** directory: system resource package for ArkUI rendering consistency. + +``` +arkui-x_darwin_x64_1.0.0.0_Alpha.zip/arkui-x/engine +├── lib // ArkUI cross-platform engine and platform adaptation layer. +│ ├── include // NAPIs and auxiliary C APIs. +│ ├── arkui +│ │ ├── arkui_android_adapter.jar // ArkUI adaptation layer for the Android platform. +│ │ ├── android-arm +│ │ ├── android-arm-profile +│ │ ├── android-arm-release +│ │ ├── android-arm64 +│ │ ├── android-arm64-profile +│ │ ├── android-arm64-release +│ │ │ └── libarkui_android.so // ArkUI cross-platform engine, including ArkUI, NAPI, ARK, and ability. +│ │ └── android-x86_64 +│ ├── third_party +│ └── utils +├── framework +│ ├── arkui +│ │ ├── ios-arm64 +│ │ ├── ios-arm64-profile +│ │ │ └── libarkui_ios.framework // ArkUI cross-platform engine and platform adaptation layer. +│ │ │ ├── Headers +│ │ │ │ ├── Ace.h +│ │ │ │ ├── AceViewController.h +│ │ │ │ └── include +│ │ │ ├── Info.plist +│ │ │ ├── libarkui_ios +│ │ │ ├── libarkui_ios.podspec +│ │ │ └── Modules +│ │ │ └── module.modulemap +│ │ ├── ios-arm64-release +│ │ ├── ios-arm64-simulator +│ │ └── ios-x86_64-simulator +│ ├── third_party +│ └── utils +├── xcframework +│ ├── arkui +│ │ ├── ios +│ │ │ └── libarkui_ios.xcframework // ArkUI cross-platform engine and platform adaptation layer. +│ │ │ ├── Info.plist +│ │ │ ├── ios-arm64 +│ │ │ │ └── libarkui_ios.framework +│ │ │ │ ├── Headers +│ │ │ │ │ ├── Ace.h +│ │ │ │ │ ├── AceViewController.h +│ │ │ │ │ └── include +│ │ │ │ ├── Info.plist +│ │ │ │ ├── libarkui_ios +│ │ │ │ ├── libarkui_ios.podspec +│ │ │ │ └── Modules +│ │ │ │ └── module.modulemap +│ │ │ └── ios-arm64_x86_64-simulator +│ │ ├── ios-profile +│ │ │ └── libarkui_ios.xcframework // ArkUI cross-platform engine and platform adaptation layer. +│ │ │ ├── Info.plist +│ │ │ ├── ios-arm64 +│ │ │ │ └── libarkui_ios.framework +│ │ │ │ ├── Headers +│ │ │ │ │ ├── Ace.h +│ │ │ │ │ ├── AceViewController.h +│ │ │ │ │ └── include +│ │ │ │ ├── Info.plist +│ │ │ │ ├── libarkui_ios +│ │ │ │ ├── libarkui_ios.podspec +│ │ │ │ └── Modules +│ │ │ │ └── module.modulemap +│ │ │ └── ios-arm64_x86_64-simulator +│ │ └── ios-release +│ │ └── libarkui_ios.xcframework // ArkUI cross-platform engine and platform adaptation layer. +│ │ ├── Info.plist +│ │ ├── ios-arm64 +│ │ │ └── libarkui_ios.framework +│ │ │ ├── Headers +│ │ │ │ ├── Ace.h +│ │ │ │ ├── AceViewController.h +│ │ │ │ └── include +│ │ │ ├── Info.plist +│ │ │ ├── libarkui_ios +│ │ │ ├── libarkui_ios.podspec +│ │ │ └── Modules +│ │ │ └── module.modulemap +│ │ └── ios-arm64_x86_64-simulator +│ ├── third_party +│ └── utils +├── ets // Definition of the ArkUI-X unique APIs and configuration description of the basic APIs related to the ArkUI cross-platform stage model. +│ └── @arkui-x.bridge.d.ts +├── apiConfig.json +└── systemres // System resource package for ArkUI component rendering consistency. +``` + +### Directory Structure of the ArkUI-X SDK Plug-Ins + +* **component** directory: dynamic libraries of ArkUI component plug-ins. +* **api** directory: dynamic libraries of the ArkTS API plug-ins. + +``` +arkui-x_darwin_x64_1.0.0.0_Alpha.zip/arkui-x/plugins +├── component // Dynamic library of ArkUI component plug-ins. +│ ├── lib +│ │ ├── include +│ │ └── ${ui-name} +│ │ ├── ${ui-name}_android_adapter.jar // Dependent Android APIs for the implementation of some components. +│ │ ├── android-arm +│ │ ├── android-arm-profile +│ │ ├── android-arm-release +│ │ ├── android-arm64 +│ │ ├── android-arm64-profile +│ │ ├── android-arm64-release +│ │ │ └── lib${ui-name}.so // Implementation of ArkUI components. +│ │ └── android-x86_64 +│ ├── framework +│ │ ├── ios-arm64 +│ │ ├── ios-arm64-profile +│ │ ├── ios-arm64-release +│ │ │ └── lib${ui-name}.framework // Implementation of ArkUI components. +│ │ │ ├── Headers +│ │ │ ├── Info.plist +│ │ │ ├── lib${ui-name} +│ │ │ ├── lib${ui-name}.podspec +│ │ │ └── Modules +│ │ │ └── module.modulemap +│ │ ├── ios-arm64-simulator +│ │ └── ios-x86_64-simulator +│ ├── xcframework +│ │ ├── ios +│ │ │ └── lib${ui-name}.xcframework // Implementation of ArkUI components. +│ │ │ ├── Info.plist +│ │ │ ├── ios-arm64 +│ │ │ │ └── lib${ui-name}.framework +│ │ │ │ ├── Headers +│ │ │ │ ├── Info.plist +│ │ │ │ ├── lib${ui-name} +│ │ │ │ ├── lib${ui-name}.podspec +│ │ │ │ └── Modules +│ │ │ │ └── module.modulemap +│ │ │ └── ios-arm64_x86_64-simulator +│ │ ├── ios-profile +│ │ │ └── lib${ui-name}.xcframework // Implementation of ArkUI components. +│ │ │ ├── Info.plist +│ │ │ ├── ios-arm64 +│ │ │ │ └── lib${ui-name}.framework +│ │ │ │ ├── Headers +│ │ │ │ ├── Info.plist +│ │ │ │ ├── lib${ui-name} +│ │ │ │ ├── lib${ui-name}.podspec +│ │ │ │ └── Modules +│ │ │ │ └── module.modulemap +│ │ │ └── ios-arm64_x86_64-simulator +│ │ └── ios-release +│ │ └── lib${ui-name}.xcframework // Implementation of ArkUI components. +│ │ ├── Info.plist +│ │ ├── ios-arm64 +│ │ │ └── lib${ui-name}.framework +│ │ │ ├── Headers +│ │ │ ├── Info.plist +│ │ │ ├── lib${ui-name} +│ │ │ ├── lib${ui-name}.podspec +│ │ │ └── Modules +│ │ │ └── module.modulemap +│ │ └── ios-arm64_x86_64-simulator +│ └── apiConfig.json // Configuration of the cross-platform implementation of ArkUI components. +└── api // Dynamic library of ArkTS API plug-ins. + ├── lib + │ ├── include + │ └── ${module-name}_${submodule-name} + │ ├── ${module-name}_${submodule-name}_android_adapter.jar // Independent Android APIs for the implementation of some ArkTS APIs. + │ ├── android-arm + │ ├── android-arm-profile + │ ├── android-arm-release + │ ├── android-arm64 + │ ├── android-arm64-profile + │ ├── android-arm64-release + │ │ └── lib${module-name}_${submodule-name}.so // ArkTS API implementation. + │ └── android-x86_64 + ├── framework + │ ├── ios-arm64 + │ ├── ios-arm64-profile + │ ├── ios-arm64-release + │ │ └── lib${module-name}_${submodule-name}.framework // ArkTS API implementation. + │ │ ├── Headers + │ │ ├── Info.plist + │ │ ├── lib${module-name}_${submodule-name} + │ │ ├── lib${module-name}_${submodule-name}.podspec + │ │ └── Modules + │ │ └── module.modulemap + │ ├── ios-arm64-simulator + │ └── ios-x86_64-simulator + ├── xcframework + │ ├── ios + │ │ └── lib${module-name}_${submodule-name}.xcframework // ArkTS API implementation. + │ │ ├── Info.plist + │ │ ├── ios-arm64 + │ │ │ └── lib${module-name}_${submodule-name}.framework + │ │ │ ├── Headers + │ │ │ ├── Info.plist + │ │ │ ├── lib${module-name}_${submodule-name} + │ │ │ ├── lib${module-name}_${submodule-name}.podspec + │ │ │ └── Modules + │ │ │ └── module.modulemap + │ │ └── ios-arm64_x86_64-simulator + │ ├── ios-profile + │ │ └── lib${module-name}_${submodule-name}.xcframework // ArkTS API implementation. + │ │ ├── Info.plist + │ │ ├── ios-arm64 + │ │ │ └── lib${module-name}_${submodule-name}.framework + │ │ │ ├── Headers + │ │ │ ├── Info.plist + │ │ │ ├── lib${module-name}_${submodule-name} + │ │ │ ├── lib${module-name}_${submodule-name}.podspec + │ │ │ └── Modules + │ │ │ └── module.modulemap + │ │ └── ios-arm64_x86_64-simulator + │ └── ios-release + │ └── lib${module-name}_${submodule-name}.xcframework // ArkTS API implementation. + │ ├── Info.plist + │ ├── ios-arm64 + │ │ └── lib${module-name}_${submodule-name}.framework + │ │ ├── Headers + │ │ ├── Info.plist + │ │ ├── lib${module-name}_${submodule-name} + │ │ ├── lib${module-name}_${submodule-name}.podspec + │ │ └── Modules + │ │ └── module.modulemap + │ └── ios-arm64_x86_64-simulator + └── apiConfig.json // Configuration of the cross-platform implementation of ArkTS @ohos APIs. +``` diff --git a/en/application-dev/quick-start/start-with-ability-on-android.md b/en/application-dev/quick-start/start-with-ability-on-android.md new file mode 100644 index 0000000000000000000000000000000000000000..761083b9b95c0e3fa46d9ede5a1efe580ba95c29 --- /dev/null +++ b/en/application-dev/quick-start/start-with-ability-on-android.md @@ -0,0 +1,60 @@ +# Developing an Android Application on Stage Model + +## Overview + +This topic describes the classes required for extending the ArkUI framework to the Android platform and their usages. This way, you can reuse most code (such as lifecycle code) of an OpenHarmony application and deploy the code on the Android platform. + +## Android Studio Configuration + +The value of **packageName** of the project created on Android Studio must be the same as that of **bundleName** of the OpenHarmony project. + +Android Studio is the tool for developing Android applications. + +## Key Classes Used for ArkUI-X and Android Integration + +### StageApplication of the Android Logic Part + +The application part must inherit **StageApplication** provided by the **arkui_android_adapter.jar** package. **StageApplication** is used to initialize resource paths and load the configuration. The code snippet is as follows: + +``` +package com.example.myapplication; +import ohos.stage.ability.adapter.StageApplication; + +public class HiStageApplication extends StageApplication { + +} +``` + +### StageActivity of the Android Logic Part + +The activity part must inherit **StageActivity** provided by the **arkui_android_adapter.jar** package. **StageActivity** is used to map the lifecycle of an activity in Android to that of an ability in OpenHarmony. The code snippet is as follows: + +``` +package com.example.myapplication; +import ohos.stage.ability.adapter.StageActivity; + +public class EntryMainAbilityActivity extends StageActivity { + @Override + protected void onCreate(Bundle savedInstanceState) { + super.setInstanceName("com.example.myapplication:entry:MainAbility:"); + super.onCreate(savedInstanceState); + } +} +``` + +To associate an activity with an ability, override the **onCreate** event in **StageActivity** and set **instanceName** in the following format before **super.onCreate(savedInstanceState)** is invoked: + +``` +bundleName:moduleName:abilityName: +``` + +The value of **bundleName** is obtained from the **app.json5** file of the OpenHarmony application, and the values of **moduleName** and **abilityName** are obtained from the **module.json5** file. + +## Mappings Between Abilities and Activities + +**packageName** of an activity in the Android application must be the same as **bundleName** of an ability in the OpenHarmony application. + +The format of **activityName** in the Android application is as follows: moduleName of the ability + abilityName of the ability + "Activity". + +A configuration example is as follows. + ![stage_android](figures/stage_android.png) \ No newline at end of file diff --git a/en/application-dev/quick-start/start-with-ability-on-ios.md b/en/application-dev/quick-start/start-with-ability-on-ios.md new file mode 100644 index 0000000000000000000000000000000000000000..e81c53001337af95daed234bcf2343d43c7e3068 --- /dev/null +++ b/en/application-dev/quick-start/start-with-ability-on-ios.md @@ -0,0 +1,196 @@ +# Developing an iOS Application on Stage Model + +## Overview + +This topic describes the classes required for extending the ArkUI framework to the iOS platform and their usages. This way, you can reuse most code (such as lifecycle code) of an OpenHarmony application and deploy the code on the iOS platform. + +## Key Classes Used for ArkUI-X and iOS Integration + +### StageViewController + +**StageViewController** is the base class of the iOS view controller of the stage model. To implement cross-platform basic capabilities and trigger ability lifecycle events, all iOS application-level view controllers must inherit from **StageViewController**. + +#### Common Attributes + +* **instanceName**: unique ID of the StageViewController. **instanceName** must be set to a value in the format of **bundleName:moduleName:abilityName**, where the value **bundleName** is obtained from the **app.json5** file of the OpenHarmony application, and the values of **moduleName** and **abilityName** are obtained from the **module.json5** file. + + ```objc + @property (nonatomic, readonly) NSString *instanceName; + ``` + +* **params**: external attribute of the StageViewController, which maps to the **want** parameter passed in **startAbility**. + + ```objc + @property (nonatomic, strong) NSString *params; + ``` + +#### Initialization Method + +```objc +- (instancetype)initWithInstanceName:(NSString *_Nonnull)instanceName; +``` + +### StageApplication + +**StageApplication** is essentially a scheduling class. It is used to trigger internal classes to implement path parsing and configuration, register application-related configuration, and trigger ability lifecycle events. + +#### Public Methods + +* Configure the local HAP file path. + + ```objc + + (void)configModuleWithBundleDirectory:(NSString *_Nonnull)bundleDirectory; + ``` + +* Trigger the calling of **StartAbility** and configure the process ID, localization information, and configuration. + + ```objc + + (void)launchApplication; + ``` + +* Trigger the ability to switch to the foreground. + + ```objc + + (void)callCurrentAbilityOnForeground; + ``` + +* Trigger the ability to switch to the background. + + ```objc + + (void)callCurrentAbilityOnBackground; + ``` + +* Process a singleton or multiton ability. + + ```objc + + (BOOL)handleSingleton:(NSString *)bundleName moduleName:(NSString *)moduleName abilityName:(NSString *)abilityName; + ``` + +* Release all view controllers in the navigation view stack and trigger the **OnDestory** event. + + ```objc + + (void)releaseViewControllers; + ``` + +* Obtain the top view controller of the navigation view stack. + + ```objc + + (StageViewController *)getApplicationTopViewController; + ``` + +## Key Implementation Reference in AppDelegate + +### Starting and Initializing the ArkUI Application +```objc +- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { + + // Configure the HAP file path. + [StageApplication configModuleWithBundleDirectory:@"arkui-x"]; + // Start the ability. + [StageApplication launchApplication]; + + // The application automatically starts. Initialize the StageViewController child class VC and set it as the root view controller of the application. + if (!launchOptions.count) { + NSString *instanceName = [NSString stringWithFormat:@"%@:%@:%@",@"com.example.iosabilitystage", @"entry", @"MainAbility"]; + EntryMainViewController *mainView = [[EntryMainViewController alloc] initWithInstanceName:instanceName]; + UINavigationController *navi = [[UINavigationController alloc]initWithRootViewController:mainView]; + self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds]; + self.window.rootViewController = navi; + [self.window makeKeyAndVisible]; + } + return YES; +} +``` + +### Implementing Page Redirection of the ArkUI Application +You can use either of the following ways to use [startAbility](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) to implement page redirection on the iOS platform. + +- Use openURL to implement the iOS application page redirection callback to obtain passed parameters. + +```objc +- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary *)options { + + // Truncate the URL based on rules. + NSString *bundleName = url.scheme; + NSString *moduleName = url.host; + NSString *abilityName, *params; + + NSURLComponents *urlComponents = [NSURLComponents componentsWithString:url.absoluteString]; + NSArray *array = urlComponents.queryItems; + for (NSURLQueryItem * item in array) { + if ([item.name isEqualToString:@"abilityName"]) { + abilityName = item.value; + } else if ([item.name isEqualToString:@"params"]) { + params = item.value; + } + } + // Process a singleton ability. + if ([StageApplication handleSingleton:bundleName moduleName:moduleName abilityName:abilityName] == YES) { + return YES; + } + [self handleOpenUrlWithBundleName:bundleName + moduleName:moduleName + abilityName:abilityName + params:params, nil]; + return YES; +} +``` +- Use the parameters parsed from the URL to map the view controller for an ability. + +```objc +- (BOOL)handleOpenUrlWithBundleName:(NSString *)bundleName + moduleName:(NSString *)moduleName + abilityName:(NSString *)abilityName + params:(NSString *)params, ...NS_REQUIRES_NIL_TERMINATION { + + NSString *instanceName = [NSString stringWithFormat:@"%@:%@:%@",bundleName, moduleName, abilityName]; + + // Map the view controller based on moduleName and abilityName. + // Note: An incorrect moduleName or abilityName will cause a failure in finding the view controller and opening the page. + if ([moduleName isEqualToString:@"entry"] && [abilityName isEqualToString:@"MainAbility"]) { + EntryMainAbilityViewController *entryMainVC = [[EntryMainAbilityViewController alloc] initWithInstanceName:instanceName]; + entryMainVC.params = params; + } else if ([moduleName isEqualToString:@"entry"] && [abilityName isEqualToString:@"Other"]) { + EntryOtherViewController *entryOtherVC = [[EntryOtherViewController alloc] initWithInstanceName:instanceName]; + entryOtherVC.params = params; + } + + return YES; +} +``` + +### Processing Lifecycle Callbacks for the ArkUI Application + +* Trigger a lifecycle event when the ArkUI application switches to the background. + + ```objc + - (void)applicationDidEnterBackground:(UIApplication *)application { + [StageApplication callCurrentAbilityOnBackground]; + } + ``` + +* Trigger a lifecycle event when the ArkUI application switches to the foreground. + + ```objc + - (void)applicationWillEnterForeground:(UIApplication *)application { + [StageApplication callCurrentAbilityOnForeground]; + } + ``` + +* Terminate the ArkUI application process. + + ```objc + - (void)applicationWillTerminate:(UIApplication *)application { + [StageApplication releaseViewControllers]; + } + ``` + +**NOTE**: For the complete code, see the samples. + +## Mappings Between Abilities and View Controllers + +The value of **bundleName** in **info** of the iOS application must be the same as that of **bundleName** in the ability. + +The format of **viewControllerName** in the iOS application is as follows: moduleName of the ability + abilityName of the ability + "ViewController". + +![stage_iOS](figures/StageiOS.png) \ No newline at end of file diff --git a/en/application-dev/reference/apis/readme.md b/en/application-dev/reference/apis/README.md similarity index 91% rename from en/application-dev/reference/apis/readme.md rename to en/application-dev/reference/apis/README.md index 2543495f3fa8ce24af19a5baccdc11c60b57902e..b44ebbfaf9ad86931ba361db5392b0c515f7e35a 100644 --- a/en/application-dev/reference/apis/readme.md +++ b/en/application-dev/reference/apis/README.md @@ -1,4 +1,16 @@ # OpenHarmony APIs with Cross-Platform Support +- Platform Bridge + - [@arkui-x.bridge (Platform Bridget)](js-apis-bridge.md) + +- UI Page + - [@ohos.animator (Animator)](js-apis-animator.md) + - [@ohos.arkui.UIContext (UIContext)](js-apis-arkui-UIContext.md) + - [@ohos.curves (Interpolation Calculation)](js-apis-curve.md) + - [@ohos.matrix4 (Matrix Transformation)](js-apis-matrix4.md) + - [@ohos.mediaquery (Media Query)](js-apis-mediaquery.md) + - [@ohos.promptAction (Prompt)](js-apis-promptAction.md) + - [@ohos.router (Page Routing)](js-apis-router.md) + - Ability Framework - Stage Model (Recommended) - [@ohos.app.ability.abilityLifecycleCallback (AbilityLifecycleCallback)](js-apis-app-ability-abilityLifecycleCallback.md) @@ -11,8 +23,6 @@ - [@ohos.app.ability.ConfigurationConstant (ConfigurationConstant)](js-apis-app-ability-configurationConstant.md) - [@ohos.app.ability.Want (Want)](js-apis-app-ability-want.md) - Dependent Elements and Definitions - - ability - - app - application - [abilityDelegator](js-apis-inner-application-abilityDelegator.md) - [abilityDelegatorArgs](js-apis-inner-application-abilityDelegatorArgs.md) @@ -31,30 +41,29 @@ - [applicationInfo](js-apis-bundleManager-applicationInfo.md) - [hapModuleInfo](js-apis-bundleManager-hapModuleInfo.md) - [metadata](js-apis-bundleManager-metadata.md) -- UI - - [@ohos.animator (Animator)](js-apis-animator.md) - - [@ohos.arkui.UIContext (UIContext)](js-apis-arkui-UIContext.md) - - [@ohos.curves (Interpolation Calculation)](js-apis-curve.md) - - [@ohos.matrix4 (Matrix Transformation)](js-apis-matrix4.md) - - [@ohos.mediaquery (Media Query)](js-apis-mediaquery.md) - - [@ohos.promptAction (Prompt)](js-apis-promptAction.md) - - [@ohos.router (Page Routing)](js-apis-router.md) - -- Network Management - - [@ohos.net.connection (Network Connection Management)](js-apis-net-connection.md) - - [@ohos.net.http (Data Request)](js-apis-http.md) - - [@ohos.net.socket (Socket Connection)](js-apis-socket.md) - - [@ohos.net.webSocket (WebSocket Connection)](js-apis-webSocket.md) + +- Graphics + - [@ohos.window (Window)](js-apis-window.md) + - [@ohos.display (Display)](js-apis-display.md) - Resource Management - [@ohos.i18n (Internationalization)](js-apis-i18n.md) - [@ohos.intl (Internationalization)](js-apis-intl.md) + - [@ohos.resourceManager (Resource Manager)](js-apis-resource-manager.md) + +- Network Management + - [@ohos.request (Upload and Download)](js-apis-request.md) + - [@ohos.net.webSocket (WebSocket Connection)](js-apis-webSocket.md) + - [@ohos.net.socket (Socket Connection)](js-apis-socket.md) + - [@ohos.net.http (Data Request)](js-apis-http.md) + - [@ohos.net.connection (Network Connection Management)](js-apis-net-connection.md) - File Management - [@ohos.file.fs (File Management)](js-apis-file-fs.md) - Device Management - - [@ohos.deviceInfo (Device Information)](js-apis-device_Info.md) + - [@ohos.deviceInfo (Device Information)](js-apis-device_info.md) + - Data Management - [@ohos.data.preferences (User Preferences)](js-apis-data-preferences.md) - [@ohos.data.relationalStore (RDB Store)](js-apis-data-relationalStore.md) @@ -85,4 +94,6 @@ - [@ohos.util.TreeSet (Nonlinear Container TreeSet)](js-apis-treeset.md) - [@ohos.worker (Worker Startup)](js-apis-worker.md) - [@ohos.xml (XML Parsing and Generation)](js-apis-xml.md) - \ No newline at end of file + +- Basic Features + - [@ohos.hilog (HiLog)](js-apis-hilog.md) diff --git a/en/application-dev/tools/figures/en-us_image_0000001579994524.png b/en/application-dev/tools/figures/en-us_image_0000001579994524.png new file mode 100644 index 0000000000000000000000000000000000000000..42259ceea00ab84cd201786cf349436d7f8241c6 Binary files /dev/null and b/en/application-dev/tools/figures/en-us_image_0000001579994524.png differ diff --git a/en/application-dev/tools/figures/en-us_image_0000001580312688.png b/en/application-dev/tools/figures/en-us_image_0000001580312688.png new file mode 100644 index 0000000000000000000000000000000000000000..cbfe03a4bd66073fa272591b276475c8e356ed56 Binary files /dev/null and b/en/application-dev/tools/figures/en-us_image_0000001580312688.png differ diff --git a/en/application-dev/tools/figures/en-us_image_0000001580313452.png b/en/application-dev/tools/figures/en-us_image_0000001580313452.png new file mode 100644 index 0000000000000000000000000000000000000000..08d28e8f385a822830e9c37e7241af97515927a3 Binary files /dev/null and b/en/application-dev/tools/figures/en-us_image_0000001580313452.png differ diff --git a/en/application-dev/tools/figures/en-us_image_0000001630032705.png b/en/application-dev/tools/figures/en-us_image_0000001630032705.png new file mode 100644 index 0000000000000000000000000000000000000000..24521c59fe8e10ba8b0b855485c521c67612782f Binary files /dev/null and b/en/application-dev/tools/figures/en-us_image_0000001630032705.png differ diff --git a/en/application-dev/tools/figures/en-us_image_0000001642806197.png b/en/application-dev/tools/figures/en-us_image_0000001642806197.png new file mode 100644 index 0000000000000000000000000000000000000000..dce687b971b22ddbac4efc1a8561ee89d5d3e383 Binary files /dev/null and b/en/application-dev/tools/figures/en-us_image_0000001642806197.png differ diff --git a/en/application-dev/tools/figures/import_sample.png b/en/application-dev/tools/figures/import_sample.png new file mode 100644 index 0000000000000000000000000000000000000000..25c20ee63eb57757e7d1ab2ae8a6958152f57bdf Binary files /dev/null and b/en/application-dev/tools/figures/import_sample.png differ diff --git a/en/application-dev/tools/how-to-use-ace-tools.md b/en/application-dev/tools/how-to-use-ace-tools.md new file mode 100644 index 0000000000000000000000000000000000000000..5bfad1b39c781cb708059148a54ee1359810e73a --- /dev/null +++ b/en/application-dev/tools/how-to-use-ace-tools.md @@ -0,0 +1,120 @@ +# Using ACE Tools to Build a Cross-Platform Application + +This tutorial walks you through on how to use ACE Tools to extend the OpenHarmony development paradigm to cross-platform development, including: + +* Basic project development +* Native C++ development +* AAR/Framework development +* Multi-ability development +* Multi-module development + +## Basic Project Development +* Run the **ace create** command to create a simple project and enter the project name and related information as prompted. + ```shell + ace create project + ? Please enter the project name: HelloWorld + ? Please enter the bundle name (com.example.helloworld):com.example.helloworld + ? 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 // Create an empty Ability or native C++ project. + ``` +* The structure of the created project is as follows: + ``` + HelloWorld + ├── .arkui-x + | ├── android // Android application project + | └── ios // iOS application project + ├── AppScope + ├── build-profile.json5 + ├── entry // Module + ├── hvigor + ├── hvigorw + ├── hvigorw.bat + └── oh-package.json5 + ``` +* The project structure is the same as the structure of a cross-platform project built using DevEco Studio. +* Run the **ace build** command to build and pack the ArkTS source code. In this way, a cross-platform application is built. +## Native C++ Development +With ACE Tools, you can use native C++ APIs in cross-platform development. +* When creating a project, select **Native C++** for the template type. + + **Note**: The iOS project structure remains unchanged. After the iOS project is configured, the **hello.cpp** file in the **source** directory is compiled to the application. + +* The structure of the created project is as follows: + + ``` + HelloWorld + ├── .arkui-x + | ├── android/app/src/main + | | └── cpp + | | └── CmakeLists.txt + | └── ios + ├── AppScope + ├── build-profile.json5 + ├── entry/src/main + | └── cpp // Native C++ + | ├── types/libentry + | | ├── index.d.ts + | | └── oh-package.json5 + | ├── CMakeLists.txt + | └── hello.cpp + ├── hvigor + ├── hvigorw + ├── hvigorw.bat + └── oh-package.json5 + ``` +* Run the **ace build** command to build the source code. In this way, a cross-platform application is built with native C++ APIs. + +## AAR/Framework Development +With ACE Tools, you can develop Android Archive (AAR) plug-ins. +* When creating a project, select **Library** for the project type. The project structure is the same as the structure of a simple project. The only difference is that the project you create is an Android directory project. +* Run the **ace build** command to build the library product of the target platform. + ```shell + ace build aar // Build the AAR for the Android platform. + ace build framework // Build the framework of the iOS platform. + ``` +## Multi-Ability Development +With ACE Tools, you can develop a cross-platform application with multiple abilities. +* Run the following command and enter the ability name as prompted to create an Ability module: + ``` + cd entry + ace create ability + ? Please enter the ability name:Second + ``` +* The preceding command adds the corresponding ability adaptation code to the **entry**, **android**, and **ios** directories. The following shows only the new code. + ``` + HelloWorld + ├── .arkui-x + | ├── android/app/src/main/java/com/example/demo + | | └── EntrySecondAbilityActivity.java // Android code for ability adaptation + | └── ios/app + | ├── EntrySecondAbilityViewController.h // iOS code for ability adaptation + | └── EntrySecondAbilityViewController.m // iOS code for ability adaptation + | + └── entry/src/main/ets + └── SecondAbility // SecondAbility + └── SecondAbility.ets + ``` +* Run the **ace build app/apk** command to build and pack the ArkTS source code. In this way, an iOS or Android application in the multi-ability scenario is built. +## Multi-Module Development +With ACE Tools, you can develop a cross-platform application with multiple modules. +* Run the following command and enter the module name as prompted: + ``` + cd entry + ace create ability + ? Please enter the module name: feature1 + ``` +* Run the **ace create module** command and enter the module name as prompted. In this example, the module name is **feature1**. This command adds the corresponding ability adaptation code to the **entry**, **android**, and **ios** directories. + ``` + HelloWorld + ├── .arkui-x + | ├── android/app/src/main/java/com/example/demo + | | └── Feature1Feature1AbilityActivity.java // Android code for ability adaptation + | └── ios/app + | ├── Feature1Feature1AbilityViewController.h // iOS code for ability adaptation + | └── Feature1Feature1AbilityViewController.m // iOS code for ability adaptation + ├── entry + └── feature1 // New module: feature1 + + ``` +* Run the **ace build app/apk** command to build and pack the ArkTS source code. In this way, an iOS or Android application in the multi-module scenario is built. diff --git a/en/application-dev/tools/how-to-use-deveco-studio.md b/en/application-dev/tools/how-to-use-deveco-studio.md new file mode 100644 index 0000000000000000000000000000000000000000..1b8e8aa4d75a858ca642fcc28bbd048d77634a15 --- /dev/null +++ b/en/application-dev/tools/how-to-use-deveco-studio.md @@ -0,0 +1,68 @@ +# Using DevEco Studio to Develop a Cross-Platform Application + +## Developing a Cross-Platform Application + + +### Creating a Project + +Import the ArkUI-X sample to DevEco Studio to quickly create a cross-platform project. + +1. Choose **File > New > Import > Import Sample**. + + ![import_sample](figures/import_sample.png) + +2. Select **OpenHarmony** from the drop-down list box in the upper left corner, select **ArkUI-X/HelloWorld**, and click **Next**. + +3. On the project configuration page, set **Project name** and **Project location**, click **Finish**, and wait until the sample project is imported. + +To get the most out of DevEco Studio, run a diagnostic test on your development environment and fix the failed items based on the provided suggestions. + +If a dialog box indicating a failed Android SDK check is displayed, check the configuration of the environment variables. + +![en-us_image_0000001642806197](figures/en-us_image_0000001642806197.png) + +### Building a Cross-Platform Application + +DevEco Studio can generate application packages for different platforms. Specifically, DevEco Studio running on Windows generates .apk packages that can run on Android devices in addition to application packages that can run on OpenHarmony devices. DevEco Studio running on iOS generates application packages that can run on iOS devices in addition to the preceding two types of packages. + +1. On the menu bar of DevEco Studio, choose **Build > Build Hap(s)/APP(s) > Build APP(s)**. + + ![en-us_image_0000001580152768](figures/en-us_image_0000001580313452.png) + + After the build is complete, an .apk file that can run on Android devices is generated in the **.arkui-x > android > app > build > outputs** directory. If macOS is in use, an application package that can run on iOS devices is generated in the **ios** directory. + + ![en-us_image_0000001580312688](figures/en-us_image_0000001580312688.png) + + An application package that can run on OpenHarmony devices is generated in the **build** directory. + + ![en-us_image_0000001630032705](figures/en-us_image_0000001630032705.png) + +2. Open the **android** directory in Android Studio, push the build product package to a real Android device through Android Studio, and check the application running effect. + +## Developing a Cross-Platform Dependency Package + +You can build dependency packages for Android and iOS applications based on an OpenHarmony application. The dependency packages can be added to existing Android and iOS applications. + +### Creating a Library + +Import the ArkUI-X sample to DevEco Studio to quickly create a cross-platform project. + +1. Choose **File > New > Import > Import Sample**. + + ![import_sample](figures/import_sample.png) + +2. Select **OpenHarmony** from the drop-down list box in the upper left corner, select **ArkUI-X/ArkUI-X_Library**, and click **Next**. + +3. On the project configuration page, set **Project name** and **Project location**, click **Finish**, and wait until the sample project is imported. + +### Building a Cross-platform Dependency Package + +Based on an OpenHarmony application, DevEco Studio can generate dependency packages for different platforms. Specifically, DevEco Studio running on Windows generates an .aar package that can be integrated with Android applications. DevEco Studio running on iOS generates an .xcframework package that can be integrated with iOS applications in addition to the .aar package. + +On the menu bar, choose **Build > Build Hap(s)/APP(s) > Build APP(s)**. + +![en-us_image_0000001580313452](figures/en-us_image_0000001580313452.png) + +After the build is complete, the .aar package that can be integrated with Android applications is generated in the **.arkui-x > android > library > build > outputs** directory. If macOS is in use, an .xcframework package that can be integrated with iOS applications is generated in the **ios** directory. + +![en-us_image_0000001579994524](figures/en-us_image_0000001579994524.png) diff --git a/en/application-dev/tutorial/how-to-integrate-arkui-into-android.md b/en/application-dev/tutorial/how-to-integrate-arkui-into-android.md new file mode 100644 index 0000000000000000000000000000000000000000..84b98522adb056d4a682837838bf76d7ee04c9bc --- /dev/null +++ b/en/application-dev/tutorial/how-to-integrate-arkui-into-android.md @@ -0,0 +1,85 @@ +# How to Build an ArkUI Application on Android + +## Overview + +This tutorial describes how to use the ArkUI-X SDK to develop Android applications, thereby implementing the display of the ArkTS-based declarative development paradigm on Android. It covers the following topics: + +* Integrating the ArkUI-X SDK into an Android project +* Integrating ArkUI-X building products into an Android project +* Using ACE Tools and DevEco Studio to integrate the ArkUI-X SDK for Android application development + +### Creating an Android Project +Use ACE Tools or DevEco Studio to create an ArkUI-X application project (named **HelloWorld** in this example). An **.arkui-x/android** file is generated in the project directory. The entry classes **Application** and **Activity** of the Android application must inherit from the ArkUI base classes **StageApplication** and **StageActivity**, respectively. The **Application** class can also be used through the **StageApplicationDelegate** class. For details, see [ArkUI-X APIs for Android Integration](../reference/arkui-for-android). +* Activity class + + The class name is obtained by combining the module name and ability name. One ability corresponds to one **Activity** class of Android. For details, see [Developing an Android Application on Stage Model](../quick-start/start-with-ability-on-android.md). + + ```java + package com.example.helloworld; + + import android.os.Bundle; + import android.util.Log; + + import ohos.stage.ability.adapter.StageActivity; + + public class EntryEntryAbilityActivity extends StageActivity { + @Override + protected void onCreate(Bundle savedInstanceState) { + Log.e("HiHelloWorld", "EntryMainAbilityActivity"); + + setInstanceName("com.example.helloworld:entry:EntryAbility:"); // Name of the directory (module instance name) for storing ArkUI-X build products in assets/js of the application project. + super.onCreate(savedInstanceState); + } + } + ``` +* Application class + ```java + package com.example.helloworld; + + import android.util.Log; + + import ohos.stage.ability.adapter.StageApplication; + + public class MainApplication extends StageApplication { + private static final String LOG_TAG = "HiHelloWorld"; + + private static final String RES_NAME = "res"; + + @Override + public void onCreate() { + Log.e(LOG_TAG, "MyApplication"); + super.onCreate(); + Log.e(LOG_TAG, "MyApplication onCreate"); + } + } + ``` + + +### Building an Android Project +ACE Tools or DevEco Studio performs the following steps when building an Android project: + +* Integrate the ArkUI-X SDK. + + The integration complies with the JAR and dynamic library integration rules of Android application projects. Specifically, you need to copy the **arkui_android_adapter.jar** package in the SDK components to the **libs** directory. In this case, the dynamic libraries (**libarkui_android.so**, **libhilog_android.so**, **libhilog.so**, and **libresourcemanager.so**) are automatically copied to the **libs/arm64-v8a** directory. +* Integrate ArkUI-X build products. + + After ArkUI-X build products are generated, copy them to the **assets/arkui-x** (fixed) directory of the Android application project. For details, see [ArkUI-X Application Project Structure](../quick-start/package-structure-guide.md). + + ``` + src/main/assets/arkui-x + ├── entry + | ├── ets + | | ├── modules.abc + | | └── sourceMaps.map + | ├── resouces.index + | ├── resouces + | └── module.json + └── systemres + ``` + + + +After the preceding steps are complete, you can build the ArkUI Android application according to the Android application building process. The application built will be able to be installed and run on Android phones. +### Reference + +[ArkUI-X Samples](https://gitee.com/arkui-x/samples) diff --git a/en/contribute/README.md b/en/contribute/README.md index 9310ee69400b882df3439eac2c64aba5b15831aa..cb6dc682b10b69e5b7656e935c2e81c740c6bde1 100644 --- a/en/contribute/README.md +++ b/en/contribute/README.md @@ -7,4 +7,3 @@ - [Documentation Contribution](documentation-contribution.md) - [Writing Instructions](writing-instructions.md) - [Communication in Community](communication-in-community.md) - diff --git a/en/glossary.md b/en/glossary.md index 38908a258f19adf1e51f4008562701c6c0128f11..9a1b20fab5704bd2c45b200fcd0060d41e1bb959 100644 --- a/en/glossary.md +++ b/en/glossary.md @@ -4,14 +4,24 @@ - ### ArkUI - ArkUI is a UI development framework for building OpenHarmony applications. It provides simple and natural UI syntax and UI development infrastructure including UI components, animation mechanisms, and event interaction, to meet the visualized GUI development requirements of application developers. + ArkUI is a UI development framework for building OpenHarmony applications. It provides simple and natural UI syntax and UI development infrastructure including UI components, animation mechanisms, and event interaction, to meet the visualized GUI development requirements of application developers. For more information, see [ArkUI](https://developer.harmonyos.com/en/develop/arkUI/). - ### ArkUI-X - The ArkUI-X project extends the ArkUI development framework to multiple OS platforms, enabling developers to develop multi-platform applications based on a set of main code. + ArkUI-X extends the ArkUI framework to multiple OS platforms. Currently, it supports OpenHarmony, HarmonyOS, Android, and iOS. More OS platforms will be supported in the future. With ArkUI-X, you can use a set of main code to develop high-performance applications supporting multiple platforms. -## C +- ### ACE -- ### CLI + ArkUI Cross-Platform Environment (ACE) provides a set of command line tools (ACE Tools) for ArkUI-X application developers to check the development environment, create projects, and build, pack, install, and debug applications. - The command line interface (CLI) tools are tools that allow developers to build cross-platform applications. +## N + +- ### Node-API + + Node-API provides APIs to encapsulate JavaScript (JS) capabilities as a native plug-in. It is independent of the underlying JS and is maintained as part of Node.js. The N-API component of ArkUI-X re-implements Node-API interfaces. Currently, it supports [some interfaces](./application-dev/reference/native-lib/third_party_napi/napi.md) in the Node-API standard library. + +## P + +- ### Platform Bridge + + The platform bridge (@arkui-x.bridge) transmits messages between the client (ArkUI) and the platform (Android or iOS). It also enables ArkTS to call platform APIs and the platform to call ArkTS methods. diff --git a/en/release-notes/README.md b/en/release-notes/README.md index d074db5a34aa275be9c9a076de735af5d79478a7..befe4f56e40ad53ac88709a64980970b36a24955 100644 --- a/en/release-notes/README.md +++ b/en/release-notes/README.md @@ -1,6 +1,5 @@ # ArkUI-X Release Notes -### ArkUI-X 1.x Releases +## ArkUI-X 1.x Releases * [ArkUI-X v1.0.0 Canary1 (2023-08-04)](ArkUI-X-v1.0.0-canary1.md) -