Привязка свойств

Свойству объекта может быть присвоено статическое значение, которое остается постоянным до тех пор, пока ему явно не будет присвоено новое значение. Однако, чтобы в полной мере использовать QML и его встроенную поддержку динамического поведения объектов, большинство QML-объектов используют привязки свойств.

Привязки свойств — это ключевая функция QML, которая позволяет разработчикам задавать взаимосвязи между различными свойствами объектов. Когда зависимости свойства изменяются, свойство автоматически обновляется в соответствии с заданной взаимосвязью.

Внутри QML-движка отслеживаются зависимости свойства (то есть переменные в выражении привязки). При обнаружении изменения QML-движок повторно вычисляет выражение привязки и применяет новый результат к свойству.

Обзор

Для создания привязки свойства свойству присваивается выражение JavaScript, которое вычисляется до желаемого значения. В самом простом случае привязкой может быть ссылка на другое свойство. Рассмотрим следующий пример, где высота синего прямоугольника Rectangle привязана к высоте его родителя:

Rectangle {
    width: 200; height: 200

    Rectangle {
        width: 100
        height: parent.height
        color: "blue"
    }
}

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

Привязка может содержать любое допустимое выражение или оператор JavaScript, поскольку QML использует совместимый с стандартами движок JavaScript. Привязки могут обращаться к свойствам объектов, вызывать методы и использовать встроенные JavaScript-объекты, такие как Date и Math. Ниже приведены другие возможные привязки для предыдущего примера:

height: parent.height / 2

height: Math.min(parent.width, parent.height)

height: parent.height > 100 ? parent.height : parent.height/2

height: {
    if (parent.height > 100)
        return parent.height
    else
        return parent.height / 2
}

height: someMethodThatReturnsHeight()

Ниже приведен более сложный пример, включающий больше объектов и типов:

Column {
    id: column
    width: 200
    height: 200

    Rectangle {
        id: topRect
        width: Math.max(bottomRect.width, parent.width/2)
        height: (parent.height / 3) + 10
        color: "yellow"

        TextInput {
            id: myTextInput
            text: "Hello QML!"
        }
    }

    Rectangle {
        id: bottomRect
        width: 100
        height: 50
        color: myTextInput.text.length <= 10 ? "red" : "blue"
    }
}

В предыдущем примере,

• topRect.width зависит от bottomRect.width и column.width
• topRect.height зависит от column.height
• bottomRect.color зависит от myTextInput.text.length

Синтаксически привязки могут иметь произвольную сложность. Однако, если привязка слишком сложна — например, включает несколько строк или императивные циклы — это может указывать на то, что привязка используется для чего-то большего, чем описание взаимосвязей свойств. Сложные привязки могут снизить производительность кода, читабельность и поддерживаемость. Возможно, стоит перепроектировать компоненты со сложными привязками или, по крайней мере, вынести привязку в отдельную функцию.

Создание привязок свойств из JavaScript

Свойство с привязкой автоматически обновляется по мере необходимости. Однако, если свойству позже присваивается статическое значение из оператора JavaScript, привязка будет удалена.

Например, прямоугольник Rectangle ниже первоначально гарантирует, что его height всегда в два раза больше его width. Однако, когда нажимается клавиша пробела, текущее значение width*3 будет присвоено height как статическое значение. После этого height останется фиксированным в этом значении, даже если width изменится. Присвоение статического значения удаляет привязку.

import QtQuick 2.0

Rectangle {
    width: 100
    height: width * 2

    focus: true
    Keys.onSpacePressed: {
        height = width * 3
    }
}

Если цель — присвоить прямоугольнику фиксированную высоту и остановить автоматическое обновление, то это не проблема. Однако, если цель — установить новые взаимосвязи между width и height, то новое выражение привязки необходимо обернуть в функцию Qt.binding():

import QtQuick 2.0

Rectangle {
    width: 100
    height: width * 2

    focus: true
    Keys.onSpacePressed: {
        height = Qt.binding(function() { return width * 3 })
    }
}

Теперь, после нажатия клавиши пробела, высота прямоугольника будет продолжать автоматически обновляться, всегда будучи в три раза больше его ширины.

Отладка перезаписи привязок

Распространённая причина ошибок в QML-приложениях — случайная перезапись привязок статическими значениями из операторов JavaScript. Чтобы помочь разработчикам отслеживать проблемы такого рода, QML-движок может генерировать сообщения всякий раз, когда привязка теряется из-за императивного присваивания.

Для генерации таких сообщений необходимо включить информационный вывод для категории регистрации qt.qml.binding.removal, например, вызвав:

QLoggingCategory::setFilterRules(QStringLiteral("qt.qml.binding.removal.info=true"));

Дополнительную информацию об включении вывода из категорий регистрации см. в документации к QLoggingCategory.

Обратите внимание, что в некоторых случаях перезапись привязок вполне допустима. Любое сообщение, сгенерированное QML-движком, следует рассматривать как средство диагностики, а не как доказательство проблемы без дальнейшего исследования.

Использование this с привязкой свойства

При создании привязки свойства из JavaScript можно использовать ключевое слово this, чтобы сослаться на объект, который получает привязку. Это полезно для разрешения неоднозначностей с именами свойств.

Например, обработчик Component.onCompleted ниже определен в области видимости Item. В этой области видимости width относится к ширине Item, а не ширине Rectangle. Чтобы привязать height Rectangle к его собственной width, выражение привязки должно явно ссылаться на this.width (или, альтернативно, на rect.width):

Item {
    width: 500
    height: 500

    Rectangle {
        id: rect
        width: 100
        color: "yellow"
    }

    Component.onCompleted: {
        rect.height = Qt.binding(function() { return this.width * 2 })
        console.log("rect.height = " + rect.height) // prints 200, not 1000
    }
}

Примечание: Значение this не определено вне привязок свойств. Подробности см. в разделе Ограничения среды JavaScript.