插入 UI 控件

Components 中提供了预设的UI控件 > Qt Quick Controls >Controls 中提供。

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

• 按钮控件
• 指示器
• 选择器
• 标签栏
• 工具栏
• UI 控件汇总

您可以在“Properties ”视图中为组件实例的属性指定值。有些属性适用于所有组件，有些则仅适用于特定类型的控件，还有些属性仅对特定控件可用。以下各节将介绍预设的 UI 控件及其属性。

通用控件属性

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

“Enable ”复选框用于指示该控件是否已启用。

“Focus policy ”字段的值决定了该控件是否接受通过Tab键、单击以及鼠标滚轮获得焦点。

选中“Hover ”和“Wheel ”选项，可使控件接受鼠标事件。悬停值将传播至所有子组件，除非已为这些子组件显式设置了该值。

Spacing 对于具有多个或重复构建块的控件，此功能非常有用。例如，某些样式使用间距来确定复选框中的文本与指示器之间的距离。控件不会强制执行间距设置，因此每个样式可能对其有不同的解释，有些甚至可能完全忽略它。

按钮控件

Qt Quick 控件提供了一系列适用于特定使用场景的按钮类控件。以下各节包含针对如何选择最适合特定使用场景的按钮的指南，并讨论了在“Properties ”视图中可为按钮属性设置的值。

包含文本的按钮的建议：

• 标签应简短扼要。
• 除非 UI 指南另有规定，否则请使用默认字体。
• 如果文本需要本地化，请考虑较长的文本会对布局产生何种影响。

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

所有按钮控件共有的属性在以下内容中进行了说明：

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

按钮

您可以创建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 ”，以突出显示该委托。

对于切换后立即生效的二进制操作，请使用开关。例如，使用开关来打开或关闭 Wi-Fi。

圆形按钮

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

除了常见的按钮属性外，圆形按钮还具有Radius 属性，该属性用于指定按钮的半径。

若要创建一个四角略微圆润的近似方形按钮，请使用较小的数值，例如 3。

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

显示文本和图标

按钮可以包含文本、图标或两者兼有。在“Button Content ”部分的“Text ”字段中指定按钮文本。通过“Display ”字段的值，可以决定仅显示文本还是仅显示图标；当两者同时显示时，还可以决定文本是置于图标旁边还是下方。

可选中按钮

当用户在按钮处于活动焦点状态时选中该按钮或按空格键，可选按钮会在选中（开启）和未选中（关闭）状态之间切换。选择“Checkable ”可使按钮变为可选状态。若要使按钮处于选中状态，请选择“Checked ”。

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

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

如果按钮不属于同一个父组件，则选中或取消选中某个按钮不会影响该组中的其他按钮。

按钮信号

当按钮被用户激活时，会发出clicked() 信号。连接此信号以执行按钮的操作。按钮还提供以下附加信号：canceled() 、doubleClicked() 、pressed() 、released() 以及用于长按操作的pressAndHold() 。

选择“Auto-repeat ”可使按钮在长按期间重复发送pressed() 、released() 和clicked() 信号。pressAndHold() 信号将不会被触发。

指示器

Qt Quick 控件提供了一系列指示器类控件，例如忙碌指示器、页面指示器和进度条，以满足特定用例的需求。以下各节提供了选择最适合特定用例的指示器的指南。

忙碌指示器

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

忙碌指示器类似于状态未定的进度条。两者均可用于指示后台活动。主要区别在于视觉表现，且进度条还能显示具体的进度数值（当进度可确定时）。由于视觉上的差异，忙碌指示器和状态未定的进度条在用户界面中的适用位置各不相同。

选择“Running ”以显示忙碌指示器。

选择“Live ”以提供进度的实时更新。

忙碌指示器的常见位置包括：

• Tool Bar 的角落。
• 作为Page 的叠加层。
• 位于Item Delegate 的侧边。

页面指示器

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

选中“Interactive ”选项，可使页面指示器对按压操作作出响应，并据此自动更改“Current ”字段的值。

页码指示器通常设计得比较小，以避免分散用户对 UI 实际内容的注意力。因此，它们可能难以点击，用户也可能难以识别其交互性。基于这些原因，页码指示器最好用于补充主要导航方式（如Swipe View ），而非取代它们。

进度条

Progress Bar 用于显示操作的进度。您可以在“Value ”字段中指定初始值，但该值应定期更新。请在“From ”和“To ”字段中指定范围，这两个字段均可包含任意值。

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

“不确定”模式与“忙碌指示器”类似，二者均可用于指示后台活动。由于视觉上的差异，不确定进度条和忙碌指示器在用户界面中的适用位置不同。

不确定进度条的典型位置包括：

• Tool Bar 的底部。
• Page 内容中的内联位置。
• 位于Item Delegate 中，用于显示特定项目的进度。

选择器

Qt Quick 控件提供了一组类似选择器的控件，例如滑块、旋钮、旋转框、下拉列表和拨盘，以满足特定用例的需求。以下各节提供了针对不同用例选择最合适选择器的指南。

滑块和旋钮

您可以创建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 属性的角色。若要使用与“text”角色对应的模型项角色，请在该字段中输入valueRole 。

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

扁平化下拉列表框在未被交互时不会绘制背景，因此能与用户界面融为一体。例如，可在工具栏上使用扁平化下拉列表框，以匹配工具按钮的扁平化外观。要创建扁平化下拉列表框，请选择“Flat ”。

关于下拉列表的建议：

• 如果选项数量非常多，请考虑应用筛选功能。
• 如果选项数量较少，请考虑使用单选按钮，以便用户能够同时看到所有选项。
• 设置默认值，该值应为预计被选择频率最高的选项。

旋转按钮

Tumbler 允许用户从一个可旋转的选项轮中选择一个选项。当选项数量过多（例如使用单选按钮）又不足以需要使用可编辑的旋转框时，该控件非常实用。其便利之处在于无需使用键盘，且当选项数量较多时，列表会在两端循环显示。

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

要启用循环显示，请选择“Wrap ”。

标签栏

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

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

您可以在“Content size ”字段中指定内容宽度（W ）和高度（H ）。

如果按钮的总宽度超过标签栏的可用宽度，标签栏将自动变为可滑动状态。

工具栏

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

Tool Button 与“按钮”几乎完全相同，但其图形外观使其更适合插入到工具栏中。

工具栏本身不提供布局，需要您手动定位其内容，例如通过创建RowLayout 。如果工具栏仅包含一个项目，它会自动调整大小以适应该项目的隐含尺寸。这使得工具栏特别适合与布局配合使用。 不过，您可以在Pane 部分的Content size 字段中指定内容的宽度（W ）和高度（H ）。

Tool Separator 用于通过分隔线在视觉上区分工具栏上的项目组。通过设置Orientation 字段的值，可在水平或垂直工具栏中使用该功能。

样式控制

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

有关定义自定义样式并在设计模式中使用它的示例，请参阅《Qt Quick 控件——扁平化样式》。

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

UI 控件概览

下表列出了预设的 UI 控件及其开发文档链接。这些控件可在Components > Qt Quick Controls中提供。MCU 支持列标明了哪些控件在 MCU 上受支持。