<qqml.h> - Functions to register C++ types to QML

函数文档

template <typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool createIfMissing = true)

该模板函数的形式为：

template<typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool createIfMissing = true)

该函数返回由附加类型T 附加到指定attachee 上的附加对象实例。

如果 `attachee ` 为 `nullptr`，则返回 `nullptr`。

如果存在类型为T的已附加对象实例，则返回该实例。否则，如果createIfMissing 为true 且T是有效的附加类型，则返回新创建的实例；否则，返回nullptr 。

另请参阅 QML_ATTACHED() 和提供附加属性。

void qmlClearTypeRegistrations()

清除所有已存储的类型注册，例如通过qmlRegisterType() 生成的注册。

此函数仅影响应用程序的全局缓存。请删除QQmlEngine 以清除与该引擎相关的所有缓存数据。

QObject *qmlExtendedObject(QObject *base)

该函数返回属于base 的扩展对象（如有）。否则，返回nullptr 。

另请参阅 QML_EXTENDED 。

bool qmlProtectModule(const char *uri, int majVersion)

此函数可防止对模块进行进一步修改。这可用于阻止其他插件向您的模块注入类型。此外，它还能提升性能，因为当执行到此导入语句时，引擎可以跳过对新类型或新插件存在的检查。

一旦调用了 qmlProtectModule，QML 引擎将不再搜索新的qmldir 文件来加载该模块。不过，它会复用之前已加载的任何qmldir 文件。 因此，此时已存在的类型仍可正常工作。请注意，不同的 QML 引擎可能会加载不同的模块。然而，模块保护是全局的，会影响所有引擎。在文件系统速度较慢的情况下，查找qmldir 文件和加载插件的开销可能会比较明显。 因此，一旦确定不再需要加载某个模块，对其进行保护便是一种有效的优化手段。还需注意，模块锁定不仅影响插件，还影响其他任何 `qmldir` 指令（如 `import ` 或 `prefer`），以及在 `qmldir ` 文件中声明的任何复合类型或脚本。

此外，调用此函数后，任何尝试将 C++ 类型注册到该 URI 和主版本号组合中的操作都将导致运行时错误。

如果找到了模块标识符为uri 、主版本号为majVersion 的模块并已将其锁定，则返回 true；否则返回 false。该模块必须包含导出类型才能被找到。

template <typename T> int qmlRegisterAnonymousType(const char *uri, int versionMajor)

此模板函数将 C++ 类型作为匿名类型注册到 QML 系统中。生成的 QML 类型没有名称。因此，无法通过 QML 系统创建该类型的实例。不过，当该类型的实例作为其他类型的属性暴露出来时，您可以访问它们。

当类型不会被按名称引用时，请使用此函数，特别是对于用作属性绑定左侧的 C++ 类型。要指定该类型所属的模块，请使用 `uri ` 和 `versionMajor`。

例如，考虑以下两个类：

class Bar : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QString baz READ baz WRITE setBaz NOTIFY bazChanged)

public:
    Bar() {}

    QString baz() const { return mBaz; }

    void setBaz(const QString &baz)
    {
        if (baz == mBaz)
            return;

        mBaz = baz;
        emit bazChanged();
    }

signals:
    void bazChanged();

private:
    QString mBaz;
};

class Foo : public QObject
{
    Q_OBJECT
    Q_PROPERTY(Bar *bar READ bar CONSTANT FINAL)

public:
    Foo() {}

    Bar *bar() { return &mBar; }

private:
    Bar mBar;
};

在 QML 中，我们将一个字符串赋值给bar 的baz 属性：

Foo {
    bar.baz: "abc"
    Component.onCompleted: print(bar.baz)
}

为了让 QML 引擎知道Bar 类型具有baz 属性，我们必须声明Bar ：

qmlRegisterType<Foo>("App", 1, 0, "Foo");
qmlRegisterAnonymousType<Bar>("App", 1);

由于Foo 类型是在 QML 中实例化的，因此必须将其注册到接受元素名称的qmlRegisterType() 版本中。

返回 QML 类型的 ID。

另请参阅 QML_ANONYMOUS 以及《选择 C++ 与 QML 之间的正确集成方法》。

template <typename T, typename E> int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

