通过 JavaScript 动态创建 QML 对象 JavaScript 宿主环境

在 QML 中定义 JavaScript 资源

QML 应用程序的程序逻辑可以使用 JavaScript 定义。JavaScript 代码既可以直接内联在 QML 文档中，也可以单独保存为 JavaScript 文件（在 QML 中称为“JavaScript Resources ”）。

QML支持两种不同的JavaScript资源：代码后端实现文件和共享（库）文件。这两种JavaScript资源均可被其他JavaScript资源导入，或包含在QML模块中。

代码后端实现资源

导入到 QML 文档中的大多数 JavaScript 文件，都是针对导入它们的 QML 文档的状态化实现。在这种情况下，文档中定义的每个 QML 对象实例都需要一份独立的 JavaScript 对象和状态副本，才能正常工作。

导入 JavaScript 文件时的默认行为是为每个 QML 组件实例提供一个唯一且隔离的副本。如果该 JavaScript 文件未使用 `.import ` 语句导入任何资源或模块，其代码将在与 QML 组件实例相同的作用域内运行，因此可以访问并操作该 QML 组件中声明的对象和属性。否则，它将拥有自己的独立作用域，若需要使用 QML 组件的对象和属性，应将其作为参数传递给 JavaScript 文件中的函数。

以下是一个“代码 behind”实现资源的示例：

// MyButton.qml
import QtQuick 2.0
import "my_button_impl.js" as Logic // A new instance of this JavaScript resource
                                    // is loaded for each instance of Button.qml.

Rectangle {
    id: rect
    width: 200
    height: 100
    color: "red"

    MouseArea {
        id: mousearea
        anchors.fill: parent
        onClicked: Logic.onClicked(rect)
    }
}

// my_button_impl.js
var clickCount = 0;   // this state is separate for each instance of MyButton
function onClicked(button) {
    clickCount += 1;
    if ((clickCount % 5) == 0) {
        button.color = Qt.rgba(1,0,0,1);
    } else {
        button.color = Qt.rgba(0,1,0,1);
    }
}

通常，简单的逻辑应直接在 QML 文件中内联定义，但更复杂的逻辑应分离到“代码后”实现资源中，以提高可维护性和可读性。

共享的 JavaScript 资源（库）

默认情况下，从 QML 导入的 JavaScript 文件与 QML 组件共享上下文。这意味着 JavaScript 文件可以访问相同的 QML 对象并对其进行修改。因此，每次导入都必须拥有这些文件的唯一副本。

上一节介绍了 JavaScript 文件的状态化导入。然而，有些 JavaScript 文件是无状态的，其作用更类似于可重用库——它们提供了一组辅助函数，这些函数无需依赖导入它们的位置。如果您像以下示例所示，使用特殊的 pragma 标记此类库，则可以节省大量内存并加快 QML 组件的实例化速度。

// factorial.js
.pragma library

var factorialCount = 0;

function factorial(a) {
    a = parseInt(a);

    // factorial recursion
    if (a > 0)
        return a * factorial(a - 1);

    // shared state
    factorialCount += 1;

    // recursion base-case.
    return 1;
}

function factorialCallCount() {
    return factorialCount;
}

该pragma声明必须出现在任何 JavaScript 代码（不包括注释）之前。

请注意，多个 QML 文档可以导入 `"factorial.js" ` 并调用它提供的 `factorial` 和 `factorialCallCount` 函数。该 JavaScript 导入的状态在所有导入它的 QML 文档之间共享，因此，当在从未调用过 `factorial` 函数的 QML 文档中调用 `factorialCallCount` 函数时，其返回值可能不为零。

例如：

// Calculator.qml
import QtQuick 2.0
import "factorial.js" as FactorialCalculator // This JavaScript resource is only
                                             // ever loaded once by the engine,
                                             // even if multiple instances of
                                             // Calculator.qml are created.

Text {
    width: 500
    height: 100
    property int input: 17
    text: "The factorial of " + input + " is: " + FactorialCalculator.factorial(input)
}

由于是共享的，.pragma库文件无法直接访问QML组件实例对象或属性，尽管可以将QML值作为函数参数传递。

从 JavaScript 动态创建 QML 对象 JavaScript 宿主环境

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.