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

中文 English

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

简介

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

部署架构概述

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

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

手动部署步骤

1. 准备工作

首先，确保您有：

 * Qt 安装目录（包含为 HarmonyOS 编译的 Qt 库）
 * 目标 HarmonyOS 应用工程目录

2. 创建必要的目录结构

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

<syntaxhighlight lang="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 </syntaxhighlight\>

3. 复制 Qt 核心库文件

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

<syntaxhighlight lang="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 库...

</syntaxhighlight\>

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

4. 复制 Qt 插件

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

<syntaxhighlight lang="bash"\>

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

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

5. 处理 QML 模块文件

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

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

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

1. 检查 Qt 安装目录中的 qml 文件夹

1. 手动创建相应的目录结构

1. 复制 <code\>.so\</code\> 文件

例如，对于 \<code\>\<Qt 安装目录\>/qml/QtQuick/Controls/libqtquickcontrolsplugin.so\</code\>：

<syntaxhighlight lang="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/ </syntaxhighlight\>

\==== B. 处理 QML 模块的非 .so 文件 ==== 遍历同样的 Qt 安装目录中的 \<code\>qml\</code\> 目录，复制所有非 \<code\>.so\</code\> 文件到 \<code\>resources/resfile/qml\</code\> 目录，保持原目录结构：

1. 检查同一个 qml 文件夹

1. 手动创建相应的目录结构

1. 复制所有非 \<code\>.so\</code\> 文件（如 \<code\>.qml\</code\>、\<code\>.js\</code\>、图片等）

例如，对于 \<code\>\<Qt 安装目录\>/qml/QtQuick/Controls/Button.qml\</code\>：

\<syntaxhighlight lang="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/ \</syntaxhighlight\>

\=== 6. 完整手动部署案例 === 假设我们需要部署 QtQuick.Controls 模块，手动步骤如下：

\<syntaxhighlight lang="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

1. 获取相对路径

relpath=$(echo $sofile | sed "s|\<Qt 安装目录\>/qml/||")

1. 复制到目标位置

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

1. 获取相对路径

relpath=$(echo $file | sed "s|\<Qt 安装目录\>/qml/||")

1. 复制到目标位置

mkdir -p $(dirname "entry/src/main/resources/resfile/qml/$relpath") cp "$file" "entry/src/main/resources/resfile/qml/$relpath" done \</syntaxhighlight\>

\== QML 部署详解 ==

\=== 1. 动态库文件 (\<code\>.so\</code\>) 处理原则 === 对于 QML 应用，需要将以下库文件按照规则手动部署：

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

\=== 2. 非 \<code\>.so\</code\> 文件处理原则 === 对于 QML 模块中的非 \<code\>.so\</code\> 文件（如 \<code\>.qml\</code\> 文件、\<code\>.js\</code\> 文件、图片等资源），应保持其目录结构，放在 \<code\>resources/resfile/qml/\</code\> 目录。

\== 最佳实践 ==

\=== 手动部署检查清单 ===

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

\=== 应用程序开发建议 ===

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

\<syntaxhighlight lang="qml"\> import QtQuick 2.12 import QtQuick.Controls 2.12 \</syntaxhighlight\>

 * 资源路径使用：在 QML 代码中引用资源时，使用相对路径，如：
   \<syntaxhighlight lang="qml"\>
   Image {
   source: "images/button.png"  // 相对于当前 QML 文件的路径
   }
   \</syntaxhighlight\>
 * 插件依赖检查：如果使用第三方 QML 插件，确保相关的 \<code\>.so\</code\> 文件和资源文件按照上述规则放置

\== 常见问题解决 ==

\=== 找不到 QML 模块 ===

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

\=== 应用崩溃 ===

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

\=== 资源文件不可见 ===

 * 确认非 \<code\>.so\</code\> 文件是否正确放置在 \<code\>resources/resfile/qml/\</code\> 目录下

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

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

例如，如果您有一个名为 "MyCustomModule" 的模块： \<syntaxhighlight lang="text"\> libs/arm64-v8a/qml/MyCustomModule/libmycustommodule.so resources/resfile/qml/MyCustomModule/MyComponent.qml resources/resfile/qml/MyCustomModule/qmldir \</syntaxhighlight\>

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