Qt QML 的变化

Qt 6 是有意识地使框架更高效、更易用的结果。

我们努力在每个版本中保持所有公共 API 的二进制和源代码兼容性。但为了使 Qt 成为一个更好的框架，有些改动是不可避免的。

在本专题中，我们总结了 Qt QML 中的这些变化，并提供了处理这些变化的指导。

QML 语言

URL 解析

在 Qt 5 中，相对 url 通常是直接解析的，尽管并不一致，尤其是分配给 url 属性时。在 Qt 6 中，情况不再如此。

如果您有一个存储在"/home/qml/example.qml "下的 QML 文件，而 "example.qml "包含了

property url imageFolder: "./images"

那么 url 属性将存储 URL"/home/qml/images"。这使得在 Qt Qml 中无法以这种方式使用相对 URL，因此在 Qt Qml 6 中，URL 保持相对，只有在需要时才会被解析（例如，当它被用作图像组件的源时）。如果您依赖于旧的行为，可以使用Qt.resolvedUrl

例如，如果您有如下代码

property url imageFolder: "./images"

的代码，您可以将其重写为

property url imageFolder: Qt.resolvedUrl("./images")

Qt.resolvedUrl 可在 Qt 5 和 6 中使用。

作为移植辅助工具，可将QML_COMPAT_RESOLVE_URLS_ON_ASSIGNMENT 环境变量设为 1 以获得 Qt 5 行为。这在 Qt 6.2.2 中是可行的。不过，建议仅在解封端口时使用此变量，并如上所述使用Qt.resolvedUrl 。

变量属性

variant 属性，自 Qt 5 起已被标记为过时，现在的处理方式与 属性完全相同。依赖于赋值给变量属性时触发的隐式字符串转换的代码应更新为显式创建一个正确类型的对象。var

例如，如果代码中包含

property variant myColor: "red"

的代码，可以重写为

property variant myColor: Qt.color("red")

对于可解析为

• color（使用 Qt.color 代替）、
• 日期（使用日期对象代替）、
• rect（使用 Qt.rect 代替）和
• 尺寸（使用 Qt.size 代替）

variant 在 Qt 6 中仍然是一个废弃的关键字，不过强烈建议新代码使用 属性来代替。var

源代码不兼容的 API 更改

已更改的 API

QQmlListProperty的CountFunction 和AtFunction 已改为使用qsizetype 而不是int ，以便与 Qt 容器中的相应更改保持一致。

例如，如果您有类似

int myCountFunction(QQmlListProperty<MyType> *);
MyType *myAtFunction(QQmlListProperty<MyType> *, int);

QQmlListProperty<MyType> myReadOnlyList(containingObject, container, &myCountFunction,
                                        &myAtFunction);

这样的代码，您可以将其重写为

qsizetype myCountFunction(QQmlListProperty<MyType> *);
MyType *myAtFunction(QQmlListProperty<MyType> *, qsizetype);

QQmlListProperty<MyType> myReadOnlyList(containingObject, container, &myCountFunction,
                                        &myAtFunction);

需要同时支持 Qt 5 和 Qt 6 的代码可以使用 Qt 5 中的int 和 Qt 6 中的qsizetype 类型定义，或者使用QList::size_type ，它已经是这样一个类型别名。

删除的 API

删除了各种过时的函数。

• 获取引用的QQmlListProperty 构造函数已被删除。

  例如，如果您有以下代码

  QQmlListProperty<QObject>(owner, owner->objectList);

  的代码，可以重写为

  QQmlListProperty<QObject>(owner, &owner->objectList);
• 函数qmlDebug,qmlInfo,qmlWarning,qmlContext 和qmlEngine 曾经同时存在于全局命名空间（或命名空间构建中的 Qt XML 命名空间）和QtQml 命名空间中。现在这些函数只存在于全局命名空间中。

  例如，如果您有以下代码

  QQmlEngine *engine = QtQml::qmlEngine(qmlObject);

  的代码，可以将其重写为

  QQmlEngine *engine = qmlEngine(qmlObject);
• qmlRegisterType 已删除不带参数的重载。请使用qmlRegisterAnonymousType 代替，或使用QML_ANONYMOUS 切换到声明式类型注册。

  例如，如果您有如下代码

  class AnonymousType : public QObject {
    // ...
  };
  
  qmlRegisterType<AnonymousType>();

  的代码，可以将其重写为

  class AnonymousType : public QObject {
    // ...
  };
  
  qmlRegisterAnonymousType<AnonymousType>("MyModule", 1);

  或者

  class AnonymousType : public QObject {
      QML_ANONYMOUS
      // ...
  };
• qmlRegisterExtendedType 和qmlRegisterInterface 中不包含版本参数的重载已被删除。请使用提供版本的重载，或改用QML_EXTENDED 和QML_INTERFACE 进行声明式类型注册。

  例如，如果您有以下代码

  struct GreetInterface
  {
     virtual ~GreetInterface();
     virtual void greet();
  };
  Q_DECLARE_INTERFACE(GreetInterface, "org.hi.GreetInterface")
  
  qmlRegisterInterface<GreetInterface>("Greeter");

  这样的代码，可以重写为

  struct GreetInterface
  {
     virtual ~GreetInterface();
     virtual void greet();
  };
  Q_DECLARE_INTERFACE(GreetInterface, "org.hi.GreetInterface")
  
  qmlRegisterInterface<GreetInterface>("Greeter", 1);

  或者

  struct GreetInterface
  {
     QML_INTERFACE(Greeter)
     virtual ~GreetInterface();
     virtual void greet();
  };
  Q_DECLARE_INTERFACE(GreetInterface, "org.hi.GreetInterface")

  注意： 在新代码中，应优先选择声明式类型注册。

• 函数QJSValue::engine 已被删除。如果需要访问引擎，则必须存储引擎引用。
• qmlAttachedPropertiesObjectById 和 已被删除。请使用 重载 。qmlAttachedPropertiesObject(int *, const QObject *, const QMetaObject *, bool) qmlAttachedPropertiesObject(QObject *, QQmlAttachedPropertiesFunc, bool) qmlAttachedPropertiesObject
• QJSEngine::installTranslatorFunctions QJSEngine::installExtensions 可作为替代。

  例如，如果您有以下代码

  QJSEngine engine;
  engine.installTranslatorFunctions();

  的代码，可以将其重写为

  QJSEngine engine;
  engine.installExtensions(QJSEngine::TranslationExtension);