插入用户界面控件

预设用户界面控件可在Components > >。 Qt Quick Controls>Controls 。

以下类型的控件可供用户交互使用：

• 按钮控件
• 指示器
• 选择器
• 标签栏
• 工具栏
• 用户界面控件概述

您可以在Properties 视图中为组件实例的属性指定值。有些属性是所有组件共有的，有些则是特定类型控件共有的。有些属性只适用于特定控件。下文将介绍预设的 UI 控件及其属性。

一般控件属性

您可以在Properties 视图中设置控件属性。

Enable 复选框表示控件是否启用。

Focus policy 字段的值决定控件是否通过制表、单击和使用鼠标滚轮接受焦点。

选择Hover 和Wheel 可使控件接受鼠标事件。悬停值会传播到所有子组件，除非已为它们明确设置了悬停值。

Spacing 对于具有多个或重复构建模块的控件来说，"滚轮事件 "非常有用。例如，某些样式使用间距来确定复选框的文本和指示符之间的距离。间距不是由控件强制执行的，因此每种样式可能会有不同的解释，有些样式可能会完全忽略间距。

按钮控件

Qt Quick Controls 按钮控件是一种针对特定使用情况的按钮式控件。下面几节将介绍如何选择最适合使用情况的按钮，并讨论可以在Properties 视图中为按钮属性设置的值。

对包含文本的按钮的建议：

• 标签应简明扼要。
• 使用默认字体，除非用户界面指南另有规定。
• 如果文本是本地化的，请考虑较长文本对布局的影响。

有关设置文本属性的更多信息，请参阅字符属性和填充。

所有按钮控件共享的属性在以下章节中描述：

• 显示文本和图标
• 可选中按钮
• 按钮信号

按钮

您可以创建Components > 的实例 Qt Quick Controls>Controls >Button ：

按钮可由用户按下或点击。通常，按钮用于执行操作或回答问题。例如，确定、应用、取消、关闭、是、 否和帮助。

按钮文本应该是描述操作的动词，或者是与将要打开的弹出窗口标题相匹配的名词。

不要使用按钮来设置状态，因为开关更适合设置状态。

高亮按钮

在Button 部分选择Highlight ，以引起用户对按钮的注意。突出显示按钮不会影响键盘交互。

下图显示了高亮按钮的示例：

扁平按钮

扁平按钮通常不会绘制背景，除非按下或选中该按钮。要创建平面按钮，请在Button 部分选择Flat 。

下图显示了扁平按钮的示例：

延迟按钮

Delay Button 控制器在触发操作前有一个延时。这种延迟可防止意外按下。

在触摸用户界面和必须小心触发的操作中使用延迟按钮。

您可以在Delay 字段中以毫秒为单位设置延迟时间。

复选框

您可以创建Components > 的实例。 Qt Quick Controls>Controls >Check Box ：

复选框是一个可以打开（选中）或关闭（不选中）的选项按钮。复选框通常用于从一组选项中选择一个或多个选项。对于较大的选项集，如列表中的选项，可考虑创建Check Delegate 控件的实例。

委托可以高亮显示，以引起用户对它的注意。高亮显示对键盘交互没有影响。选择Item Delegate 部分中的Highlight 来突出显示委托。

使用复选框建立多选选项列表，在列表中可以选择任意数量的选项，包括不选，但这些选项并不相互排斥。

在 "是/否 "选项中使用单个复选框，例如用户必须接受对话框中的服务协议条款。对于单个 "是"/"否 "选项，也可以使用开关。如果用户在选项之间进行选择，则使用复选框。如果用户在要采取的操作之间进行选择，则建议使用开关。

Button Content 部分中Checked 的值决定复选框的状态。不过，除了选中和未选中状态外，复选框还有第三种状态：部分选中。

在Check Box 部分选择Tri-state ，当用户使用触摸、鼠标或键盘切换复选框时，复选框可在选中、部分选中和未选中状态之间循环。

当选项可以分组时，可以使用部分选中复选框来代表整个组。在Check state 字段中选择PartiallyChecked ，表示用户选择了组中的某些子组件，但不是全部。

可选中的选项通常以垂直方式列出。

复选框标签应该是复选标记为 "真"，无复选标记为 "假 "的声明。因此，复选框标签不应包含否定语句。

单选按钮

Radio Button 是一种可以打开（选中）或关闭（不选中）的选项按钮。单选按钮通常用于从一组选项中选择一个选项。选择一个选项会自动清除前一个选项。

如果只有两个相互排斥的选项，可将它们合并为一个复选框或开关。

Radio Delegate 单选按钮与单选按钮类似，但它通常用于视图中。

在Radio Delegate 部分选择Highlight ，高亮显示委托。

建议使用单选按钮：

• 将标签文本限制为一行。
• 确保选中合理的默认选项。
• 垂直列出单选按钮选项。
• 保持列表简短。
• 为避免混淆，不要将两组单选按钮放在一起。

切换

您可以创建Components > 的实例。 Qt Quick Controls>Controls >Switch ：

