在Qt桌面应用开发中，QCheckBox是最常用的控件之一。然而，许多开发者在使用自定义样式表美化界面时，常常遭遇一个令人困惑的问题：设置setStyleSheet后，勾选标记（checkmark）突然不显示了。界面看起来光鲜亮丽，但复选框失去了“选中”视觉反馈，用户体验大打折扣。这究竟是怎么回事？又该如何解决？本文将为你详细剖析。

问题重现：一个常见的场景

假设你在QSS文件中这样编写样式：

ui->checkBox->setStyleSheet(
    "QCheckBox {"
    "   spacing: 5px;"
    "}"
    "QCheckBox::indicator {"
    "   width: 20px;"
    "   height: 20px;"
    "   border: 1px solid #999;"
    "   border-radius: 3px;"
    "}"
);

运行后，复选框变成了一个带圆角的灰色方框，但无论怎么点击，方框内始终没有出现那个熟悉的打勾符号。更糟糕的是，当调用isChecked()时返回true，视觉上却毫无变化。

根源剖析：样式表的“覆盖”机制

问题的核心在于Qt样式表对子控件的绘制规则。QCheckBox的指示器（indicator）实际上是一个复合子控件，它由背景和前景（即勾选标记）两部分组成。当你在QSS中仅定义了QCheckBox::indicator的尺寸和边框样式时，Qt会认为你已经完全接管了该子控件的绘制，此时系统将不再自动绘制默认的勾选标记图案。

关键点在于：原生样式会提供checked/unchecked/disabled等多种状态的图形，而自定义样式表默认只使用“无状态”背景。除非你明确指定checked状态下的前景绘制规则，否则勾选标记永远不会出现。

解决方案：显式定义状态样式

要解决此问题，只需在样式表中明确声明QCheckBox::indicator:checked的样式。以下是标准做法：

ui->checkBox->setStyleSheet(
    "QCheckBox {"
    "   spacing: 5px;"
    "}"
    "QCheckBox::indicator {"
    "   width: 20px;"
    "   height: 20px;"
    "   border: 1px solid #999;"
    "   border-radius: 3px;"
    "   background: white;"
    "}"
    "QCheckBox::indicator:checked {"
    "   background: #4CAF50;"  // 选中时改变背景色
    "   image: url(:/icons/checkmark.png);"  // 使用自定义图标
    "}"
);

关键修改在于： 1. 为:checked伪状态专门设置了background和image属性。 2. 使用image指定一个勾选标记图片（PNG格式，建议16x16或20x20像素）。

如果你希望完全保持原生字体风格，也可用Unicode字符替代，但需要借助font和qproperty-icon等技巧。更简单的做法是使用Qt内置资源：直接调用系统主题的勾选标记。

进阶技巧：巧用CSS字体符号

如果你不想依赖外部图片，也可以利用字体图标。例如使用Font Awesome字体库，或直接在Unicode中插入勾选符号：

"QCheckBox::indicator:checked {"
"   color: #2e7d32;"
"   font-size: 16px;"
"   font-weight: bold;"
"   qproperty-text: \"\\u2713\";"  // 这是Unicode勾号
"}"

注意：qproperty-text是Qt扩展属性，并非标准CSS，但在Qt中是生效的。更推荐使用image或background-image结合图形资源。

常见误解与最佳实践

误解一：设置indicator背景色后，系统会自动在背景上画勾选标记。
事实：Qt不会帮你自动补画，对自定义样式表来说，你的indicator就是一块空画板。

误解二：只需要设置:disabled状态，:checked会继承。
事实：子控件的状态是独立的，必须逐一定义所有需要呈现的伪状态（:checked、:unchecked、:hover、:pressed、:disabled等）。

最佳实践： - 优先使用Qt样式表参考手册中推荐的image属性而非background-image。 - 为indicator设置width和height后，也务必为:checked和:unchecked分别定义背景。 - 如果你希望保留原生样式的勾选标记，可以考虑不自定义indicator，仅修改QCheckBox全局属性（如字体、间距）。 - 调试时可在样式表中临时添加outline: 1px solid red;来观察子控件边界。

结语

QCheckBox勾选标记不显示的问题，本质上是开发者与Qt样式表引擎之间的一次“沟通失灵”。只需记住一条黄金法则——自定义子控件时，必须明确定义所有需要呈现的状态样式——就能轻松避开这个陷阱。当你的复选框再次在选中时亮起绿色对勾、未选中时保持清爽空白，用户界面的专业感便会瞬间提升。希望本文能帮助你在Qt样式设计的道路上少走弯路。