此模板函数将 C++ 类型及其扩展对象注册到 QML 系统中，名称为qmlName ，位于从uri 导入的库中，其版本号由versionMajor 和versionMinor 组成。主类型中不存在的属性将在扩展对象中进行查找。

返回 QML 类型 ID。

另请参阅 QML_EXTENDED()、qmlRegisterType() 以及《注册扩展对象》。

template <typename T, typename E> int qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)

此模板函数将 C++ 类型及其扩展注册到 QML 系统中，名称为qmlName ，位于从uri 导入的库中，其版本号由versionMajor 和versionMinor 组成。

虽然该类型具有名称和类型，但无法被创建。如果用户尝试创建该类型的实例，系统将显示包含指定reason 的错误消息。

这在以下情况下非常有用：该类型仅用于提供附加属性、枚举值或作为其扩展的抽象基类。

返回 QML 类型 ID。

另请参阅 QML_EXTENDED()、QML_UNCREATABLE() 和qmlRegisterUncreatableType()。

void qmlRegisterModule(const char *uri, int versionMajor, int versionMinor)

该函数将一个模块注册到特定的uri 中，其版本由versionMajor 和versionMinor 中指定的版本决定。

这可用于使某个模块的特定版本可用，即使该版本尚未注册任何类型。这对于保持相关模块版本的同步尤为有用。

void qmlRegisterModuleImport(const char *uri, int moduleMajor, const char *import, int importMajor = QQmlModuleImportLatest, int importMinor = QQmlModuleImportLatest)

为主要版本为moduleMajor 的模块uri 注册一个 qmldir-import。

这与 qmldir 文件中的import 语句效果相同：每当导入版本为moduleMajor 的uri 时，版本为importMajor 的import 以及importMinor 也会被自动导入。如果importMajor 为QQmlModuleImportLatest ，则导入该模块的最新可用版本，此时importMinor 无关紧要。如果importMinor 为QQmlModuleImportLatest ，则选择importMajor 的最新次要版本。如果importMajor 为QQmlModuleImportAuto ，则import 的版本即为正在导入的uri 的版本，此时importMinor 无关紧要。 如果moduleMajor 为QQmlModuleImportModuleAny ，则该模块导入规则将适用于uri 的任何主版本。例如，您可以指定每当导入任何版本的 MyModule 时，都应导入 MyOtherModule 的最新版本。此时，以下调用是合适的：

qmlRegisterModuleImport("MyModule", QQmlModuleImportModuleAny,
                        "MyOtherModule", QQmlModuleImportLatest);

或者，您可以指定：每当导入“MyModule”的主版本 5 时，应导入“MyOtherModule”的 3.14 版本：

qmlRegisterModuleImport("MyModule", 5, "MyOtherModule", 3, 14);

最后，如果您希望每次导入“MyModule”时都导入“MyOtherModule”的同一版本，请指定如下内容：

qmlRegisterModuleImport("MyModule", QQmlModuleImportModuleAny,
                        "MyOtherModule", QQmlModuleImportAuto);

另请参阅 qmlUnregisterModuleImport()。

template <typename T, int metaObjectRevision> int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)

此模板函数在 QML 系统中，将 C++ 类型 `T ` 注册到指定的修订版本 `metaObjectRevision ` 下，并使用从 `uri ` 导入的库，该库的版本号由 `versionMajor ` 和 `versionMinor` 组合而成。

返回 QML 类型 ID。

template<typename T, int metaObjectRevision>
int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor);

该函数通常用于注册基类的修订版本，以便在指定类型的版本中使用（参见“类型修订与版本”）。

int qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *cppObject)

该函数用于注册一个单例对象cppObject ，并指定特定的uri 和typeName 。其版本由versionMajor 和versionMinor 组合而成。

将单例类型安装到 URI 中，可让您向 QML 代码提供任意功能（方法和属性），而无需客户端单独实例化该类型的各个实例。

使用此函数将给定类型 T 的对象注册为单例类型。

QObject 的单例类型可以通过其注册时的类型名称进行引用；反过来，该类型名称可作为Connections 类型中的目标，或像任何其他类型ID一样使用。 但是，有一个例外：QObject 的单例类型属性不能被别名化，因为单例类型名称无法识别与任何其他项目位于同一组件内的对象。

注意：qmlRegisterSingleton 仅在该模块的所有类型均通过过程化方式注册时才可使用。

用法：

