Binding QML Type

支持任意创建属性绑定。更多...

• 所有成员的列表，包括继承的成员

属性

• delayed : bool
• property : string
• restoreMode : enumeration
• target : QtObject
• value : var
• when : bool

详细说明

在 QML 中，属性绑定会在不同对象的属性之间建立依赖关系。

绑定到不可访问的属性

有时需要将一个对象的属性绑定到另一个未由 QML 直接实例化的对象的属性上，例如由 C++ 导出到 QML 的类的某个属性。您可以使用 Binding 类型来建立这种依赖关系；将任意值绑定到任意对象的属性上。

例如，在将“app.enteredText”属性映射到 QML 的 C++ 应用程序中，您可以使用 Binding 来更新 enteredText 属性。

TextEdit { id: myTextField; text: "Please type here..." }
Binding { app.enteredText: myTextField.text }

当 `text ` 发生变化时，C++ 属性 `enteredText ` 将自动更新。

条件绑定

在某些情况下，您可能希望在满足特定条件时修改属性的值，否则保持不变。通常，直接绑定无法实现这一点，因为您必须为所有可能的分支提供值。

例如，下面的代码片段会在您释放鼠标时触发警告。这是因为当鼠标未被按下时，绑定的值是未定义的。

// produces warning: "Unable to assign [undefined] to double value"
targetProperty: if (mouse.pressed) mouse.mouseX

Binding 类型可以避免此警告。

Binding on targetProperty {
    when: mouse.pressed
    value: mouse.mouseX
}

Binding 类型可恢复该属性上先前设置的任何直接绑定。

然而，对Binding 的value 属性的绑定仍会无条件地进行求值，即使when 的false 。

当 Binding 用于防止值变为null 时，这可能会引发警告：

Binding on targetProperty {
    when: root.object !== null
    //  produces warning: "TypeError: Cannot read property 'someProperty' of null"
    value: root.object.someProperty
}

有两种方法可以避免此问题：

• 如果目标具有id ，您可以使用Multiple targets in one Binding 中描述的语法，这也会导致绑定表达式仅在Binding 启用时才运行：

  Binding {
      when: root.object !== null
      root.targetProperty: root.object.someProperty
  }

• 您可以在绑定中重复进行该检查，并提前返回：

  Binding on targetProperty {
      when: root.object !== null
      value: {
          if (root.object === null)
              return
          return root.object.someProperty
      }
  }

一个 Binding 中的多个目标

你可以在一个 Binding 元素中为同一个对象指定多个绑定：

Text {
    id: t1
}

Binding {
    t1 {
        color: "#00FF00"
        text: "green text"
    }
}

您还可以在单个 Binding 元素中指定多个具有不同目标对象的绑定：

Text {
    id: t1
}

Text {
    id: t2
}

Binding {
    t1.text: "Foo"
    t2.text: "Bar"
}

另请参阅 Qt Qml.

属性文档

delayed : bool

该属性用于指定绑定是否应延迟执行。

延迟绑定不会立即更新目标，而是等待事件队列清空后再进行更新。这既可作为一种优化手段，也可用于防止中间值被赋值。

Binding {
    contactName.text.value: givenName + " " + familyName
    when: list.ListView.isCurrentItem
    delayed: true
}

property : string

待更新的属性。

如果表达式最终访问的是值类型的属性，则该属性可以是组属性。例如：

Item {
    id: item

    property rect rectangle: Qt.rect(0, 0, 200, 200)
}

Binding {
    target: item
    property: "rectangle.x"
    value: 100
}

只有当无法以声明式方式提供绑定目标时，才需要使用此属性。以下代码片段与上述绑定等效，但更为简洁：

Binding { item.rectangle.x: 100 }

restoreMode : enumeration

该属性可用于描述在禁用绑定时，是否应恢复原始值以及如何恢复。

可能的取值为：

默认值为Binding.RestoreBindingOrValue 。

target : QtObject

待更新的对象。如果绑定目标没有id 属性（例如，当目标是单例时），则需要使用此属性。否则，以下两段代码是等效的：

Binding { contactName.text: name }

Binding {
    target: contactName
    property: "text"
    value: name
}

前者更为简洁，但无法在运行时替换目标对象或属性。而后者则可以。

value : var

要设置在目标对象和属性上的值。这可以是一个常量（虽然用处不大），也可以是一个绑定表达式。

只有当无法通过声明式方式提供绑定目标时，才需要使用此属性。否则，可以直接绑定到目标。

when : bool

当绑定处于活动状态时，此属性有效。若希望绑定处于活动状态，应将此属性设置为一个在满足条件时求值为 true 的表达式。

Binding {
    contactName.text: name
    when: list.ListView.isCurrentItem
}

默认情况下，当绑定失效时，之前设置的任何绑定或值都会被恢复。您可以通过restoreMode 属性自定义恢复行为。

另请参阅 restoreMode 。