qml的文件结构及其对象基本属性-阿里云开发者社区

QML介绍

QML 是一种用户界面规范和编程语言。它允许开发人员和设计师创建高性能、流畅的动画和视觉吸引人的应用程序。
QML 提供了一种高度可读、声明性、类似JSON 的语法，像脚本语言一样定义界面的元素,支持与动态属性绑定相结合的命令式 JavaScript 表达式。
QML 全称：Qt Meta Language 或 Qt Modelling Language，主要包含以下特征：

1.是对 ECMAScript 标准的扩展.（参见：JavaScript）
2.提供了建立一颗 QML 元素对象树的机制 ,支持 QML 元素和基于 QObject 的 C++ 对象之间的交互 QML 包含了一套 QML 元素图形的和行为的基础组成部分.
3.可以通过 QML 文档来建立更加复杂的元件和 QML 应用.

文件结构

一个QML文件就是一块QML源代码。

简单的QML代码包含了QML元素，它是以.qml为后缀名的文件或者文本，其编码方式为UTF-8。
QML默认不会导入任何的模块一个QML文件总是以至少一个import语句开始。Nothing is imported by default，其并没有包含什么代码，仅仅只是为了在运行时解释器寻找元素的定义.
一个QML文件要定义唯一的顶层QML组件
Self-contained：A）在执行之前并没有预处理机制；B）在运行时解释执行

语法上说，一个QML文件是自包含的，QML不包含在将文件提交给QML运行环境之前对其进行修改的预处理器。import语句并不会包含在将文件提交给QML运行环境之前对其进行修改的预处理器。

一般来说,一个qml文件结构分主要由三部分组成：import声明、对象和注释。

import语句

这个就像C++中的头文件,一个QML文件在文件顶部可能含有一个或多个import.
一个import声明可能为以下几种类型：

注册的是哪个版本的命名空间.

a relative directory which contains type-definitions as QML documents

一个JavaScript文件.
JavaScript file imports must be qualified when imported, so that the properties and methods they provide can be accessed.

import几种声明形式:

import Namespace VersionMajor.VersionMinor 
import Namespace VersionMajor.VersionMinor as SingletonTypeIdentifier 
import “directory” 
import “file.js” as ScriptIdentifier

import QtQuick 2.0
import projects.MyQMLProject.MyFunctions 1.0 as MyFuncs
import org.example.Functions 1.0 as TheirFuncs

QML对象

QML 对象类型是可以实例化 QML 对象的类型。
在语法方面，QML 对象类型是一种可用于通过指定类型名称后跟一组包含该对象属性的花括号来声明对象的类型。
例如，Rectangle 是一个 QML 对象类型：它可以用来创建 Rectangle 类型的对象。
自定义 QML 对象类型可以通过创建定义类型的 .qml 文件来定义，或者通过从 C++ 定义 QML 类型并将类型注册到 QML 引擎。请注意，在这两种情况下，类型名称都必须以大写字母开头，才能在 QML 文件中声明为 QML 对象类型。
在 QML 的代码结构中，对象属性的声明顺序通常是：

id

property declarations

signal declarations

JavaScript functions

object properties

child objects

states

transitions

为了更好的可阅读性，通常用空行来分隔这些不同部分。

对象声明中的属性(Attributes in Object Declarations)

id属性(The id Attribute)

QML 元素可以有一个id属性，作为该元素的名字。以后我们可以直接用这个名字指代该元素，相当于该元素的指针。

QML对象的id属性是唯一的，不同对象的id属性值不能相同，我们可通过某个对象的id属性来访问这个对象。

在不同的文件中可以有相同的id值，因为id值是在文件作用域进行解析的。

属性是QML语言内建的一个属性，在对象实例化完成后其值是不能被修改的，不同于其它的普通属性。

id属性值必须以小写字母或下划线开头，且不能包含字母、数字、下划线以外的其它字符.

自定义属性(Property Attributes)

property 是QML自定义属性修饰符。

声明:

[default] [required] [readonly] property <propertyType> <propertyName> [ : <value> ]

default、required 和 readonly 关键字是可选的，用于修改所声明属性的语义.

属性名称必须以小写字母开头，并且只能包含字母、数字和下划线。

声明自定义属性隐式地为该属性创建一个值更改信号，以及一个名为 onChanged 的关联信号处理程序，其中是属性的名称，首字母大写.

除了枚举类型之外的任何 QML 基本类型都可以用作自定义属性类型（枚举值只是整数值，可以用 int 类型代替）.

属性是类型安全的,只能为属性分配与属性类型匹配的值，否则会出错.

信号属性(Signal Attributes)

