Qt for HarmonyOS/user development/how to pass args to main guiad zh

Qt for HarmonyOS：Qt main() 启动参数传递用户开发指南

本文档说明如何把启动参数传递到 Qt for HarmonyOS 应用的 main(int argc, char *argv[])，以及如何通过 Want / hdc shell aa start 注入参数。

注意

hdc shell aa ... 仅用于调试验证，不建议作为正式产品功能入口。

1. Qt 侧参数拼接规则

Qt OHOS 平台插件会从启动配置或启动 Want 读取参数，并拼装成传给 main() 的 argv。

拼接规则（重点）：

• argv[0]：Qt 加载到的应用共享库路径（如 .../libs/arm64/lib<app>.so）。
• argv[1...]：来自 appArgs 的字符串参数列表。
  • 如果在工程内固定传参（QAbilityStage.ets 的 appArgs）：直接作为 argv[1...]，不会为 want.uri 预留占位。
  • 如果通过 Want 传参（io.qt.appArgs / io.qt.appArgsJson）：默认会先插入 want.uri 作为 argv[1]，即使 uri 为空也会占位。
    • 可通过 want.parameters["io.qt.useUriAsArg"] = false 关闭该占位（见下方示例）。

2. 传参方式一：工程内固定传参

在 Qt 鸿蒙工程模板的 AbilityStage 启动配置里设置 appArgs（字符串数组），Qt 会把它透传给 main()。 此路径会优先于 Want 参数；启用后，不会插入 want.uri 占位。

示例（ohostemplateforqtapplication/entry/src/main/ets/qabilitystage/QAbilityStage.ets）：

private static appArgs = ["va1", "va2"];

3. 传参方式二：Want 参数

要让 Want 参数生效，需要在 ETS 侧显式构造 Want 并调用 context.startAbility(...) 启动 QAbility（或使用 hdc shell aa start 从外部启动）。 工程模板默认只包含系统拉起的启动流程；如果希望在工程内触发并传参，需要在入口 Ability/页面中添加 startAbility 调用。

示例（在可获取 UIAbilityContext 的位置）：

import Want from '@ohos.app.ability.Want';

const want: Want = {
bundleName: '<bundlename>',
abilityName: 'QAbility',
parameters: {
"io.qt.useUriAsArg": false,
"io.qt.appArgs": ["va1", "va2"]
// 或 "io.qt.appArgsJson": '["va1","va2"]'
}
};

this.context.startAbility(want);

Qt 会在 want.parameters 下读取以下键（当未在工程内固定传参时生效）：

3.1 io.qt.appArgs：Array<string>（N-API 的 Napi::Array）

要求：值必须是“数组类型”，且数组元素必须全是字符串；否则 Qt 会进行类型检查并抛异常终止进程（表现为启动后崩溃）。

JS/TS 中 Want.parameters 的正确数据形态：

{
parameters: {
"io.qt.useUriAsArg": false,
"io.qt.appArgs": ["va1", "va2"]
}
}

3.2 io.qt.appArgsJson：string（JSON 数组字符串）

当外部工具只能传 string 时（例如 hdc shell aa start --ps），使用该键。

示例 value（注意这是字符串内容，不是数组类型）：

["va1","va2"]

3.3 hdc shell aa start 调试示例

由于 io.qt.appArgsJson 键的值必须是合法的 JSON 字符串（包含双引号），在不同的操作系统终端下，需要注意转义规则以防止双引号被 Shell 剥离。

macOS / Linux (zsh 或 bash)

在 macOS 上，最简单的方法是使用单引号 ' 包裹整个 JSON 字符串。

推荐写法： :

hdc shell aa start -a QAbility -b <bundlename> --ps io.qt.appArgsJson '["va1","va2"]'

Windows (CMD)

Windows CMD 不支持单引号包裹。必须使用双引号，并对内部的双引号进行转义。

推荐写法（使用反斜杠）： :

hdc shell aa start -a QAbility -b <bundlename> --ps io.qt.appArgsJson \"[\"va1\",\"va2\"]\"

调试要点汇总

1. 参数占位：走 Want 传参时，want.uri 默认会占用 argv[1]；你的自定义参数通常从 argv[2] 开始。
2. 禁用 URI 占位：若希望自定义参数从 argv[1] 开始，请显式传入布尔值参数 io.qt.useUriAsArg：

hdc shell aa start -a QAbility -b <bundlename> --pb io.qt.useUriAsArg false --ps io.qt.appArgsJson '["va1","va2"]'

错误辨析： 如果应用崩溃并报错 input is not valid JSON string， 通常是因为双引号在传递过程中丢失了（变成了 [va1,va2]），请重新检查转义。

4. 应用侧接收参数示例（main.cpp）

#include <QApplication>
#include <QMainWindow>
#include <QDebug>

int main(int argc, char *argv[])
{
QApplication a(argc, argv);

QMainWindow mainwindow;
qDebug() &lt;&lt; QString(&quot;argc=%1&quot;)
            .arg(argc);

for (int i = 0; i &lt; argc; ++i) {
    qDebug()&lt;&lt;QString(&quot;argv[%1]=%2&quot;).arg(i).arg(argv[i] ? argv[i] : &quot;(null)&quot;);
}

mainwindow.show();

return a.exec();


}