Qt 鸿蒙音乐播放器左侧导航实战:QListWidget 分组头不可选靠 ItemFlags 位运算,选中态交给 QSS 伪状态,从裸列表到像 Windows 的侧边栏
Qt 鸿蒙音乐播放器左侧导航实战:QListWidget 分组头不可选靠 ItemFlags 位运算,选中态交给 QSS 伪状态,从裸列表到像 Windows 的侧边栏
左侧那条导航看似只是"一列文字",真正写起来才发现它卡在三个地方:分组头怎么变成不可点的标题、选中态怎么在窗口失焦后还留着、图标和缩进怎么在不用资源文件的前提下做出来。这篇文章用一个跑在鸿蒙真机上的音乐播放器,把"QListWidget 的项标志位运算"“QSS 伪状态的真实行为”"无 qrc 时的图标方案"这三个问题一次讲透。
仓库与版本地址:
- 开源鸿蒙 PC 社区:https://harmonypc.csdn.net/
- 新建项目申请:https://atomgit.com/OpenHarmonyPCDeveloper
- Qt 鸿蒙预编译包发行页:https://atomgit.com/openharmony-sig/qt/releases
0. 环境与实测设备
| 项 | 版本 / 型号 |
|---|---|
| DevEco Studio | 鸿蒙电脑版,build 号「待补」,API 26 |
| Qt | 5.15.17(发行版 Alpha_v10) |
| Qt SDK 路径 | /storage/Users/currentUser/Qt5.15.17_OHOS/qt5.15.17_arm64-v8a |
| OHOS SDK | API 18,NDK clang 15.0.4 |
| hvigor | 版本「待补」 |
| 编译器 | clang 15.0.4,target aarch64-unknown-linux-ohos |
| 工程 | qt-hello,CMake target entry,产物 libentry.so |
| 真实设备 | HarmonyOS PC(aarch64),型号「待补」,系统版本「待补」 |
| 相关模块 | Qt Widgets(QListWidget / QListWidgetItem)+ Qt GUI(QFont / QColor) |
这一篇只动两个文件:musicplayerwindow.cpp 的 buildLeftPane() 和 style.h 里 #navList 那一段。环境里最要紧的一条还是老规矩——moc 跑不了,所以 QListWidget 用现成类,不做子类化,导航点击的后续处理得另想辙。
1. 一列文字不是列表——这个问题是怎么找上我的
我一开始也以为,左侧导航不就是往 QListWidget 里塞一堆字符串嘛。addItem("发现音乐")、addItem("播客")、addItem("我喜欢的音乐"),几行代码的事。
第一版确实是这么写的。结果跑起来,三个地方不对。
第一,分组标题"发现"“我的音乐”“创建的歌单"和普通导航项长得一模一样,都是能点、能选的一行字。用户点一下"我的音乐”,那行就高亮了,看起来像选中了一个功能,其实它只是个分组名。这在设计上就说不通。
第二,选中态在窗口失焦后会消失。鸿蒙 PC 上切到别的应用再切回来,或者点一下搜索框,导航里原本选中的那行就变成灰色——用户会以为选中丢了。我一开始以为是 QSS 写错了,后来翻 Qt 文档才看清楚,这是 QStyle 对非激活窗口的标准处理。
第三,我想给每个导航项配个小图标,顺手去翻 Qt 的资源系统,才想起来 rcc 在这台机器上是 x86 程序,跑不了,.qrc 这条路是堵死的。
所以这个题目的边界很清楚:在不能用 rcc、不能子类化带 Q_OBJECT 的类的前提下,用 QListWidget 现成的项模型和 QSS 伪状态,做出一个分组清晰、选中态稳定、图标不依赖资源文件的 Windows 式侧边栏。
拆开是三件事:
- 分组头怎么从"可选中的项"变成"纯标题";
- 选中态在激活/非激活两种窗口状态下怎么都稳得住;
- 图标和缩进在不用图片资源的情况下怎么做。
下面是干完之后的完整记录,包括我踩的每一个坑。
2. 效果展示
按老规矩,先给效果再讲原理。