信号是来自对象的某个事件发生的通知：例如，属性已更改，动画已开始或停止，或已下载图像。例如，MouseArea 类型有一个 clicked 信号，当用户在鼠标区域内单击时会发出该信号。
每当发出特定信号时，都可以通过信号处理程序通知对象。使用语法 on 声明信号处理程序，其中是信号的名称，第一个字母大写。
信号处理程序必须在发出信号的对象的定义中声明，并且处理程序应包含在调用信号处理程序时要执行的 JavaScript 代码块。

信号属性的定义

可以通过注册类的 Q_SIGNAL 来为 C++ 中的类型定义信号，然后将其注册到 QML 类型系统。
或者，可以使用以下语法在 QML 文档的对象声明中定义对象类型的自定义信号：

signal <signalName>[([<type> <parameter name>[, ...]])]

试图在同一类型块中声明两个具有相同名称的信号是错误的。
但是，新信号可能会重用类型上现有信号的名称。（这应该谨慎进行，因为现有信号可能会被隐藏并且无法访问。）
以下是信号声明的三个示例：

import QtQuick 2.0
Item {
   signal clicked
   signal hovered()
   signal actionPerformed(string action, var actionResult)
}

如果信号没有参数，“()”括号是可选的。

如果使用参数，则必须声明参数类型，如上面 actionPerformed 信号的 string 和 var 参数。允许的参数类型与本页定义属性属性下列出的相同。

要发出信号，请将其作为方法调用。发出信号时将调用任何相关的信号处理程序，并且处理程序可以使用定义的信号参数名称来访问相应的参数。

属性变化信号

QML 类型还提供内置的属性更改信号，只要属性值发生更改，就会发出这些信号，如前面关于属性属性的部分所述。有关这些信号为何有用以及如何使用它们的更多信息，请参阅属性更改信号处理程序。

信号处理程序属性(Signal Handler Attributes)

信号处理程序是一种特殊的方法属性，只要发出相关信号，QML 引擎就会调用方法实现。将信号添加到 QML 中的对象定义会自动将关联的信号处理程序添加到对象定义中，默认情况下，该对象定义具有空实现。
客户端可以提供一个实现，来实现程序逻辑。

属性更改信号处理程序.

属性更改信号的信号处理程序采用on<Property>Changed语法形式.
其中 <Property> 是属性的名称，首字母大写。例如，虽然 TextInput 类型文档没有记录 textChanged 信号，但通过 TextInput 具有 text 属性这一事实可以隐式使用此信号，因此可以编写一个 onTextChanged 信号处理程序，以便在此属性更改时调用.

方法属性(Method Attributess)

对象类型的方法是可以调用以执行某些处理或触发进一步事件的函数。
方法可以连接到信号，以便在发出信号时自动调用它。
有关更多详细信息，请参阅描述信号和处理程序事件系统.

方法属性的定义

可以通过标记类的函数来为 C++ 中的类型定义方法，然后使用 Q_INVOKABLE 将其注册到 QML 类型系统，或者将其注册为类的 Q_SLOT。或者，可以使用以下语法将自定义方法添加到 QML 文档中的对象声明：

function <functionName>([<parameterName>[, ...]]) { <body> }

可以将方法添加到 QML 类型以定义独立的、可重用的 JavaScript 代码块。这些方法既可以在部调用，也可以由外部对象调用。
与信号不同，方法参数类型不必声明，因为它们默认为 var 类型。

尝试在同一类型块中声明两个具有相同名称的方法或信号是错误的。
但是，新方法可能会重用该类型上现有方法的名称。(这应该谨慎进行，因为现有方法可能会被隐藏并且无法访问.)

枚举属性(Enumeration Attributes)

枚举提供了一组固定的命名选项。它们可以在 QML 中使用 enum 关键字声明：

// MyText.qml
Text {
  enum TextType {
       Normal,
         Heading
    }
       property int textType: MyText.TextType.Normal
   
       font.bold: textType == MyText.TextType.Heading
       font.pixelSize: textType == MyText.TextType.Heading ? 24 : 12
}

其中,枚举类型（例如 TextType）和值（例如 Normal）必须以大写字母开头.

枚举类型值通过 .. 或 . 引用.

对象的特殊属性

qml的property（属性）有一些特殊的，如必要属性（Required Properties）、只读属性（Read-Only Properties）、默认属性（Default Properties）、分组属性（Grouped Properties）、属性别名（Property Aliases）、附加属性（Attached Properties）。
上述除了属性别名、附加属性以外的属性都是属于所定义的对象类型的，属性别名实质上是子对象属性的引用，属于子对象，而附加属性则属于附加类型（attached type），附加类型也可以理解成一个特殊的子对象（其实例化过程是隐式的）.

