Qt QML 组件

您不仅可以访问用于设计应用程序用户界面的 AppStudio QML 组件，还可以访问所有 The Qt Company 自己的 QML 组件。 本主题将为您介绍常用组件。 有关 Qt QML 类型的完整列表，请参阅 Qt 文档。

以下内容是一些最常用的 QML 类型：

• 定位器
• 锚点
• 布局
• 转发器
• 多个省/自治区/直辖市
• 连接

警告：

从 Qt 5.13.1 迁移至 Qt 5.15.2 时，可在 AppStudio 应用程序和示例的用户界面 (UI) 组件的显示中观察到差异。 一些差异包括位置、大小、布局、颜色、裁剪、换行和字体。 查看应用程序所有 UI 组件的显示。 在某些情况下，您可能需要更改组件的嵌套；但是其他情况下，可能需要定义更多或更少的属性。 因为在 QML 中定义 UI 的方式具有很大的灵活性，所以，不存在固定的规则。

在 5.15.2 版本中，诸如 bool、string 和 int 等 Qt 属性类型十分严格，不再支持空值或未定义的值。 如果您的应用程序使用这些类型，则必须考虑如何支持空值或未定义的值。 或者，您可以使用 var 属性类型，该类型允许空值和未定义的值，但也允许所有其他可能的值。

定位器

定位器属于容器项目，用于管理用户界面中项目的位置。 定位器类型包括 row、column、grid 和 flow。 如果基于上述任一项来组织项目，则可以在常规布局中对其进行排列，此常规布局非常适合可调整大小的用户界面。 例如，如果在格网中组织项目并纵向查看应用程序，则可以看到 2 x 5 矩阵项目，但是切换到横向后，系统将自动重新排列您的项目格网以最佳拟合屏幕，由此提供 3 x 4 矩阵项目。

有关定位器的详细信息，请参阅 Qt 文档。

锚点

可以认为每个项目具有七个锚点，可相对于这些锚点定位其他项目。 这些点是指顶部、底部、左侧、右侧、水平中心、垂直中心和基线（项目中的文本所在的线）。 这适用于相对于彼此定位项目，从而创建动态用户界面。 即使项目的尺寸或位置发生变化，锚点保持不变。 还可以定义锚点边距，从而指定应在项目的锚点外留出多大空间。

有关锚点的详细信息，请参阅 Qt 文档。

布局

要使用 Qt 快速布局，您必须在 QML 文件中引用其他模块，例如：

import QtQuick.Layouts 1.15

三个布局：RowLayout、ColumnLayout 和 GridLayout。 与行、列和格网相比，使用布局可实现对项目定位的更精细控制。 这包括可以指定布局中每个项目的对齐方式。 GridLayout 还可以设置单独的列和行间距、使项目跨多行和多列，以及为项目指定单个格网像元。 还可使用布局来设置首选最大及最小宽度和长度，以及填充各个项目的宽度和高度。 这在针对动态显示或多个显示进行设计时尤其有用。 还可以对布局进行镜像，将从左到右布局更改为从右到左布局。

转发器

转发器对象可使用模型中的数据从模板创建项目，以与定位器结合使用。 展示多个项目的有效方式是结合使用转发器和定位器。 模型可以为以下其中一项：

• 指示转发器要创建的委托次数的数值
• 自由形式列表数据源 - ListModel
• 字符串列表
• 对象列表

委托可提供一个模板，用于定义转发器实例化的各个项目。 转发器委托可以访问其在转发器内的索引以及与委托有关的模型数据。

有关转发器的详细信息，请参阅 Qt 文档。

多个省/自治区/直辖市

状态可用于在应用程序中显示不同的视图或屏幕。借助状态，您可以根据属性值显示或隐藏元素、更改锚点或更改父对象。 可以基于状态来开始、停止或暂停动画或执行脚本。 所有基于项目的组件都具有状态属性和默认状态。 默认状态为空字符串 ("") 并且包含所有初始属性值。 将状态属性设置为空字符串将加载默认状态。

有关状态的详细信息，请参阅 Qt 文档。

连接

在 Qt 5.15 中，有一种新的连接语法。 之前用于创建 <信号> 处理程序的方法已经弃用，现在应遵循函数语法。 当您使用之前的连接语法运行应用程序时，将收到以下警告消息。

qrc:/qml/main.qml:277:5: QML Connections: Implicitly defined onFoo properties in Connections are deprecated. Use this syntax instead: function onFoo (<arguments>) { ... }

以下示例显示了在 Qt 5.13 及较早版本中定义连接的常用方法：

Connections { 
     target: mouseArea 
     onPositionChanged: { 
         console.log( "onPositionChanged: ", mouse.x, mouse.y ); 
     } 
     onPressedChanged: { 
         console.log( "onPressedChanged: ", mouseArea.pressed ); 
     } 
}

以下示例显示了在 Qt 5.15 及更高版本中定义连接的方法：

Connections { 
     target: mouseArea 
     function onPositionChanged(mouse) { 
         console.log( "onPositionChanged: ", mouse.x, mouse.y ); 
     } 
     function onPressedChanged() { 
         console.log( "onPressedChanged: ", mouseArea.pressed ); 
     } 
}

既已使用函数语法，就必须确保显式列出所有信号参数。 如果忽略了任何参数，则将无法按名称使用信号参数，这可能导致您的代码中出现未定义的引用。 例如，您必须使用 function onPositionChanged(mouse) 而非 onPositionChanged。

在列出信号参数时，建议使用信号参数的正式名称作为函数参数名，按照正确的顺序列出所有参数。 例如，使用 function onPositionChanged(mouse) 而非 function onPositionChanged(m)。

如果信号用于属性更改，则必须显式命名对象以访问属性。 例如，您必须使用 mouseArea.pressed 而非 pressed。

有关连接的详细信息，请参阅 Qt 文档。