Преобразование типов данных между QML и C++

При обмене значениями данных между QML и C++, движок QML преобразует их к соответствующим типам данных, подходящим для использования в QML или C++. Это требует, чтобы обменные данные имели тип, распознаваемый движком.

Движок QML предоставляет встроенную поддержку большого количества типов данных Qt C++. Кроме того, пользовательские типы C++ могут быть зарегистрированы в системе типов QML, чтобы сделать их доступными для движка.

На этой странице обсуждаются типы данных, поддерживаемые движком QML, и как они преобразуются между QML и C++.

Владение данными

При передаче данных из C++ в QML владение данными всегда остается у C++. Исключением из этого правила является случай, когда объект QObject возвращается из явного вызова метода C++: в этом случае движок QML принимает на себя владение объектом, если только владение объектом явно не установлено за C++ путем вызова QQmlEngine::setObjectOwnership() со значением QQmlEngine::CppOwnership.

Кроме того, движок QML соблюдает стандартные семантики владения родителями объектов QObject объектов Qt C++, и никогда не удалит экземпляр QObject, у которого есть родитель.

Основные типы данных Qt

По умолчанию QML распознаёт следующие типы данных Qt, которые автоматически преобразуются в соответствующий базовый тип QML при передаче из C++ в QML и наоборот:

Примечание: Классы, предоставляемые модулем Qt GUI, такие как QColor, QFont, QQuaternion и QMatrix4x4, доступны из QML только при включении модуля Qt Quick.

Для удобства многие из этих типов могут быть указаны в QML строковыми значениями или с помощью соответствующего метода, предоставляемого объектом QtQml::Qt. Например, свойство Image::sourceSize имеет тип size (что автоматически переводится в тип QSize) и может быть указано строковым значением, отформатированным как «widthxheight», или с помощью функции Qt.size():

Item {
    Image { sourceSize: "100x200" }
    Image { sourceSize: Qt.size(100, 200) }
}

Для получения дополнительной информации см. документацию по каждому отдельному типу в разделе Базовые типы QML.

Типы, производные от QObject

Любой класс, производный от QObject, может использоваться в качестве типа для обмена данными между QML и C++, при условии, что класс зарегистрирован в системе типов QML.

Движок позволяет регистрировать как экземпляризуемые, так и неэкземпляризуемые типы. После регистрации класса как типа QML его можно использовать в качестве типа данных для обмена данными между QML и C++. Подробную информацию о регистрации типов см. в разделе Регистрация типов C++ в системе типов QML.

Преобразование между типами Qt и JavaScript

Движок QML имеет встроенную поддержку преобразования ряда типов Qt в соответствующие типы JavaScript и наоборот при передаче данных между QML и C++. Это позволяет использовать эти типы и получать их в C++ или JavaScript без необходимости реализации пользовательских типов, обеспечивающих доступ к значениям данных и их атрибутам.

(Обратите внимание, что среда JavaScript в QML изменяет прототипы собственных объектов JavaScript, включая те, что относятся к String, Date и Number, чтобы предоставить дополнительные возможности. Дополнительные сведения см. в разделе Среда выполнения JavaScript.)

QVariantList и QVariantMap в JavaScript Array и Object

Движок QML предоставляет автоматическое преобразование между QVariantList и массивами JavaScript, а также между QVariantMap и объектами JavaScript.

Например, функция, определенная в QML ниже, ожидает два аргумента: массив и объект и выводит их содержимое с использованием стандартной синтаксической конструкции JavaScript для доступа к элементам массива и объекта. Ниже представлен код C++, который вызывает эту функцию, передавая QVariantList и QVariantMap, которые автоматически преобразуются в значения массива и объекта JavaScript соответственно:

// MyItem.qml
Item {
    function readValues(anArray, anObject) {
        for (var i=0; i<anArray.length; i++)
            console.log("Array item:", anArray[i])

        for (var prop in anObject) {
            console.log("Object item:", prop, "=", anObject[prop])
        }
    }
}

// C++
QQuickView view(QUrl::fromLocalFile("MyItem.qml"));

