Qt for HarmonyOS/user development guide/how to deply qml app zh

1. QML 应用程序在 HarmonyOS 中的部署指南

1. 1. 简介

本文档介绍如何将基于 Qt QML 开发的应用程序部署到 HarmonyOS 设备上。HarmonyOS 对 QML 应用程序的部署有特定的要求，需要将不同类型的文件放置在指定的目录结构中。本指南将详细说明部署的步骤与方法，并提供关于 QML 部署的最佳实践。

1. 1. 部署架构概述

在 HarmonyOS 中部署 QML 应用程序时，需要遵循以下文件组织结构：

``` ohos模板工程根目录 ├── entry │ ├── libs │ │ └── arm64-v8a │ │ ├── libqt相关.so文件 │ │ ├── 应用的.so文件 │ │ ├── plugins/ │ │ └── qml/（保持原目录结构的.so文件） │ └── src │ └── main │ └── resources │ └── resfile │ └── qml/（保持原目录结构的非.so文件） ```

1. 1. 手动部署步骤

1. 1. 1. 1. 准备工作

首先，确保您有： - Qt 安装目录（包含为 HarmonyOS 编译的 Qt 库） - 目标 HarmonyOS 应用工程目录

1. 1. 1. 2. 创建必要的目录结构

在应用工程目录中手动创建以下目录结构：

```bash

1. 为.so文件创建目录

mkdir -p entry/libs/arm64-v8a/qml mkdir -p entry/libs/arm64-v8a/plugins

1. 为 QML 资源文件创建目录

mkdir -p entry/src/main/resources/resfile/qml ```

1. 1. 1. 3. 复制 Qt 核心库文件

手动从 Qt 安装目录复制核心库文件到目标目录：

```bash

1. 将 Qt 核心库复制到 libs/arm64-v8a 目录

cp <Qt 安装目录>/lib/libQt5Core.so entry/libs/arm64-v8a/ cp <Qt 安装目录>/lib/libQt5Gui.so entry/libs/arm64-v8a/ cp <Qt 安装目录>/lib/libQt5Network.so entry/libs/arm64-v8a/ cp <Qt 安装目录>/lib/libQt5Qml.so entry/libs/arm64-v8a/ cp <Qt 安装目录>/lib/libQt5Quick.so entry/libs/arm64-v8a/

1. 复制其他所需的 Qt 库...

```

找到并复制所有必要的 Qt 核心库文件（.so 文件）。这些文件通常位于 Qt 安装目录的 lib 文件夹中。

1. 1. 1. 4. 复制 Qt 插件

保持目录结构，将 Qt 插件复制到目标目录：

```bash

1. 复制所有插件目录及文件，保持目录结构

cp -r <Qt 安装目录>/plugins/* entry/libs/arm64-v8a/plugins/ ```

1. 1. 1. 5. 处理 QML 模块文件

QML 模块文件需要特殊处理，按照文件类型分为两类：

1. 1. 1. 1. A. 处理 QML 模块的 .so 文件

遍历 Qt 安装目录中的 qml 目录，复制所有 .so 文件到 libs/arm64-v8a/qml 目录，保持原目录结构：

首先检查 Qt 安装目录中的 qml 文件夹 手动创建相应的目录结构 复制 .so 文件 例如，对于 `<Qt 安装目录>/qml/QtQuick/Controls/libqtquickcontrolsplugin.so`：

```bash

1. 创建目标目录

mkdir -p entry/libs/arm64-v8a/qml/QtQuick/Controls

1. 复制.so文件

cp <Qt 安装目录>/qml/QtQuick/Controls/libqtquickcontrolsplugin.so entry/libs/arm64-v8a/qml/QtQuick/Controls/ ```

1. 1. 1. 1. B. 处理 QML 模块的非 .so 文件

遍历同样的 Qt 安装目录中的 qml 目录，复制所有非 .so 文件到 resources/resfile/qml 目录，保持原目录结构：

检查同一个 qml 文件夹 手动创建相应的目录结构 复制所有非 .so 文件（如 .qml、.js、图片等） 例如，对于 `<Qt 安装目录>/qml/QtQuick/Controls/Button.qml`：

```bash

1. 创建目标目录

mkdir -p entry/src/main/resources/resfile/qml/QtQuick/Controls

1. 复制非.so文件

cp <Qt 安装目录>/qml/QtQuick/Controls/Button.qml entry/src/main/resources/resfile/qml/QtQuick/Controls/ ```

1. 1. 1. 6. 完整手动部署案例

假设我们需要部署 QtQuick.Controls 模块，手动步骤如下：

