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

'''中文''' [[Qt_for_HarmonyOS/user_development_guide/how_to_deply_qml_app|English]]

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

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

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

<pre>
HarmonyOS模板工程根目录
├── entry
│   ├── libs
│   │   └── arm64-v8a
│   │       ├── Qt-related .so files
│   │       ├── Application .so files
│   │       └── qml/ (保持原目录结构的.so文件)
│   └── src
│       └── main
│           └── resources
│               └── resfile
│                   └── qml/ (保持原目录结构的非.so文件)
</pre>

== 手动部署步骤 ==

=== 1. 准备工作 ===
首先，确保您有：

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

=== 2. 创建必要的目录结构 ===
在应用工程目录中手动创建以下目录结构：<syntaxhighlight lang="shell">
# 为.so文件创建目录
mkdir -p entry/libs/arm64-v8a/qml

# 为 QML 资源文件创建目录
mkdir -p entry/src/main/resources/resfile/qml
</syntaxhighlight>


=== 3. 复制 Qt 核心库文件 ===
手动从 Qt 安装目录复制核心库文件到目标目录：<syntaxhighlight lang="bash">
# 将 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/
# 复制其他所需的 Qt 库...
</syntaxhighlight>

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

=== 4. 复制 Qt 插件 ===
保持目录结构，将 Qt 插件复制到目标目录：<syntaxhighlight lang="bash">
# 复制所有插件目录及文件，保持目录结构
cp -r <Qt 安装目录>/plugins/* entry/libs/arm64-v8a/
</syntaxhighlight>

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

==== A. 处理 QML 模块的 .so 文件 ====
遍历 Qt 安装目录中的 '''qml''' 目录，复制所有 '''.so''' 文件到 '''libs/arm64-v8a/qml''' 目录，保持原目录结构：

# 检查 Qt 安装目录中的 qml 文件夹
# 手动创建相应的目录结构
# 复制 .so 文件


例如，对于  <Qt 安装目录>/qml/QtQuick/Controls/libqtquickcontrolsplugin.so：<syntaxhighlight lang="bash">
# 创建目标目录
mkdir -p entry/libs/arm64-v8a/qml/QtQuick/Controls

# 复制.so文件
cp <Qt 安装目录>/qml/QtQuick/Controls/libqtquickcontrolsplugin.so entry/libs/arm64-v8a/qml/QtQuick/Controls/
</syntaxhighlight>

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

# 检查同一个 qml 文件夹
# 手动创建相应的目录结构
# 复制所有非 .so文件（如  .qml、.js 等）


例如，对于 <Qt 安装目录>/qml/QtQuick/Controls/Button.qml：<syntaxhighlight lang="bash">
# 创建目标目录
mkdir -p entry/src/main/resources/resfile/qml/QtQuick/Controls

# 复制非.so文件
cp <Qt 安装目录>/qml/QtQuick/Controls/Button.qml entry/src/main/resources/resfile/qml/QtQuick/Controls/
</syntaxhighlight>

=== 6. 完整手动部署案例 ===
假设我们需要部署 QtQuick.Controls 模块，手动步骤如下：<syntaxhighlight lang="bash">
QT_INSTALL_DIR=/home/user/qt/qt-5.12.12-harmonyos-arm

# 1. 在 Qt 安装目录查找该模块的所有文件
find <Qt 安装目录>/qml/QtQuick/Controls -type f

# 2. 创建相应的目录结构
mkdir -p entry/libs/arm64-v8a/qml/QtQuick/Controls
mkdir -p entry/src/main/resources/resfile/qml/QtQuick/Controls

# 3. 复制.so文件
find <Qt 安装目录>/qml/QtQuick/Controls -name "*.so" | while read sofile; do
  # 获取相对路径
  relpath=$(echo $sofile | sed "s|$QT_INSTALL_DIR/qml/||")
  # 复制到目标位置
  mkdir -p $(dirname "entry/libs/arm64-v8a/qml/$relpath")
  cp "$sofile" "entry/libs/arm64-v8a/qml/$relpath"
done

# 4. 复制非.so文件
find <Qt 安装目录>/qml/QtQuick/Controls -type f ! -name "*.so" | while read file; do
  # 获取相对路径
  relpath=$(echo $file | sed "s|$QT_INSTALL_DIR/qml/||")
  # 复制到目标位置
  mkdir -p $(dirname "entry/src/main/resources/resfile/qml/$relpath")
  cp "$file" "entry/src/main/resources/resfile/qml/$relpath"
done
</syntaxhighlight>

== QML 部署详解 ==

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

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

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

== 最佳实践 ==

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

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

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

* '''正确引用 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 插件，确保相关的 .so 文件和资源文件按照上述规则放置

== 常见问题解决 ==

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

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

=== 应用崩溃 ===

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

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

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

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

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

例如，如果您有一个名为 "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 设备上正常运行。开发者应当特别注意将 .so 文件和非 .so 文件正确分离到不同的目录，同时保持目录结构一致。通过遵循本文档的手动部署步骤，可以成功将 QML 应用部署到 HarmonyOS 平台。