这张图里,三组标题"发现"“我的音乐”"创建的歌单"是浅灰色小字,明显和普通导航项区分开;普通项里"发现音乐"是选中态,浅灰底 + 红色文字。
这里每一行都不是装饰:
- "发现"这行之所以不可点,是因为它的
Qt::ItemFlags里被清掉了ItemIsSelectable和ItemIsEnabled两个位; - "发现音乐"的红色文字来自 QSS 的
#navList::item:selected { color: #ec4141; }; - 分组头的小字号和灰色来自
QListWidgetItem::setFont()和setForeground(),这是项自己的属性,不是 QSS; - 选中项两侧有 6px 的圆角边距,来自
#navList::item { margin: 1px 6px; border-radius: 5px; }。
另一张图是窗口失焦后的状态:





切到别的应用再回来,选中项仍然保持浅灰底 + 红字,没有变成系统默认的那种"灰色失焦态"。这靠的是 QSS 里单独写的 #navList::item:selected:!active 规则——这是这次调试里最值钱的一行,后面第 5.3 节专门讲。
这两张图都是静态框架阶段拍的,点击导航项不会真的切换右侧内容。这一篇只解决"看起来对",功能留在后续。
3. 原理:QListWidget 的项到底有几种状态
QListWidget 是 Item-Based 控件——每一行是一个 QListWidgetItem 对象,控件本身只负责排列和交互,项的文字、图标、字体、颜色、可选性都在项对象上。理解这个分工,后面就不会把"改项的属性"和"改控件的样式"搞混。
把这一篇涉及的机制列成表:
| 机制 | 作用层级 | 决定什么 | 什么时候用 |
|---|---|---|---|
QListWidgetItem::setFlags() | 项 | 这一项能不能被选中、能不能交互 | 做不可点的分组头 |
setFont() / setForeground() | 项 | 这一项的字体、颜色 | 分组头小字灰字 |
QListWidget::setCurrentRow() | 控件 | 初始选中哪一项 | 设默认选中态 |
QSS ::item:selected | 控件样式 | 选中项的外观 | 定义选中态 |
QSS ::item:selected:!active | 控件样式 | 窗口失焦时的选中态 | 防止失焦后选中态消失 |
setEditTriggers(NoEditTriggers) | 控件 | 双击能不能编辑项文字 | 防止用户改坏导航文字 |
这里有一个判断值得单独钉死:项的属性归项,控件的外观归 QSS,两者不要混。 分组头的灰色小字是用 setFont() / setForeground() 设在项上的,而选中态的红字是用 QSS 设在控件的 ::item 子控件上的。为什么这么分?因为分组头永远是灰的,不随状态变,用项属性最直接;而选中态是瞬时状态,QSS 的伪状态机制天生适合处理它。
事件流大概是这样:
用户点击某一行
→ QListWidget 检查该行的 ItemFlags
→ 没有 ItemIsEnabled/ItemIsSelectable:忽略点击(分组头)
→ 有:设置该行为 current
→ 触发 QSS 的 :selected 伪状态重算
→ 窗口激活:用 :selected 规则
→ 窗口失焦:用 :selected:!active 规则
注意这一步:QSS 伪状态是重算的,不是一次画上去的。 每次窗口激活状态变化、每次选中项变化,Qt 都会重新匹配一遍样式规则。所以 :selected:!active 这种组合伪状态能实时生效。这也解释了为什么这条规则必须单独写——不写的话,失焦时 Qt 会退回默认样式,选中态就没了。
记住这个模型:分组头靠 ItemFlags 挡住交互,选中态靠 QSS 伪状态渲染,两层各管各的。 后面第 5 节的所有代码都是围绕这两层展开的。
4. 工程怎么搭
这一篇涉及的改动集中在两个文件。先看相关目录和职责:
entry/src/main/cpp/
├── musicplayerwindow.h 声明 buildLeftPane()
├── musicplayerwindow.cpp
│ └── buildLeftPane() ← 这一篇的主战场:造列表、造项
├── style.h
│ └── #navList / #navList::item ... ← 这一篇的另一战场:选中态样式
└── main.cpp 不动
这次整理最关键的变化,是把"一堆 addItem"变成"两个 lambda 工厂"。这带来三条边界:
- 分组头和普通项走不同构造函数:
addSection()关交互、设小字灰字;addItem()保留可选、不可编辑; - 新增导航项只写一行:
addItem(QStringLiteral("新项")),不用重复设置属性; - 样式和逻辑分离:项的属性在 C++ 里设,选中态在 QSS 里定,改配色不动 C++。
最小实现(节选):
// entry/src/main/cpp/musicplayerwindow.cpp - buildLeftPane()(节选)
auto addSection = [this](const QString &text) {
auto *it = new QListWidgetItem(text, m_navList);
it->setFlags(it->flags() & ~Qt::ItemIsSelectable & ~Qt::ItemIsEnabled);
QFont f = it->font();
f.setPointSize(9);
f.setBold(true);
it->setFont(f);
it->setForeground(QColor(QStringLiteral("#a0a0a4")));
};
auto addItem = [this](const QString &text) {
auto *it = new QListWidgetItem(text, m_navList);
it->setFlags(it->flags() & ~Qt::ItemIsEditable);
};