// First, define your QObject which provides the functionality.
class SingletonTypeExample : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)

public:
    explicit SingletonTypeExample(QObject* parent = nullptr) : QObject(parent) {}

    Q_INVOKABLE int doSomething()
    {
        setSomeProperty(5);
        return m_someProperty;
    }

    int someProperty() const { return m_someProperty; }
    void setSomeProperty(int val) {
        if (m_someProperty != val) {
            m_someProperty = val;
            emit somePropertyChanged(val);
        }
    }

signals:
    void somePropertyChanged(int newValue);

private:
    int m_someProperty = 0;
};

// Second, create an instance of the object

// allocate example before the engine to ensure that it outlives it
QScopedPointer<SingletonTypeExample> example(new SingletonTypeExample);
QQmlEngine engine;

// Third, register the singleton type provider with QML by calling this
// function in an initialization function.
qmlRegisterSingletonInstance("Qt.example.qobjectSingleton", 1, 0, "MyApi", example.get());

要在 QML 中使用已注册的单例类型，必须导入对应版本的 URI。

import QtQuick 2.0
import Qt.example.qobjectSingleton 1.0
Item {
    id: root
    property int someValue: MyApi.someProperty

    Component.onCompleted: {
        console.log(MyApi.doSomething())
    }
}

另请参阅 QML_SINGLETON和qmlRegisterSingletonType 。

int qmlRegisterSingletonType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)

该函数可用于将名称为qmlName 的单例类型注册到从uri 导入的库中，该库的版本号由versionMajor 和versionMinor 组成。该类型由位于url 的 QML 文件定义。url 必须是绝对 URL，即 url.isRelative() == false。

此外，该类型的 QML 文件必须在其导入语句中包含 pragma Singleton 语句。

单例类型可通过其注册时使用的类型名进行引用，该类型名可作为 `Connections ` 类型中的目标，或像其他任何类型标识符一样使用。 唯一例外是：单例类型的属性不能被别名（因为单例类型名无法标识与任何其他项位于同一组件内的对象）。

用法：

// First, define your QML singleton type which provides the functionality.
pragma Singleton
import QtQuick 2.0
Item {
    property int testProp1: 125
}

// Second, register the QML singleton type by calling this function in an initialization function.
qmlRegisterSingletonType(QUrl("file:///absolute/path/SingletonType.qml"), "Qt.example.qobjectSingleton", 1, 0, "RegisteredSingleton");

要在 QML 中使用已注册的单例类型，必须导入该单例类型。

import QtQuick 2.0
import Qt.example.qobjectSingleton 1.0
Item {
    id: root
    property int someValue: RegisteredSingleton.testProp1
}

此外，也可以不使用 qmlRegisterSingletonType 函数来注册 QML 单例类型。方法是在该类型的 QML 文件的导入语句中添加一个 pragma Singleton 语句。 此外，该类型必须在 qmldir 文件中使用 singleton 关键字进行定义，且使用该单例的 QML 文件必须导入该 qmldir 文件。

另请参阅 QML_SINGLETON。

int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QJSValue (QQmlEngine *, QJSEngine *)> callback)

该函数可用于在特定的uri 和typeName 中注册单例类型提供程序callback ，其版本在versionMajor 和versionMinor 中指定。

安装单例类型可让开发人员向客户端提供任意功能（方法和属性），而无需客户端实例化该类型的单个实例。

单例类型可以是QObject 或QJSValue 。应使用此函数注册一个单例类型提供程序函数，该函数将返回一个QJSValue 作为单例类型。

注意： QJSValue 单例类型属性在发生变更时不会触发绑定重新评估。

用法：

// First, define the singleton type provider function (callback).
static QJSValue example_qjsvalue_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
{
    Q_UNUSED(engine)

    static int seedValue = 5;
    QJSValue example = scriptEngine->newObject();
    example.setProperty("someProperty", seedValue++);
    return example;
}

// Second, register the singleton type provider with QML by calling this function in an initialization function.
qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", example_qjsvalue_singletontype_provider);

此外，您还可以使用 C++11 lambda 表达式：

qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QJSValue {
    Q_UNUSED(engine)

    static int seedValue = 5;
    QJSValue example = scriptEngine->newObject();
    example.setProperty("someProperty", seedValue++);
    return example;
});

