变更内容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”。这种行为使得无法以这种方式在 Qml 中使用相对 URL，因此在 Qt 6 中，URL 仍保持相对形式，仅在必要时（例如用作 Image 组件的来源时）才会进行解析。 如果您依赖旧的行为，可以使用Qt.resolvedUrl

例如，如果你有如下代码

property url imageFolder: "./images"

你可以将其重写为

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

Qt.resolvedUrl 在 Qt 5 和 Qt 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），
• date（请改用 Date 对象），
• rect（请改用 Qt.rect）以及
• size（请改用 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 的代码，既可以使用 typedef（在 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命名空间），也存在于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 的qmlAttachedPropertiesObject(QObject *, QQmlAttachedPropertiesFunc, bool) 重载版本。
• QJSEngine::installTranslatorFunctions 已被移除。QJSEngine::installExtensions 可作为替代方案。

  例如，如果您有如下代码：

  QJSEngine engine;
  engine.installTranslatorFunctions();

  你可以将其重写为

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