Qt 文档

使用说明

简介

QML Live 采用模块化结构，以满足各种使用需求。

在项目的早期阶段，通常，您想使用 QML Live 通用台，其中包含典型桌面应用程序中的所有内容。

在项目的后期，您可能希望在设备上测试您的 UI 代码。为此，您可以将 QML Live 通用台与 QML Live 运行时 结合使用。这种组合为您提供在设备上运行默认的 QML 渲染器的功能，以及在桌面上进行控制的简易远程应用程序。

对于 C++ 开发者，使用 LiveNodeEngine 类和几行代码将这些 QML Live 集成到自己的自定义运行时中，然后使用 QML Live 通用台进行控制。

QML Live 通用台

QML Live 通用台是全面的 QML 实时重载工具，允许您选择要监视的工作区，并为选定的 QML 文档提供高级 QML Live 运行时。所谓的“高级 QML Live 运行时”是一种特殊的运行时，跟随当前选定的 .qml 文件。相比之下，QML Live 通用台允许您同时预览多个文件。

QML Live Bench

要启动通用台，请运行以下命令

$(QMLIVEPROJECT)/bin/qmllivebench[.exe]

您可以按以下方式将命令行参数传递给 QML Live 通用台

qmllivebench [options] <workspace>
qmllivebench [options] <workspace/file.qml>

以下选项受支持

选项	描述
`-version`	显示版本信息。
`-pluginpath`	指定 QML Live 插件路径。
`-importpath`	指定 QML 导入路径。
`-stayontop`	保持查看器窗口在顶部。
`-addhost <name, address[,port]>`	添加或更新远程主机配置，然后退出。
`-rmhost <name>`	删除指定的远程主机配置，然后退出。
`-probehost <name>`	建议指定的主机在线并连接；意味着 `-remotely`。
`-noremote`	不要尝试与正在运行的通用台通信；不要监听远程连接。
`-remoteonly`	与正在运行的通用台通信；如果没有运行的通用台则不执行任何操作。
`-ping`	检查是否有正在运行的通用台并接受远程连接。
`-maxdirwatch <number>`	限制要监视更改的目录数量。
`-project`	加载包含工作区路径、导入路径和主文档的 JSON 格式的项目 `.qmllive` 文档。

以下参数受支持

参数	描述
`workspace`	指定要监视的工作区文件夹。如果该文件夹指向一个 QML 文档，则假设该目录是工作区，该文件是活动文档。
`document`	最初要加载的主 QML 文档。

要预览其他文件，在工作区导航器中右键单击文件，然后选择“在新窗口中打开”。

集成到 Qt Creator

您可以将 QML Live 通用台集成到 Qt Creator 中，作为外部工具。要这样做

从 Qt Creator 中，打开 设置/选项 对话框。
打开环境组。 外部工具 选项卡位于此处。
在可执行下，输入您的 QML Live Bench 可执行文件的路径。

Qt Creator

QML Live Bench 现已可在 工具 > 外部 > QML Live Bench 下使用。为了方便地启动 QML Live Bench，您还可以为该工具分配一个快捷键。

Qt Creator

现在当您按住 Alt+F8 时，QML Live Bench 会以当前项目根文件夹作为工作空间打开。

Qt Creator

QML Live 运行时

QML Live 运行时工具提供了一个默认运行环境，带有默认的 QML 查看器，监听指定端口以接收来自远程的 IPC 调用。当不需要额外的 C++ 代码时，该工具非常适合在目标设备上进行开发。

QML Live Runtime

要调用运行时，运行以下命令

$(QMLIVEPROJECT)/bin/qmlliveruntime[.exe]

要使用运行时，运行以下命令

qmlliveruntime [options] <workspace>

以下选项受支持