QVariantList list;
list << 10 << QColor(Qt::green) << "bottles";

QVariantMap map;
map.insert("language", "QML");
map.insert("released", QDate(2010, 9, 21));

QMetaObject::invokeMethod(view.rootObject(), "readValues",
        Q_ARG(QVariant, QVariant::fromValue(list)),
        Q_ARG(QVariant, QVariant::fromValue(map)));

Это приводит к выводу, подобному:

Array item: 10
Array item: #00ff00
Array item: bottles
Object item: language = QML
Object item: released = Tue Sep 21 2010 00:00:00 GMT+1000 (EST)

Аналогично, если тип C++ использует тип QVariantList или QVariantMap для типа свойства или параметра метода, значение может быть создано как массив или объект JavaScript в QML, и автоматически преобразуется в QVariantList или QVariantMap при передаче в C++.

QDateTime в JavaScript Date

Движок QML предоставляет автоматическое преобразование между значениями QDateTime и объектами JavaScript Date.

Например, функция, определенная в QML ниже, ожидает объект JavaScript Date, и также возвращает новый объект Date с текущей датой и временем. Код C++ ниже вызывает эту функцию, передавая значение QDateTime, которое автоматически преобразуется движком в объект Date при передаче в функцию readDate(). В свою очередь, функция readDate() возвращает объект Date, который автоматически преобразуется в значение QDateTime при получении в C++:

// MyItem.qml
Item {
    function readDate(dt) {
        console.log("The given date is:", dt.toUTCString());
        return new Date();
    }
}

// C++
QQuickView view(QUrl::fromLocalFile("MyItem.qml"));

QDateTime dateTime = QDateTime::currentDateTime();
QDateTime retValue;

QMetaObject::invokeMethod(view.rootObject(), "readDate",
        Q_RETURN_ARG(QVariant, retValue),
        Q_ARG(QVariant, QVariant::fromValue(dateTime)));

qDebug() << "Value returned from readDate():" << retValue;

Аналогично, если тип C++ использует QDateTime для типа свойства или параметра метода, значение может быть создано как объект JavaScript Date в QML, и автоматически преобразуется в значение QDateTime при передаче в C++.

QTime и JavaScript Date

Движок QML предоставляет автоматическое преобразование значений QTime в объекты JavaScript Date. Поскольку значения QTime не содержат компонента даты, при преобразовании создаётся компонент даты. Поэтому не следует полагаться на компонент даты полученного объекта Date.

Внутри движка преобразование объекта JavaScript Date в QTime выполняется путём преобразования в объект QDateTime и вызова его метода time().

Тип последовательности в JavaScript Array

Определённые типы C++ последовательностей прозрачно поддерживаются в QML как типы JavaScript Array.

В частности, QML в настоящее время поддерживает:

• QList<int>
• QList<qreal>
• QList<bool>
• QList<QString> и QStringList
• QVector<QString>
• std::vector<QString>
• QList<QUrl>
• QVector<QUrl>
• std::vector<QUrl>
• QVector<int>
• QVector<qreal>
• QVector<bool>
• std::vector<int>
• std::vector<qreal>
• std::vector<bool>

Эти типы последовательностей реализуются непосредственно на основе базовых типов C++. Существует два способа экспонирования таких последовательностей в QML: как свойство Q_PROPERTY указанного типа последовательности или как возвращаемый тип метода Q_INVOKABLE. Существуют некоторые различия в их реализации, которые важно отметить.

Если последовательность экспонируется как Q_PROPERTY, обращение к любому значению в последовательности по индексу вызовет чтение данных последовательности из свойства QObject, а затем чтение. Аналогично, изменение любого значения в последовательности вызовет чтение данных последовательности, а затем выполнение изменения и запись изменённой последовательности обратно в свойство QObject.

Если последовательность возвращается из функции Q_INVOKABLE, доступ и изменение намного дешевле, так как не происходит чтения или записи свойства QObject; вместо этого данные C++ последовательности обращаются и изменяются напрямую.

