此文档包含我们在文档编制和范例中遵循的 QML 编码约定,并推荐其它人遵循。
纵观文档编制和范例, QML 对象属性 始终按以下次序被构造化:
为提高可读性,我们采用空行分隔这些不同部分。
例如,假设 photo QML 对象看起来像这样:
Rectangle { id: photo // id on the first line makes it easy to find an object property bool thumbnail: false // property declarations property alias image: photoImage.source signal clicked // signal declarations function doSomething(x) // javascript functions { return x + photoImage.width } color: "gray" // object properties x: 20 // try to group related properties together y: 20 height: 150 width: { // large bindings if (photoImage.width > 200) { photoImage.width; } else { 200; } } Rectangle { // child objects id: border anchors.centerIn: parent; color: "white" Image { id: photoImage anchors.centerIn: parent } } states: State { // states name: "selected" PropertyChanges { target: border; color: "red" } } transitions: Transition { // transitions from: "" to: "selected" ColorAnimation { target: border; duration: 200 } } }
若使用来自一组特性中的多个特性,考虑使用 组表示法 而不是 点表示法 若它能改进可读性。
例如,这样:
Rectangle { anchors.left: parent.left; anchors.top: parent.top; anchors.right: parent.right; anchors.leftMargin: 20 } Text { text: "hello" font.bold: true; font.italic: true; font.pixelSize: 20; font.capitalization: Font.AllUppercase }
可以像这样编写:
Rectangle { anchors { left: parent.left; top: parent.top; right: parent.right; leftMargin: 20 } } Text { text: "hello" font { bold: true; italic: true; pixelSize: 20; capitalization: Font.AllUppercase } }
If a list contains only one element, we generally omit the square brackets.
For example, it is very common for a component to only have one state.
In this case, instead of:
states: [ State { name: "open" PropertyChanges { target: container; width: 200 } } ]
we will write this:
states: State { name: "open" PropertyChanges { target: container; width: 200 } }
若脚本是单个表达式,推荐内联编写它:
Rectangle { color: "blue"; width: parent.width / 3 }
若脚本只有几行长,一般来说使用块:
Rectangle { color: "blue" width: { var w = parent.width / 3 console.debug(w) return w } }
若脚本超过几行长或可以用于不同对象,推荐创建函数并像这样调用它:
function calculateWidth(object) { var w = object.width / 3 // ... // more javascript code // ... console.debug(w) return w } Rectangle { color: "blue"; width: calculateWidth(parent) }
对于长脚本,将函数放入 JavaScript 文件并像这样 import 它:
import "myscript.js" as Script Rectangle { color: "blue"; width: Script.calculateWidth(parent) }
若代码长于一行并因此在块中,使用分号指示每条语句结束:
MouseArea { anchors.fill: parent onClicked: { var scenePos = mapToItem(null, mouseX, mouseY); console.log("MouseArea was clicked at scene pos " + scenePos); } }