只读属性（Read-Only Properties）

对象声明可以使用 readonly 关键字定义只读属性，语法如下:

readonly property <propertyType> <propertyName> : <initialValue>

只读属性必须初始化，且不能修改，也不能是default属性和alias属性.

默认属性（Default Properties）

一个对象定义可以有一个默认属性。使用可选的 default 关键字声明属性将其标记为默认属性。
任何基于Item的类型都有一个data列表属性，这个属性就是该类型的默认属性，保存了所有的孩子对象，其中可视的孩子对象又保存在了children列表属性中，不可视的孩子对象保存在了resources列表属性中，在添加子对象时children、resources属性可写可不写，都会自动添加到对应的属性列表中.QML 对象中.

所有的 QML 实体对象都会默认归属到一个链表属性中，并且建立起父子关系（QtObject 除外，Item 及其 C++ 派生类有效，在 QML 中重新设定默认属性的无效）。

QML 中自定义默认链表属性( default property list<T> defaultProperies),不会与实例化后的内部对象实体建立起父子关系,只能手动设置父子关系。了解更多可查看Qt默认属性扩展知识

属性别名（Property Aliases）

属性别名引用其它的属性，语法如下：

[default] property alias <name>: <alias reference>

name是我们自定以的属性名，alias reference是属性别名所引用的那个属性或对象，也就是说属性别名可以引用自一个单一的属性，也可以引用自一个复杂的对象。
属性绑定是动态的，但不是双向的，而通过属性别名可达到动态、双向的效果，即修改name和aliasreference中任一个的值，与之关联的另一个属性值也会随之改变.

属性别名限制

只能引用在声明别名的类型范围内的对象或对象的属性。

它不能包含任意的 JavaScript 表达式。

它不能引用在其类型范围之外声明的对象。

它在首次声明别名时必须提供别名引用。

它不能引用附加属性。

它不能引用深度为 3 或更大的层次结构内的属性。

属性别名注意点

如果属性别名与已有的属性名相同，就会把已有的属性 覆盖掉。

不能在对alias属性继续alias。

在整个组件初始化完毕之后才可以使用。

列表属性(List Properties)

定义对象列表值的语法是用方括号括起来的逗号分隔列表，语法如下：

[ <item 1>, <item 2>, ... ]

可以使用以下语法在对象声明中指定列表类型属性：
[default] property list<<objectType>> propertyName.

如果列表包含单个项目，则可以省略方括号.

分组属性（Grouped Properties）

在某些情况下，属性包含子属性属性的逻辑组。可以使用点表示法或组表示法来分配这些子属性属性。

Text {
  //点表示法
  font.pixelSize: 12
 font.bold : true }   Text {
//组表示法
font { pixelSize: 12; bold : true } }

必要属性（Required Properties）

对象声明可以使用 required 关键字定义对象实例时必须设置的属性。，语法如下:

required property <propertyType> <propertyName>

required <propertyName>

不能为 QML 中的必需属性分配初始值，因为这会直接违背必需属性的预期用途.

附加属性和附加信号处理程序（Attached Properties and Attached Signal Handlers）

附加属性和附加信号处理程序是使对象能够用对象无法使用的额外属性或信号处理程序进行注释的机制。
特别是，它们允许对象访问与单个对象特别相关的属性或信号。
attached type（attached properties and signals）在运行时被创建并附加到指定的对象，被指定的对象可以通过以下方式访问附加属性使用语法如下：

<AttachingType>.<propertyName>

<AttachingType>.on<SignalName>

附加属性只能被所属的对象访问，而不能被这个对象的child访问.

附加属性作为属性别名暴露出去也是不允许的.

QML注释

在QML中的注释类似于C/C++,java,JavaScript,主要有两种。

// 单行注释使用双斜杠
/* 多行注释 */

注释是不被执行的，添加注释可对代码进行解释或者提高其可读性。

qml的文件结构及其对象基本属性

QML介绍

文件结构

import语句

QML对象

id属性(The id Attribute)

自定义属性(Property Attributes)

信号属性(Signal Attributes)

信号处理程序属性(Signal Handler Attributes)

方法属性(Method Attributess)

枚举属性(Enumeration Attributes)

只读属性（Read-Only Properties）

默认属性（Default Properties）

属性别名（Property Aliases）

列表属性(List Properties)

分组属性（Grouped Properties）

必要属性（Required Properties）

附加属性和附加信号处理程序（Attached Properties and Attached Signal Handlers）

QML注释

热门文章

最新文章

相关电子书