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

From Qt Wiki
Jump to navigation Jump to search

中文 English

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

简介

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

部署架构概述

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

ohos模板工程根目录

├── entry

│   ├── libs

│   │   └── arm64-v8a

│   │       ├── libqt相关.so文件

│   │       ├── 应用的.so文件

│   │       └── qml/（保持原目录结构的.so文件）

│   └── src

│       └── main

│           └── resources

│               └── resfile

│                   └── qml/（保持原目录结构的非.so文件）

手动部署步骤

1. 准备工作

首先，确保您有：

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

2. 创建必要的目录结构

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

# 为.so文件创建目录
mkdir -p entry/libs/arm64-v8a/qml
mkdir -p entry/libs/arm64-v8a/plugins

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


3. 复制 Qt 核心库文件

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

# 将 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 库...

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

4. 复制 Qt 插件

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

# 复制所有插件目录及文件，保持目录结构
cp -r <Qt 安装目录>/plugins/* entry/libs/arm64-v8a/

5. 处理 QML 模块文件

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

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

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

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


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

# 创建目标目录
mkdir -p entry/libs/arm64-v8a/qml/QtQuick/Controls

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

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

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

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

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

# 创建目标目录
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/

6. 完整手动部署案例

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

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

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 模块：
  import QtQuick 2.12
  import QtQuick.Controls 2.12
  • 资源路径使用：在 QML 代码中引用资源时，使用相对路径，如：
    Image {
      source: "images/button.png"  // 相对于当前 QML 文件的路径
  }
  • 插件依赖检查：如果使用第三方 QML 插件，确保相关的 .so 文件和资源文件按照上述规则放置

常见问题解决

找不到 QML 模块

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

应用崩溃

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

资源文件不可见

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

自定义 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

总结

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

Retrieved from "https://wiki.qt.io/index.php?title=Qt_for_HarmonyOS/user_development/how_to_deply_qml_app_zh&oldid=44644"