要在 QML 中使用已注册的单例类型，必须导入该单例类型。

import QtQuick 2.0
import Qt.example.qjsvalueApi 1.0 as ExampleApi
Item {
    id: root
    property int someValue: ExampleApi.MyApi.someProperty
}

另请参阅 QML_SINGLETON以及《选择 C++ 与 QML 之间的正确集成方法》。

template <typename T> int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QObject *(QQmlEngine *, QJSEngine *)> callback)

该函数可用于在特定的uri 和typeName 中注册单例类型提供程序callback ，其版本在versionMajor 和versionMinor 中指定。

将单例类型安装到 URI 中，可让开发人员向客户端提供任意功能（方法和属性），而无需客户端实例化该类型的单独实例。

单例类型可以是QObject 或QJSValue 。应使用此函数注册一个单例类型提供函数，该函数返回给定类型 T 的QObject 作为单例类型。

QObject 单例类型可通过其注册时使用的类型名称进行引用，该类型名称可作为Connections 类型中的目标，或像其他任何类型标识符一样使用。唯一例外是，QObject 单例类型属性不得被别名化。

注意：由单例类型提供程序返回的QObject 单例类型实例归QML引擎所有，除非该对象显式设置了QQmlEngine::CppOwnership标志。

用法：

// First, define your QObject which provides the functionality.
class SingletonTypeExample : public QObject
{
    Q_OBJECT
    Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)

public:
    SingletonTypeExample(QObject *parent = nullptr)
        : QObject(parent), m_someProperty(0)
    {
    }

    ~SingletonTypeExample() {}

    Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; }

    int someProperty() const { return m_someProperty; }
    void setSomeProperty(int val) { m_someProperty = val; emit somePropertyChanged(val); }

signals:
    void somePropertyChanged(int newValue);

private:
    int m_someProperty;
};

// Second, define the singleton type provider function (callback).
static QObject *example_qobject_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
{
    Q_UNUSED(engine)
    Q_UNUSED(scriptEngine)

    SingletonTypeExample *example = new SingletonTypeExample();
    return example;
}

// Third, register the singleton type provider with QML by calling this function in an initialization function.
qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", example_qobject_singletontype_provider);

此外，您还可以使用 C++11 lambda 表达式：

qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QObject * {
    Q_UNUSED(engine)
    Q_UNUSED(scriptEngine)

    SingletonTypeExample *example = new SingletonTypeExample();
    return example;
});

要在 QML 中使用已注册的单例类型，必须导入该单例类型。

import QtQuick 2.0
import Qt.example.qobjectSingleton 1.0
Item {
    id: root
    property int someValue: MyApi.someProperty

    Component.onCompleted: {
        someValue = MyApi.doSomething()
    }
}

另请参阅 QML_SINGLETON和《选择正确的 C++ 与 QML 集成方法》。

template <typename T> int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

此模板函数将该 C++ 类型以名称 `qmlName` 注册到 QML 系统中，该类型位于从uri 导入的库中，其版本号由versionMajor 和versionMinor 组合而成。

返回 QML 类型标识符。

该模板函数有两种形式：

template<typename T>
int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);

template<typename T, int metaObjectRevision>
int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);

前者是标准形式，用于将类型T注册为新类型。后者允许将类的特定修订版注册到指定版本中（参见“类型修订版与版本”）。

例如，以下代码将 C++ 类MySliderItem 作为名为Slider 的 QML 类型，注册到名为“com.mycompany.qmlcomponents”的类型命名空间的 1.0 版本中：

qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents", 1, 0, "Slider");

注册完成后，通过导入指定的类型命名空间和版本号，即可在 QML 中使用该类型：

import com.mycompany.qmlcomponents 1.0

Slider {
    // ...
}

请注意，库将类型注册为比其实际版本更早的版本是完全合理的。事实上，即使某些类型已有更高级的版本可用，新库仍应确保针对旧版本编写的 QML 代码能够继续正常运行，这是很常见的做法。

另请参阅 QML_ELEMENT 、QML_NAMED_ELEMENT() 以及《选择 C++ 与 QML 之间的正确集成方法》。

int qmlRegisterType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)

该函数在 QML 系统中注册一个名为qmlName 的类型，该类型位于从uri 导入的库中，其版本号由versionMajor 和versionMinor 组成。该类型由位于url 的 QML 文件定义。url 必须是绝对 URL，即 url.isRelative() == false。