开关是一个选项按钮，可以拖动或切换开（选中）或关（不选中）。开关通常用于在开 或关两种状态之间进行选择。对于较大的选项集，例如列表中的选项，可以考虑使用Switch Delegate 代替。

在Item Delegate 部分选择Highlight 以突出显示代表。

使用开关进行二进制操作，在切换开关后立即生效。例如，使用开关打开或关闭 WiFi。

圆形按钮

Round Button 是一个可点击的控件，用于启动一个操作，或打开或关闭一个弹出窗口。带有方形图像图标或单字字体图标的圆形按钮是圆形的。圆形按钮占用的空间比普通按钮小，也可用作浮动操作按钮。

除了常见的Button属性外，圆形按钮还具有Radius 属性，该属性表示按钮的半径。

若要创建一个边角略呈圆形的相对方形按钮，请使用一个较小的值，如 3。

要创建一个完全圆形的按钮，请使用一个等于按钮宽度或高度一半的值，并使按钮的宽度和高度相同。

显示文本和图标

按钮可以包含文本、图标或两者。在Button Content 部分的Text 字段中指定按钮文本。Display 字段的值决定了只显示文本还是图标，或者当两者都可见时，文本是放在图标旁边还是下面。

可选中按钮

当用户选择可复选按钮或空格键时，可复选按钮会在 "选中"（打开）和 "不选中"（关闭）之间切换。选择Checkable 可使按钮变为可选中。要选中按钮，请选择Checked 。

属于同一父组件的按钮可以互斥。用户可以选择一个按钮对其进行选中，之前的选择将被清除。用户不能通过单击当前选中的按钮来取消选中。相反，他们必须选择组中的另一个按钮，为该组设置新的选中按钮。

单选按钮和选项卡按钮默认是互斥的。要使其他类型的按钮互斥，请选择Exclusive 。

如果按钮不属于同一父级，选中和取消选中按钮不会影响组中的其他按钮。

按钮信号

用户激活按钮时，按钮会发出clicked() 信号。连接该信号可执行按钮操作。按钮还提供以下额外信号：canceled(),doubleClicked(),pressed(),released(), 和pressAndHold() 用于长按。

选择Auto-repeat 可在按住按钮的同时重复发送pressed() 、released() 和clicked() 信号。pressAndHold() 信号将不会发出。

指示器

Qt Quick Controls 针对特定的使用情况，ASP.NET 提供了一系列类似指示灯的控件，如忙指示灯、页面指示灯和进度条。以下各节包含选择最适合用例的指示器的指南。

忙指示器

Busy Indicator 表示操作正在进行中，用户界面必须等待操作完成。

繁忙指示器类似于不确定的进度条。两者都可以用来指示后台活动。两者的主要区别在于视觉上的不同，而且进度条也可以显示具体的进度（在可以确定的情况下）。由于视觉上的不同，繁忙指示器和不确定进度条在用户界面中的位置也不同。

选择Running ，使繁忙指示器可见。

选择Live 可提供实时进度更新。

繁忙指示器的典型位置有

• 在Tool Bar 的角落。
• 作为Page 顶部的覆盖层。
• Item Delegate 的侧面。

页面指示器

Page Indicator 用于显示多个页面容器中的当前活动页面。在Count 字段中指定页数。在Current 字段中选择当前页面。

选择Interactive 以确定页面指示器会对按压作出反应，并相应地自动更改Current 字段的值。

页面指示器通常很小，以免分散用户对用户界面实际内容的注意力。因此，它们可能很难被点击，而且用户可能不容易识别出它们是交互式的。因此，它们最好用来补充主要的导航方法，如Swipe View ，而不是取而代之。

进度条

Progress Bar 显示操作的进度。可以在Value 字段中指定初始值，但应定期更新。在From 和To 字段中指定范围，这两个字段都可以包含任何值。

如果无法确定下载项目的大小，或者下载进度可能因网络故障而中断，请选择Indeterminate 。

不确定模式与 "忙指示器"类似，都可用于指示后台活动。由于它们的视觉效果不同，不定进度条和繁忙指示器在用户界面中的位置也不同。

不确定进度条的典型位置有

• Tool Bar 的底部。
• 在Page 内容中内联。
• 在Item Delegate 中显示特定项目的进度。

选择器

Qt Quick Controls 为特定的使用情况提供了一组类似选择器的控件，如滑块、转盘、旋转框、组合框和滚轮。以下各节包含了选择最适合用例的选择器的指南。

滑块和拨盘

您可以创建Components > 的实例。 Qt Quick Controls>Controls >Slider ：

滑块用于通过沿轨道滑动手柄来选择一个值，而Range Slider 则用于通过沿轨道滑动每个手柄来选择由两个值指定的范围。

Dial 滑块类似于音响或工业设备上的传统拨盘旋钮。它允许用户在一个范围内指定一个值。

您可以创建Components > 的实例。 Qt Quick Controls>Controls >Dial ：