对应的控件初始化:
// entry/src/main/cpp/musicplayerwindow.cpp - buildLeftPane()(节选)
m_navList = new QListWidget(m_left);
m_navList->setObjectName(QStringLiteral("navList"));
m_navList->setFrameShape(QFrame::NoFrame);
m_navList->setSelectionMode(QAbstractItemView::SingleSelection);
m_navList->setEditTriggers(QAbstractItemView::NoEditTriggers);
m_navList->setHorizontalScrollBarPolicy(Qt::ScrollBarAlwaysOff);

注意 setObjectName("navList") 这一行——它是 C++ 和 QSS 之间的契约。没有它,style.h 里所有 #navList::item 规则都找不到目标。这个 objectName 契约会在第 5 篇系统展开。
CMake 和 ArkTS 侧一行都不用改,因为这一篇没有引入新模块——QListWidget 在 Qt Widgets 里,QFont / QColor 在 Qt GUI 里,两个都已经链接了。
5. 把代码讲透
5.1 分组头不可选:ItemFlags 的位运算
分组头要做成"纯标题",关键是把它从可交互项里摘出去。QListWidgetItem::flags() 返回一个 Qt::ItemFlags 位掩码,默认包含 ItemIsSelectable、ItemIsEnabled、ItemIsUserCheckable 等。我们要清掉其中两个位。
// entry/src/main/cpp/musicplayerwindow.cpp - buildLeftPane()(节选)
auto addSection = [this](const QString &text) {
auto *it = new QListWidgetItem(text, m_navList);
// 清掉可选中 + 可交互两个位
it->setFlags(it->flags() & ~Qt::ItemIsSelectable & ~Qt::ItemIsEnabled);
QFont f = it->font();
f.setPointSize(9);
f.setBold(true);
it->setFont(f);
it->setForeground(QColor(QStringLiteral("#a0a0a4")));
};