选项	描述
`-version`	显示版本信息。
`-ipcport <端口号>`	IPC 监听的端口号。
`-updates-as-overlay`	允许查看器以只读工作区接收更新。
`-update-on-connect`	最初更新所有工作区文档。这是一个阻塞选项。
`-pluginpath`	指定 QML Live 插件路径。
`-importpath`	指定 QML 导入路径。
`-fullscreen`	以全屏模式显示查看器窗口。
`-transparent`	使查看器窗口透明。
`-frameless`	在没有窗口框架的情况下运行查看器。
`-stayontop`	保持查看器窗口在顶部。
`-allow-create-missing`	允许在工作区中创建新文档。没有此选项时，更新只会被接受现有的工作区文档。
`-title`	设置窗口标题。
`-hidebuttons`	隐藏窗口控制按钮（关闭、最小化、最大化）。

并非所有项目都设计得允许设计器在独立的面板或屏幕上工作。有时，可能需要将整个项目部署到目标设备上以运行它。通常接收更新需要对这些部署文件具有写访问权限。但是，根据目标平台，项目可能被部署到用户无法写入的位置。在大多数情况下，部署后修改文件权限可能有所帮助。但是，一个更简便的方法是让 QML Live 运行时将所有更新存储在可写入的工作区覆盖中。使用 -updates-as-overlay 选项启用此功能。

在应用程序启动后更新文档时，您可能会遇到其他约束。如果遇到这种情况，则可以使用 -update-on-connect 选项。当使用此选项时，在实例化任何 QML 组件之前，会更新所有工作区文档。

自定义运行时

您可以使用 QML Live 功能创建自己的自定义运行时。这样，您可以将您的 QML 视图配置与额外的 C++ 代码一起与 QML Live 系统一起使用。

为此，您需要使用 LiveNodeEngine 类来能够接收工作区更改和活动文档更新。默认情况下，IPC 在端口 49156 上监听。

以下代码示例展示了最小自定义 QML Live 运行时。

#include <QtGui>
#include <QtQuick>

// Use QML Live headers
#include "livenodeengine.h"
#include "remotereceiver.h"
#include "constants.h"

class MyQmlApplicationEngine : public QQmlApplicationEngine
{
    Q_OBJECT

public:
    MyQmlApplicationEngine(const QString &mainQml); // Perform some setup here

    QString mainQml() const;
    QQuickWindow *mainWindow();
    QList<QQmlError> warnings() const;

    // ...
};

int main(int argc, char **argv)
{
    QGuiApplication app(argc, argv);
    MyQmlApplicationEngine engine(QStringLiteral("qml/customruntime-window.qml"));

    if (!qEnvironmentVariableIsSet("MY_APP_ENABLE_QMLLIVE"))
        return app.exec();

#if defined(QT_NO_DEBUG)
    qWarning() << "QML Live support was disabled at compile time";
#else
    LiveNodeEngine node;

    // Let QML Live know your runtime
    node.setQmlEngine(&engine);

    // Allow it to display QML components with non-QQuickWindow root object
    QQuickView fallbackView(&engine, 0);
    node.setFallbackView(&fallbackView);

    // Tell it where file updates should be stored relative to
    node.setWorkspace(app.applicationDirPath(),
                      LiveNodeEngine::AllowUpdates | LiveNodeEngine::UpdatesAsOverlay);

    // Listen to IPC call from remote QML Live Bench
    RemoteReceiver receiver;
    receiver.registerNode(&node);
    receiver.listen(Constants::DEFAULT_PORT());

    // Advanced use: let it know the initially loaded QML component (do this
    // only after registering to receiver!)
    node.usePreloadedDocument(engine.mainQml(), engine.mainWindow(), engine.warnings());
#endif

    return app.exec();
}

在支持 pkg-config 的平台中，如果您的构建主机已安装 QML Live，请将以下行添加到您的项目文件中。

CONFIG += link_pkgconfig
PKGCONFIG += qmllive

另一个选项是将一切直接编译到您的应用程序中，通过在项目文件中包括 $(QMLLIVEPROJECT)/src/src.pri 实现。