本页内容

使用样式表自定义Qt Widgets

在使用样式表时,每个控件都被视为一个由四个同心矩形组成的框:边距矩形、边框矩形、内距矩形和内容矩形。“框模型”对此进行了更详细的描述。

框模型

从概念上讲,这四个同心矩形如下所示:

用于布局设计的CSS盒模型图示

  • 边距位于边框之外。
  • 边框绘制在边距与内边距之间。
  • 内边距位于边框内部,介于边框与实际内容之间。
  • 内容是指在移除边距、边框和内边距后,原始控件或子控件所剩下的部分。

margin、border-width 和padding属性默认均设为零。在这种情况下,这四个矩形(margin 、border 、padding 和content )完全重合。

您可以使用background-image属性为控件指定背景。默认情况下,背景图像仅绘制在边框内部的区域内。可以通过background-clip属性更改这一行为。您可以使用background-repeat和background-origin来控制背景图像的重复方式和起始位置。

背景图像不会随控件大小进行缩放。若要提供随控件大小缩放的“皮肤”或背景,必须使用border-image。由于 border-image 属性提供了替代背景,因此在指定 border-image 时无需再指定 background-image。 如果同时指定了这两个属性,则 border-image 会覆盖 background-image 进行绘制。

此外,还可以使用image属性在 border-image 之上绘制图像。 指定的图像不会平铺或拉伸,当其尺寸与控件尺寸不匹配时,可通过 `image-position`属性指定其对齐方式。与 `background-image` 和 `border-image` 不同,可以在 `image` 属性中指定 SVG 文件,此时图像会根据控件尺寸自动缩放。

渲染一条规则的步骤如下:

  • 为整个渲染操作设置裁剪(border-radius)
  • 绘制背景(background-image)
  • 绘制边框(border-image、border)
  • 绘制叠加图像(image)

子控件

一个小部件被视为一组层层叠加的子控件所构成的层次结构(树)。例如,QComboBox 会先绘制下拉菜单子控件,然后绘制向下箭头子控件。因此,QComboBox 的渲染效果如下:

  • 渲染QComboBox { }规则
  • 渲染 QComboBox::drop-down { } 规则
  • 渲染 QComboBox::下拉箭头 { } 规则

子控件之间存在父子关系。以QComboBox 为例,下拉箭头的父控件是下拉列表,而下拉列表的父控件则是该小部件本身。子控件通过subcontrol-position和subcontrol-origin属性在父控件内进行定位。

定位完成后,可使用盒模型为子控件设置样式。

注意:对于 QComboBox 和QScrollBar 等复杂控件,如果自定义了一个属性或子控件,则必须同时自定义所有其他属性或子控件。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.