В обоих случаях, Q_PROPERTY и возврат из Q_INVOKABLE, элементы std::vector копируются. Эта операция копирования может быть дорогостоящей, поэтому следует использовать std::vector с осторожностью.

Другие типы последовательностей не поддерживаются прозрачно, и вместо этого экземпляр любого другого типа последовательности будет передан между QML и C++ как непрозрачный QVariantList.

Важно: Существуют некоторые незначительные различия в семантике таких типов последовательностей Array и стандартных типов массивов JavaScript, которые являются следствием использования типа хранения C++ в реализации. В частности, удаление элемента из массива приведет к замене этого элемента значением по умолчанию, а не значением Undefined. Аналогично, установка свойства length массива на значение, большее, чем его текущее значение, приведет к дополнению массива до указанной длины элементами по умолчанию вместо элементов Undefined. Наконец, контейнерные классы Qt поддерживают целочисленные (а не беззнаковые) индексы; поэтому попытка доступа к любому индексу, большему чем INT_MAX, завершится ошибкой.

Значения по умолчанию для каждого типа последовательности следующие:

Если вы хотите удалить элементы из последовательности, а не просто заменить их значениями по умолчанию, не используйте оператор удаления по индексу ("delete sequence[i]"), а вместо этого используйте функцию splice ("sequence.splice(startIndex, deleteCount)").

QByteArray в JavaScript ArrayBuffer

Двигатель QML обеспечивает автоматическое преобразование типов между значениями QByteArray и JavaScript ArrayBuffer объектами.

Типы значений

Некоторые типы значений в Qt, такие как QPoint, представлены в JavaScript как объекты, имеющие те же свойства и функции, что и в API C++. Такое же представление возможно и для пользовательских типов значений C++. Чтобы включить пользовательский тип значения с движком QML, объявление класса должно быть снабжено Q_GADGET. Свойства, которые должны быть видимы в представлении JavaScript, должны быть объявлены с помощью Q_PROPERTY. Аналогично функции должны быть помечены с помощью Q_INVOKABLE. Это также относится к API C++ на основе QObject. Например, класс Actor ниже помечен как gadget и имеет свойства:

class Actor
{
    Q_GADGET
    Q_PROPERTY(QString name READ name WRITE setName)
public:
    QString name() const { return m_name; }
    void setName(const QString &name) { m_name = name; }

private:
    QString m_name;
};

Q_DECLARE_METATYPE(Actor)

Типы перечислений

Чтобы использовать пользовательское перечисление как тип данных, его класс должен быть зарегистрирован, а само перечисление также должно быть объявлено с помощью Q_ENUM() для его регистрации в системе метаобъектов Qt. Например, класс Message ниже имеет перечисление Status.

class Message : public QObject
{
    Q_OBJECT
    Q_PROPERTY(Status status READ status NOTIFY statusChanged)
public:
    enum Status {
        Ready,
        Loading,
        Error
    };
    Q_ENUM(Status)
    Status status() const;
signals:
    void statusChanged();
};

После того, как класс Message был зарегистрирован в системе типов QML, его перечисление Status может быть использовано из QML:

Message {
     onStatusChanged: {
         if (status == Message.Ready)
             console.log("Message is loaded!")
     }
 }

Чтобы использовать перечисление как тип флагов в QML, см. Q_FLAG().

Примечание: Имена значений перечисления должны начинаться с заглавной буквы, чтобы быть доступными из QML.

Типы перечислений в качестве параметров сигналов и методов

Сигналы и методы C++ с параметрами типа перечисления могут быть использованы из QML, при условии, что перечисление и сигнал или метод объявлены в одном классе, или что значение перечисления является одним из тех, которые объявлены в Пространстве имен Qt.

Кроме того, если сигнал C++ с параметром типа перечисления должен быть подключен к функции QML с помощью функции connect(), тип перечисления должен быть зарегистрирован с помощью qRegisterMetaType().

Для сигналов QML значения перечислений могут передаваться в качестве параметров сигнала с использованием типа int:

Message {
    signal someOtherSignal(int statusValue)

    Component.onCompleted: {
        someOtherSignal(Message.Loading)
    }
}