通常，QML 文件可以直接从其他 QML 文件中加载为类型，或者通过 qmldir 文件加载。此函数允许从 C++ 代码中将文件注册为类型，例如当需要在启动时通过过程化方式确定类型映射时。

如果注册不成功，则返回 -1。

int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)

该函数在 QML 系统中注册了一个名为qmlName 的类型，该类型位于从uri 导入的类型命名空间中，其版本号由versionMajor 和versionMinor 组合而成，但任何尝试实例化该类型的操作都会引发给定的错误message 。

通常，插件导出的类型应为固定值。但是，如果某个 C++ 类型不可用，您至少应“预留”相应的 QML 类型名称，并向使用该不可用类型的用户提供有意义的错误信息。

返回 QML 类型 ID。

示例：

#ifdef NO_GAMES_ALLOWED
qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!");
#else
qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game");
#endif

这将导致任何导入“MinehuntCore”类型命名空间并尝试使用该类型的 QML 代码产生错误信息：

fun.qml: Get back to work, slacker!
   Game {
   ^

如果不这样做，系统将返回“Game 不是一种类型”这一通用错误信息。

另请参阅 QML_UNAVAILABLE 、qmlRegisterUncreatableType() 以及《选择正确的 C++ 与 QML 集成方法》。

int qmlRegisterUncreatableMetaObject(const QMetaObject &staticMetaObject, const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &reason)

该函数将staticMetaObject 及其扩展在QML系统中注册，名称为qmlName ，位于从uri 导入的库中，其版本号由versionMajor 和versionMinor 组成。

无法创建该元对象的实例。若用户尝试创建该实例，系统将显示包含给定reason 的错误信息。

此函数用于注册Q_NAMESPACE 命名空间。

返回 QML 类型标识符。

例如：

namespace MyNamespace {
  Q_NAMESPACE
  enum MyEnum {
      Key1,
      Key2,
  };
  Q_ENUM_NS(MyEnum)
}

//...
qmlRegisterUncreatableMetaObject(MyNamespace::staticMetaObject, "io.qt", 1, 0, "MyNamespace", "Access to enums & flags only");

在 QML 端，现在可以使用已注册的枚举：

Component.onCompleted: console.log(MyNamespace.Key2)

另请参阅 QML_ELEMENT 、QML_NAMED_ELEMENT() 和QML_UNCREATABLE()。

template <typename T> int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString &message)

此模板函数将该 C++ 类型以名称 `qmlName` 注册到 QML 系统中，该类型位于从uri 导入的库中，其版本号由versionMajor 和versionMinor 组成。

虽然该类型具有名称和类型，但无法被创建，若尝试创建，将引发message 错误。

当该类型仅用于提供附加属性或枚举值时，此功能非常有用。

返回 QML 类型 ID。

另请参阅 QML_UNCREATABLE()、qmlRegisterTypeNotAvailable() 以及《选择 C++ 与 QML 之间的正确集成方法》。

int qmlTypeId(const char *uri, int versionMajor, int versionMinor, const char *qmlName)

返回在特定uri 中以名称qmlName 注册、且版本由versionMajor 和versionMinor 指定的类型的 QML 类型 ID。

该函数返回的值与 QML 类型注册函数（如qmlRegisterType() 和qmlRegisterSingletonType()）返回的值相同。

如果qmlName 、uri 和versionMajor 与某个已注册的类型匹配，但versionMinor 中指定的次版本号更高，则返回次版本号最接近的类型的 ID。

如果未找到匹配的类型，或者给定的参数之一无效，则返回 -1。

另请参阅 QML_ELEMENT 、QML_NAMED_ELEMENT 、QML_SINGLETON、qmlRegisterType() 以及qmlRegisterSingletonType()。

void qmlUnregisterModuleImport(const char *uri, int moduleMajor, const char *import, int importMajor = QQmlModuleImportLatest, int importMinor = QQmlModuleImportLatest)

删除先前通过qmlRegisterModuleImport() 注册的模块导入

moduleMajor 调用此函数可确保当版本为uri （版本号importMajor ）的模块被导入时，版本为 （importMinor ）的import 不再被自动导入。版本解析机制与qmlRegisterModuleImport() 相同。

另请参阅 qmlRegisterModuleImport()。