Synchronizer QML Type

在两个或多个属性之间同步值。更多...

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

属性

• sourceObject : QtObject
• sourceProperty : string
• targetObject : QtObject
• targetProperty : string

信号

• valueBounced(QtObject object, string property)
• valueIgnored(QtObject object, string property)

详细说明

Synchronizer 对象将两个或多个属性绑定在一起，使得其中任意一个属性的更改都会自动更新所有其他属性。在此过程中，任何属性的现有绑定关系均不会被破坏。 当两个属性之间的数据流向尚未确定时，可以使用 Synchronizer。例如，TextInput 可能使用模型值进行初始化，但在编辑完成后也应更新该模型值。

请考虑以下示例。

不使用 Synchronizer

// MyCustomTextInput.qml
Item {
    property string text
    function append(characters: string) { text += characters }
    [...]
}

您可能会倾向于从模型中填充 `text ` 属性，并在接收到 `textChanged ` 信号时更新模型。

// Does not work!
Item {
    id: root
    property string model: "lorem ipsum"
    MyCustomTextInput {
        text: root.model
        onTextChanged: root.model = text
    }
}

这种做法行不通。当调用append 函数时，text 属性会被修改，而从model 属性更新该属性的绑定关系也会因此中断。下次当model 被独立更新时，text 将不再被更新。

要解决此问题，您可以完全省略绑定，仅使用信号来更新这两个属性。这样一来，您就需要放弃绑定带来的便利。

或者，你可以使用 Synchronizer。

使用 Synchronizer

Item {
    id: root
    property string model: "lorem ipsum"
    MyCustomTextInput {
        Synchronizer on text {
            property alias source: root.model
        }
    }
}

Synchronizer 确保无论模型还是文本发生变化，另一个都会随之更新。

您可以通过以下几种方式指定要同步的属性：

• 使用on 语法
• 填充 `sourceObject ` 和 `sourceProperty ` 属性
• 设置targetObject 和targetProperty 属性
• 在同步器作用域内创建别名

以下示例同步了四个不同的属性，并演示了所有不同的选项：

Item {
    id: root
    property string model: "lorem ipsum"

    MyCustomTextInput {
        Synchronizer on text {
            sourceObject: other
            sourceProperty: "text"

            targetObject: root.children[0]
            targetProperty: "objectName"

            property alias source: root.model
            property alias another: root.objectName
        }
    }

    MyCustomTextInput {
        id: other
    }
}

可选地，Synchronizer 将执行初始同步：

• 如果其中一个别名名为source ，则将使用它来初始化其他属性。
• 否则，如果分配给sourceObject 和sourceProperty 的值表示一个属性，则该属性将作为初始同步的源。
• 否则，如果使用了on 语法，则以此方式创建同步器的属性将作为初始同步的来源。
• 否则，将不执行初始同步。只有当其中一个属性发生变化时，其他属性才会被更新。

Synchronizer会自动消除抖动。当它使用给定值作为源进行同步时，不会接受来自预期为更新目标的属性之一的进一步更新。否则，这种行为很容易导致无限更新循环。 Synchronizer 使用valueBounced 信号来通知此情况。此外，它还会检测那些“静默拒绝”更新的属性，并为此类属性发出valueIgnored 信号。在此上下文中，“静默”是指在调用给定属性的设置器后未发出变更信号。

如果待同步的属性类型不同，将应用常规的 QML 类型强制转换。

属性文档

sourceObject : QtObject

该属性包含 sourceObject/sourceProperty 对中的 sourceObject 部分，二者共同指定 Synchronizer 将进行同步的属性之一。

sourceProperty : string

该 sourceProperty 存储了源属性（sourceProperty）部分，该部分与源属性（sourceObject ）/源属性（sourceProperty）对共同构成，二者可共同指定 Synchronizer 将进行同步的属性之一。

targetObject : QtObject

该属性包含 targetObject/targetProperty 对中的 targetObject 部分，二者共同指定 Synchronizer 将进行同步的属性之一。

targetProperty : string

该 targetProperty 包含targetObject/targetProperty 配对中的 targetProperty 部分，二者结合可指定 Synchronizer 将进行同步的属性之一。

信号文档

valueBounced(QtObject object, string property)

如果object 的property 在同步过程中拒绝了对其值的设置尝试，并返回了一个不同的值，则会发出此信号。此类波动值将被忽略，且不会触发新一轮的同步。

valueIgnored(QtObject object, string property)

如果作为同步过程的一部分，尝试设置object 的property 的值时，该信号会被触发。