```bash

1. 1. 在 Qt 安装目录查找该模块的所有文件

find <Qt 安装目录>/qml/QtQuick/Controls -type f

1. 2. 创建相应的目录结构

mkdir -p entry/libs/arm64-v8a/qml/QtQuick/Controls mkdir -p entry/src/main/resources/resfile/qml/QtQuick/Controls

1. 3. 复制.so文件

find <Qt 安装目录>/qml/QtQuick/Controls -name "*.so" | while read sofile; do

 # 获取相对路径
 relpath=$(echo $sofile | sed "s|<Qt 安装目录>/qml/||")
 # 复制到目标位置
 mkdir -p $(dirname "entry/libs/arm64-v8a/qml/$relpath")
 cp "$sofile" "entry/libs/arm64-v8a/qml/$relpath"

done

1. 4. 复制非.so文件

find <Qt 安装目录>/qml/QtQuick/Controls -type f ! -name "*.so" | while read file; do

 # 获取相对路径
 relpath=$(echo $file | sed "s|<Qt 安装目录>/qml/||")
 # 复制到目标位置
 mkdir -p $(dirname "entry/src/main/resources/resfile/qml/$relpath")
 cp "$file" "entry/src/main/resources/resfile/qml/$relpath"

done ```

1. 1. QML 部署详解

1. 1. 1. 1. 动态库文件 (.so) 处理原则

对于 QML 应用，需要将以下库文件按照规则手动部署：

- **Qt 核心库**：如 libQt5Core.so、libQt5Gui.so 等，这些文件应放在 libs/arm64-v8a/ 目录 - **Qt 插件**：所有插件文件应保持其目录结构，放在 libs/arm64-v8a/plugins/ 目录 - **QML 模块的 .so 文件**：所有 QML 相关的 .so 文件应保持其目录结构，放在 libs/arm64-v8a/qml/ 目录

1. 1. 1. 2. 非 .so 文件处理原则

对于 QML 模块中的非 .so 文件（如 .qml 文件、.js 文件、图片等资源），应保持其目录结构，放在 resources/resfile/qml/ 目录。

1. 1. 最佳实践

1. 1. 1. 手动部署检查清单

- **核心库文件检查**：确保所有必需的 Qt 核心库都已复制到 libs/arm64-v8a/ 目录 - **目录结构检查**：确保 QML 模块的目录结构在两个目标位置保持一致 - **文件分类检查**：确保 .so 文件和非 .so 文件正确分类到各自的目录

1. 1. 1. 应用程序开发建议

- **正确引用 QML 模块**：确保在 QML 代码中正确引用模块。HarmonyOS 会根据目录结构查找 QML 模块

 ```qml
 import QtQuick 2.12
 import QtQuick.Controls 2.12
 ```

- **资源路径使用**：在 QML 代码中引用资源时，使用相对路径，如：

 ```qml
 Image {
     source: "images/button.png"  // 相对于当前 QML 文件的路径
 }
 ```

- **插件依赖检查**：如果使用第三方 QML 插件，确保相关的 .so 文件和资源文件按照上述规则放置

1. 1. 常见问题解决

1. 1. 1. 找不到 QML 模块

- 检查是否正确复制了相应模块的 .so 文件和资源文件，保持目录结构不变

1. 1. 1. 应用崩溃

- 检查是否复制了所有必需的库文件，尤其是特定模块依赖的库

1. 1. 1. 资源文件不可见

- 确认非 .so 文件是否正确放置在 resources/resfile/qml/ 目录下

1. 1. 自定义 QML 模块部署

如果您开发了自定义 QML 模块，应遵循与系统 QML 模块相同的部署规则：

- 将模块的 .so 文件放在 libs/arm64-v8a/qml/您的模块名/ 目录 - 将模块的 QML 文件、资源文件等放在 resources/resfile/qml/您的模块名/ 目录

例如，如果您有一个名为 "MyCustomModule" 的模块：

``` libs/arm64-v8a/qml/MyCustomModule/libmycustommodule.so resources/resfile/qml/MyCustomModule/MyComponent.qml resources/resfile/qml/MyCustomModule/qmldir ```

1. 1. 总结

手动部署 QML 应用到 HarmonyOS 需要仔细处理文件的分类和目录结构。虽然手动部署较为繁琐，但能够帮助开发者更好地理解 HarmonyOS 的 QML 应用部署要求。正确的部署可以确保应用在 HarmonyOS 设备上正常运行。开发者应当特别注意将 .so 文件和非 .so 文件正确分离到不同的目录，同时保持目录结构一致。通过遵循本文档的手动部署步骤，可以成功将 QML 应用部署到 HarmonyOS 平台。