在From 和To 字段中，设置滑块或刻度盘的范围。在Value 字段中设置滑块手柄或刻度盘的值。对于范围滑块，在Value 1 和Value 2 字段中设置第一个和第二个手柄的初始位置。选择Live 以提供值属性的实时更新。

在Snap mode 字段中，设置滑块手柄或刻度盘如何与Step size 字段的值相关。默认情况下，它们不会与步长大小咬合，但您可以设置它们在拖动时或释放后与步长大小咬合。

您可以在Orientation 字段中将滑块方向设置为水平或垂直。

修改Drag threshold ，以确定触发触摸拖动事件的阈值。

有关详细信息，请观看以下视频：

刻度盘支持圆形、水平和垂直输入模式。对于需要快速输入的应用，圆形输入模式非常有用，因为点击刻度盘就会直接移动到该位置。对于需要精确输入的应用，建议使用水平和垂直输入模式，因为这两种模式允许相对于点击刻度盘的位置进行微调。这些模式也更适用于数值大幅跳动可能不安全的刻度盘，如控制音频音量的刻度盘。在Input mode 字段中设置输入模式。

旋转框

您可以创建Components > 的实例。 Qt Quick Controls>Controls >Spin Box ：

旋转框可让用户通过单击向上或向下指示按钮，或按键盘上的向上或向下键来选择整数值。选择Editable ，用户就可以在输入框中输入文本值。

其他自旋框属性与Dial 类似。

组合框

Combo Box 是按钮和弹出列表的组合。它提供了一种向用户展示选项列表的方式，占用的屏幕空间最小。

组合框用于从静态多行下拉列表中选择一个值。用户不能添加新值，而且只能选择一个选项。

组合框的值由数据模型提供。数据模型通常是 JavaScript 数组、ListModel 或整数，但也支持其他类型的数据模型。

选择Editable ，即可根据模型中的可用内容自动完成组合框文本。

使用具有多个已命名角色的模型时，请在Text role 字段中指定Display text 属性的角色。要使用与文本角色相对应的模型项角色，请在字段中输入valueRole 。

Current index 字段包含组合框中显示的项的索引。当组合框为空时，默认值为-1 ，否则为0 。

除非与之交互，否则平面组合框不会绘制背景，这就使其与用户界面融为一体。例如，在工具栏上使用扁平组合框可以与工具按钮的扁平外观相匹配。要创建平面组合框，请选择Flat 。

建议使用组合框：

• 如果值的数量非常多，可以考虑应用筛选器。
• 如果值的数量较少，可以考虑使用单选按钮，这样用户可以同时看到所有选项。
• 设置默认值，默认值应是你期望最常选择的值。

滚轮

Tumbler 允许用户从一个可旋转的项目轮中选择一个选项。当选项过多而无法使用单选按钮，但选项过少而需要使用可编辑的旋转框时，它就非常有用。它的方便之处在于无需使用键盘，当项目较多时，还可以在两端绕行。

在Visible count 字段中指定可见选项的数量。在Current index 字段中选择当前选项的索引。

要启用缠绕功能，请选择Wrap 。

标签栏

Tab Bar 提供基于标签的导航模式，用户可以在不同视图或子任务之间切换。标签栏通常用作ApplicationWindow 的页眉或页脚。在Position 字段中选择工具栏位置。

通常情况下，选项卡栏包含一组静态的Tab Button 控件，这些控件被定义为其子控件。Current index Container 字段显示当前选项卡按钮的索引。当标签栏为空时，默认值为-1 ，否则为0 。

您可以在Content size 字段中指定内容宽度 (W) 和高度 (H)。

如果按钮的总宽度超过了标签栏的可用宽度，则标签栏会自动变成可闪烁的。

工具栏

Tool Bar 包含整个应用程序和上下文相关的操作和控件，如导航按钮和搜索栏。工具栏通常用作ApplicationWindow 的页眉或页脚。在Position 字段中选择工具栏位置。

Tool Button 工具栏 "与"按钮 "几乎相同，但其图形外观使其更适合插入工具栏。

工具栏本身不提供布局，但需要您对其内容进行定位，例如通过创建RowLayout 。如果工具栏只包含一个项目，它将调整大小以适应隐含项目的大小。这使得工具栏特别适合与布局一起使用。不过，您可以在Pane 部分的Content size 字段中指定内容宽度 (W) 和高度 (H)。

Tool Separator 用线分隔工具栏上的各组项目，以便在视觉上区分它们。通过设置Orientation 字段的值，它可用于水平或垂直工具栏。

样式控件

可以对预设的用户界面控件进行样式设置。2D 视图会从配置文件 (qtquickcontrols2.conf) 中读取首选样式。要更改样式，请从主工具栏的列表中选择另一种样式。这样就可以检查用户界面在使用可用样式时的外观。

有关定义自己的样式并在设计模式中使用的示例，请参阅Qt Quick Controls - 扁平样式。

有关如何自定义特定控件的更多信息，请参阅《自定义参考》。

用户界面控件概述

下表列出了预设的用户界面控件及其开发人员文档链接。它们可在Components > Qt Quick Controls.MCU 支持列表示 MCU 支持哪些控件。