三个细节值得单独说:
第一,& ~ 是清除位掩码的标准写法。 ~Qt::ItemIsSelectable 把这个位取反成 0,和原 flags 做 & 就把这一位清掉,其他位保留。不要写成 it->setFlags(Qt::NoItemFlags)——那会把所有位都清掉,包括一些 Qt 内部依赖的标志,行为可能异常。
第二,ItemIsEnabled 必须一起清掉。 只清 ItemIsSelectable 的话,项虽然不能被选中,但仍然能被"激活"(鼠标悬停有反应、键盘能聚焦到它),用户点上去还是会有反馈。两个一起清,它才是真正的"装饰性标题"。
第三,分组头的字体和颜色是设在项上的。 setFont() 和 setForeground() 是 QListWidgetItem 的成员方法,只影响这一个项。这比用 QSS 去匹配"第几个项是分组头"可靠得多——QSS 没有"按文本匹配项"的选择器,而项属性是精确的。
反直觉陷阱:不要试图用 QListWidget 的 setCurrentRow(-1) 让分组头不被选中。 那只能取消当前选中项,不能阻止用户下一次点击选中分组头。治本的办法只有改 ItemFlags。
5.2 项的字体与前景色:QListWidgetItem 自带属性
这一节讲分组头外观的实现。很多人第一反应是"写 QSS",但这里用项属性反而更对。
QFont f = it->font(); // 取项当前字体
f.setPointSize(9); // 改字号
f.setBold(true); // 加粗
it->setFont(f); // 设回去
it->setForeground(QColor(QStringLiteral("#a0a0a4"))); // 灰色
三个细节:
第一,QFont 要先取再改,不要凭空 QFont f; 然后 set。 凭空构造的字体是系统默认字体,可能丢掉控件已经设好的字体族。先 it->font() 取到当前值,改完再 set 回去,才能只改需要改的属性。
第二,setForeground() 接受的是 QBrush,传 QColor 能隐式转换。 这里传 QColor(QStringLiteral("#a0a0a4")) 是合法的,Qt 会把它包装成 QBrush。如果想设更丰富的样式(比如渐变),可以显式构造 QBrush。
第三,普通项不设这些属性,是为了继承系统默认外观。 选中态的颜色交给 QSS 管,普通态用系统默认。如果普通项也用 setForeground() 设死颜色,QSS 的 :selected 规则里写的 color: #ec4141 可能覆盖不了项自带的颜色——项属性优先级比 QSS 高。
反直觉陷阱:在 Item-Based 控件里,项属性往往比 QSS 优先级更高。 想让 QSS 控制颜色,就别在项上设颜色;想在项上设死,就别指望 QSS 能改。混用会得到"样式表好像没生效"的错觉。
5.3 默认选中与失焦:QSS 伪状态的真相
这是这次调试里最值钱的一节。先看 C++ 侧的默认选中:
// entry/src/main/cpp/musicplayerwindow.cpp - buildLeftPane()(节选)
m_navList->setCurrentRow(1); // 默认选中「发现音乐」
setCurrentRow(1) 按索引选中第 2 行(分组头"发现"是第 0 行,"发现音乐"是第 1 行)。框架刚显示时,"发现音乐"就是选中的。
再看 QSS 侧的两条规则:
/* style.h - #navList::item 选中态(节选) */
#navList::item:selected {
background: #e6e6e8;
color: #ec4141;
font-weight: bold;
}
#navList::item:selected:!active {
background: #ebebed;
color: #ec4141;
}
三个细节值得单独说:
第一,:selected:!active 是"窗口失焦时的选中态"。 !active 是 :active 的取反伪状态,表示"所在窗口不是激活窗口"。鸿蒙 PC 上切到别的应用,导航窗口失焦,Qt 会切换到这条规则。不写它的话,失焦时 Qt 用默认的灰色样式,红字就丢了。
第二,两条规则的文字颜色都是 #ec4141,但背景色略有不同(#e6e6e8 vs #ebebed)。这是刻意的:失焦时背景稍微淡一点,给用户一个"窗口不活跃"的微妙暗示,但不至于让选中态消失。这是从系统原生应用学来的细节。
第三,font-weight: bold 只在 :selected 里写了,没在 :!active 里写。 这意味着失焦后选中项不再是粗体。这是个可接受的细节——失焦时视觉权重降低是合理的。如果你希望失焦也保留粗体,就在 :!active 规则里也加上。
反直觉陷阱:不要以为 :selected 一条规则就够了。 窗口激活状态变化会触发伪状态重算,失焦时 :active 不再匹配,:selected 那条规则里的 background 和 color 就都不生效了。必须显式写 :selected:!active 兜住。这个坑在桌面 Qt 上不明显,但在鸿蒙 PC 上频繁切换窗口时特别扎眼。
5.4 图标方案:不用 .qrc 怎么办
这一版导航项是纯文字,但我认真考虑过图标方案,值得把取舍写出来。
QListWidgetItem::setIcon() 接受一个 QIcon。图标来源有三条路:
| 方案 | 做法 | 在这套环境里的可行性 |
|---|---|---|
资源文件 .qrc | QIcon(":/icons/home.png") | 不可行,rcc 是 x86 程序,跑不了 |
| 磁盘路径 | QIcon("/path/to/home.png") | 可行,但图片得随 HAP 打包,路径要处理 |
| QStyle 标准图标 | style->standardIcon(QStyle::SP_DirIcon) | 最稳,由 QPA 插件从系统主题取 |
// 可行但这一版没用的图标方案(示意)
QStyle *style = QApplication::style();
const QIcon homeIcon = style->standardIcon(QStyle::SP_DirHomeIcon);
item->setIcon(0, homeIcon);
三个细节:
第一,QStyle 标准图标在这套环境里最稳。 它不依赖任何外部文件,由 QPA 插件 libplugins_platforms_qopenharmony.so 从系统主题里取。图标风格天然和系统一致,换主题还能跟着变。上一个文件管理器系列用的是这个方案,验证过可行。
第二,这一版为什么没用图标。 导航项是"发现音乐"“播客”"视频"这类功能名,QStyle 标准图标里没有完全对应的语义图标,硬套 SP_DirIcon 反而不伦不类。纯文字 + 分组头 + 缩进,视觉上已经够清晰,就不勉强加图标了。
第三,如果以后要加自定义图标,磁盘路径方案要打包。 把 png 放进 entry/resources/,用相对路径加载,并确保 HAP 里带上这些文件。这比 .qrc 麻烦,但绕开了 rcc。
反直觉陷阱:不要为了"看起来专业"硬加图标。 图标和语义不匹配时,纯文字比错图标好。这一版的选择是刻意的,不是没想到。
5.5 控件细节:边框、编辑与滚动条
最后一节收口几个不起眼但影响观感的设置。
m_navList->setFrameShape(QFrame::NoFrame);
m_navList->setEditTriggers(QAbstractItemView::NoEditTriggers);
m_navList->setHorizontalScrollBarPolicy(Qt::ScrollBarAlwaysOff);
m_navList->setSelectionMode(QAbstractItemView::SingleSelection);
三个细节:
第一,setFrameShape(QFrame::NoFrame) 去掉默认边框。 QListWidget 默认带一个 StyledPanel 边框,和左栏的 #f5f5f7 背景放一起很突兀。左栏容器本身已经有 border-right: 1px solid #e5e5e5 的分隔线了,列表再带边框就是多余。
第二,NoEditTriggers 防止用户改坏导航文字。 QListWidget 默认支持双击编辑项文字(如果项有 ItemIsEditable 标志)。导航项是固定功能名,不该被编辑,所以控件级关掉编辑触发。项级也清了 ItemIsEditable(虽然默认就没有),双保险。
第三,关掉水平滚动条。 "工作白噪音"这种长文本在窄窗口下可能超出宽度,默认会出现水平滚动条。导航项应该被省略号截断,而不是让用户横向滚动。关掉水平滚动条后,超长文本由 QSS 的 elide 或默认裁剪处理。
反直觉陷阱:setIndentation() 是 QTreeWidget 的 API,QListWidget 没有。 想给列表项加缩进,别去找 setIndentation,直接在 QSS 的 #navList::item 里写 padding-left,或者用 QListWidgetItem::setSizeHint() 配合自定义 delegate(后者在没 moc 的环境里更麻烦,不推荐)。这一版用的是 QSS padding。
延伸一:QListWidget / QTreeWidget / QListView 怎么选
导航区用哪个控件,取决于数据有没有层级。这一版选了 QListWidget,理由值得写下来。
| 控件 | 数据模型 | 适合什么 | 这一版的选择 |
|---|---|---|---|
QListWidget | 自己管理一串 item | 扁平列表、需要分组头 | ✓ 用了,分组头靠 ItemFlags 做 |
QTreeWidget | 树形 item,自带层级和展开箭头 | 真正的父子层级(目录树、组织架构) | 没用,"创建的歌单"是平级不是父子 |
QListView | 外部 Model + View 分离 | 大数据量、数据频繁变化 | 没用,导航项就十几个,不值得上 Model |
关键判断:"发现 / 我的音乐 / 创建的歌单"看着像层级,其实不是。 分组头下面那些项是平级的,不需要展开/折叠,也没有父子关系。用 QTreeWidget 会带来箭头、缩进、层级选中传播等一堆用不上的复杂度。用 QListWidget + 不可选的分组头项,正好够用。
如果以后导航项要真正分组折叠(用户能不能把"创建的歌单"整组收起来),那就该换成 QTreeWidget——但那是另一个设计决定了,不是这一版要考虑的。
延伸二:长文本和像素密度
“工作白噪音"这类四字歌单名在 180px 的左栏下限里显示得下,但换成更长的名字(比如"我喜欢的音乐 · 2026 精选合集”)就会超出。
处理办法有三个:
- QSS 省略号:给 item 设
text-overflow: ellipsis;,超长文本显示成"我喜欢的音乐…"。这是最省事的做法,但 QSS 对::item的 text-overflow 支持在不同 QStyle 下不一致,得真机验证; - 代码侧 elide:用
QFontMetrics::elidedText()在设文字前截断,稳定可靠,但要写辅助函数; - 提高左栏上限:把
setMaximumWidth(300)调大,让用户自己拖宽。这是最被动的做法,但作为兜底可以。
这一版三个都没做——因为占位数据是短的,框架阶段不需要。但要把这个隐患写下来:功能阶段接真实歌单名时,第一件事就是处理长文本省略。 否则用户建一个长名字歌单,导航就撑破了。
像素密度方面,QSS 里用的是 px 不是 pt(#navList::item { padding: 7px 14px; })。在鸿蒙 PC 的高分屏上,Qt 会按设备像素比缩放,实际显示尺寸会随 DPI 变化。字体用的是 pt(font.setPointSize(10)),也会缩放。两者混用没问题,但要在真机上确认缩放后布局不破——这是高分屏适配的常规检查项。
6. 我踩过的坑(每一条都有真实报错)
这一节可能是全文最值钱的部分。以下坑全部来自这次搭建的真实报错和排查记录。
坑一:分组头没关交互位,被鼠标选中。
第一版分组头和普通项一样可点,用户点"我的音乐"那行也高亮。
现象:点击分组头「我的音乐」后该行高亮
期望:分组头不可选中
无编译错误
排查过程:一开始想在 QListWidget::itemClicked 信号里判断文本,发现没法接——没有 Q_OBJECT 就没法用传统槽函数。后来才反应过来:不用接信号,从源头把项的交互位清掉就行。
修复:it->setFlags(it->flags() & ~Qt::ItemIsSelectable & ~Qt::ItemIsEnabled)。
教训:Item-Based 控件的交互控制,优先改项的 ItemFlags,不要靠信号槽拦截。
坑二:& ~ 写成了 | ~,分组头反而全可选。
我一度把位运算写反,写成 flags() | ~Qt::ItemIsSelectable,结果所有位都被置 1,分组头全变成可选。
现象:分组头依然可选中,且出现了奇怪的复选框
排查过程:一开始以为 ItemIsEnabled 没清干净,单独又清了一次还是不行。后来把 flags 的值打印出来,发现所有位都是 1——问题在 | 而不是 &。
修复:改成 flags() & ~Qt::ItemIsSelectable & ~Qt::ItemIsEnabled。
教训:清除标志位用 & ~,设置标志位用 |。这个是 C++ 位运算基本功,但在 Qt 的枚举上写错很隐蔽。
坑三:QListWidget 自带边框,和左栏背景打架。
现象:导航列表外面有一圈系统默认边框,左侧栏看起来像套了个框
排查过程:一开始去 QSS 里写 #navList { border: none; },效果不稳定——有些 QStyle 下 QSS 的 border 覆盖不了 frame shape。后来才反应过来:应该用 API 直接关掉 frame。
修复:m_navList->setFrameShape(QFrame::NoFrame)。
教训:控件自带的 frame 用 setFrameShape() 关,比用 QSS 的 border 覆盖可靠。
坑四:窗口失焦后选中态消失。
前面第 5.3 节讲过,这是这次最值钱的坑。
现象:切到别的应用再回来,「发现音乐」的红色选中文字变成灰色
排查过程:一开始怀疑是 setCurrentRow() 在失焦时被重置,打印 currentRow 发现还是 1——选中项没变,是外观变了。后来翻 QStyle 文档才看清楚,失焦时 :active 伪状态不再匹配,:selected 规则失效。
修复:补一条 #navList::item:selected:!active 规则。
教训:QSS 伪状态随窗口激活状态重算,选中态必须同时写 :selected 和 :selected:!active 两条。
坑五:双击导航项能改文字。
现象:双击「播客」进入编辑状态,文字被改成了乱码
排查过程:一开始以为是项的属性问题,去查 ItemIsEditable,发现默认就没设。后来才反应过来:QListWidget 控件级的 editTriggers 默认是 DoubleClicked|EditKeyPressed,即使项没有 ItemIsEditable,某些 QStyle 下仍可能进入编辑。
修复:m_navList->setEditTriggers(QAbstractItemView::NoEditTriggers)。
教训:编辑行为要控件级和项级都关,光关项级不够。
坑六:想用 setIndentation 加缩进,编译报错。
error: 'class QListWidget' has no member named 'setIndentation'
排查过程:setIndentation() 是 QTreeWidget 的 API,我记混了。QListWidget 没有这个方法。
修复:改用 QSS 的 #navList::item { padding-left: 14px; }。
教训:QListWidget 和 QTreeWidget API 不通用,缩进这类样式优先走 QSS。
坑七:QStringLiteral 接变量,编译报错。
这个坑在文件管理器系列里真实踩过,这里差点重蹈覆辙——想用循环加导航项时顺手写了 QStringLiteral(item.name):
error: cannot convert 'const char*' to 'const char16_t*' in initialization
排查过程:QStringLiteral 宏只接受字符串字面量,不接受变量。它用 sizeof 在编译期算长度,变量没有这个信息。
修复:变量用 QString::fromUtf8(item.name),只有字面量才用 QStringLiteral(...)。
教训:QStringLiteral 只接字面量;变量转 QString 用 fromUtf8()。
坑八:窄窗口下出现水平滚动条。
现象:窗口缩到 900px 时导航区底部出现横向滚动条
排查过程:长文本"工作白噪音"撑宽了项,默认水平滚动条策略是 ScrollBarAsNeeded,就冒出来了。
修复:setHorizontalScrollBarPolicy(Qt::ScrollBarAlwaysOff)。
教训:导航列表不该横向滚动,超长文本交给裁剪或省略号处理。
7. 现在怎么用:从 Demo 到依赖
构建和上一个系列一样,DevEco 打开 qt-hello,自动签名,右键 entry Run。命令行:
cd /storage/Users/currentUser/Documents/DevEcoStudioProjects/qt-hello
export DEVECO_SDK_HOME=/data/service/hnp/hmos-clt.org/hmos-clt_1.0.0/sdk
$NODE $HVIGOR assembleHap --mode module -p product=default -p module=entry@default --no-daemon
这一篇没有引入新模块,CMakeLists.txt 不用改,仍然只链接 Qt5::Core / Qt5::Gui / Qt5::Widgets。QListWidget 在 Widgets 里,QFont / QColor 在 GUI 里,都已经覆盖。
测试方面,这一版是静态导航,没有可测的逻辑分支。验证方式是真机上做三组操作:点击分组头(确认无反应)、点击普通项(确认选中态切换)、切换窗口焦点(确认选中态保持)。真机结果:三组都符合预期。
硬限制清单,免得读者踩到同一堵墙:
Q_OBJECT/slots/signals三个宏一个都不能碰,moc 跑不了;.qrc用不了,图标优先用QStyle::SP_*标准图标或磁盘路径;QListWidget没有setIndentation(),缩进走 QSS padding;QStringLiteral只接字面量,变量用fromUtf8();- 选中态必须写
:selected和:selected:!active两条规则,否则失焦就丢样式; - QSS 用
setObjectName("navList")做契约,objectName 写错整段样式失效。
更多推荐
所有评论(0)