Qt 鸿蒙音乐播放器左侧导航实战:QListWidget 分组头不可选靠 ItemFlags 位运算,选中态交给 QSS 伪状态,从裸列表到像 Windows 的侧边栏

左侧那条导航看似只是"一列文字",真正写起来才发现它卡在三个地方:分组头怎么变成不可点的标题、选中态怎么在窗口失焦后还留着、图标和缩进怎么在不用资源文件的前提下做出来。这篇文章用一个跑在鸿蒙真机上的音乐播放器,把"QListWidget 的项标志位运算"“QSS 伪状态的真实行为”"无 qrc 时的图标方案"这三个问题一次讲透。

仓库与版本地址:


0. 环境与实测设备

项版本 / 型号
DevEco Studio鸿蒙电脑版,build 号「待补」,API 26
Qt5.15.17(发行版 Alpha_v10)
Qt SDK 路径/storage/Users/currentUser/Qt5.15.17_OHOS/qt5.15.17_arm64-v8a
OHOS SDKAPI 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 工厂"。这带来三条边界:

  1. 分组头和普通项走不同构造函数:addSection() 关交互、设小字灰字;addItem() 保留可选、不可编辑;
  2. 新增导航项只写一行:addItem(QStringLiteral("新项")),不用重复设置属性;
  3. 样式和逻辑分离:项的属性在 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。图标来源有三条路:

方案做法在这套环境里的可行性
资源文件 .qrcQIcon(":/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 精选合集”)就会超出。

处理办法有三个:

  1. QSS 省略号:给 item 设 text-overflow: ellipsis;,超长文本显示成"我喜欢的音乐…"。这是最省事的做法,但 QSS 对 ::item 的 text-overflow 支持在不同 QStyle 下不一致,得真机验证;
  2. 代码侧 elide:用 QFontMetrics::elidedText() 在设文字前截断,稳定可靠,但要写辅助函数;
  3. 提高左栏上限:把 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 写错整段样式失效。
Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