Qt 鸿蒙音乐播放器图片显示实战:qrc 跑不了就用 QPainter 在内存画封面,渐变加装饰圆加稳定配色

不打包资源、不读外部文件、不碰 x86 的 rcc,封面还能不能是一张真正的图片?能。这篇文章用一个跑在鸿蒙 PC 上的 Qt 音乐播放器,把"为什么 qrc 这条路走不通"“怎么用 QPainter 在内存里画出渐变封面”“配色怎么做到同一首歌稳定复现”"封面放大后布局怎么不挤爆"这四个问题一次讲透。

工程沿用前面几篇的环境,仓库与版本地址放在这里:


0. 环境与实测设备

项版本/型号
DevEco Studio鸿蒙电脑版(build 号待补),API 26
Qt5.15.17(OHOS18 arm64-v8a 预编译包,Alpha_v10)
鸿蒙 SDKohos-sdk 5.1.0.107
编译器鸿蒙 NDK clang 15.0.4
hvigor版本待补
工程 targetentry → libentry.so
实测设备HarmonyOS NEXT 5.1.0.320,aarch64(具体机型待补)
验证方式鸿蒙 clang -fsyntax-only 语法编译 + 真机 Build

降级验证设备(API 23 的 2in1)这次没用到——生成图片这段只依赖 QtGui 的 QPainter,和 API 级别无关,所以只在一台设备上验证就够。这里先标注,后面真机跑起来有差异再补。


1. 封面还是一块色板——这个问题是怎么找上我的

我一开始也以为,界面上那些封面图不过是"给 QLabel 贴个背景色"的事。前面几篇里,推荐歌单、播客、视频缩略图、歌单大封面,全是一个 colorBox lambda 造出来的——一个 QLabel,写上文字,靠 QSS 给个 background 和 border-radius,看起来像那么回事,但本质就是一块带字的色板。

真机跑起来,这块色板的问题就藏不住了。它不像图。歌单封面本该是有渐变的唱片封套,视频缩略图本该有画面的层次,可我现在给的全是纯色加一行字。更要命的是,我想换成真图片的时候,发现这条路在这套环境里根本走不通。

翻了一圈约束,卡点有两个。

第一个是 rcc。Qt 的资源系统要靠 rcc 把 .qrc 编译成 C++ 源码,而这个 SDK 里的宿主工具是 x86-64 的——qmake、moc、rcc、uic 全都是。这台鸿蒙 PC 是 aarch64,跑这些工具直接 exec format error。所以从第一篇起我们就绕开了 qrc,样式表也都写成 C++ 原始字符串塞在 style.h 里。图片如果走 qrc,等于自己把这堵墙又砌回来。

第二个是外部文件路径。就算我把 PNG 塞进 HAP 的 resources/rawfile,运行时 QPixmap("/xxx/rawfile/cover.png") 这个路径到底怎么拼,在 HAP 沙箱里并不确定。-desktop 上我能 QCoreApplication::applicationDirPath() 拼出来,鸿蒙 QPA 下应用的当前工作目录和文件系统布局是另一套。我不想为了几张封面图,再去趟一遍 HAP 资源路径的浑水。

所以这个题目的边界很清楚:在 qrc 跑不了、外部文件路径不可靠的前提下,用纯代码在运行时生成真正的封面图,贴到界面上,并且能随内容变化、能放大而不挤爆布局。

拆开来就三件事:

  • 图从哪来:用 QPainter 在内存画一张 QPixmap,渐变、装饰、圆角、文字都画上去;
  • 配色怎么稳:同一首歌、同一个歌单,每次启动都要得到同一张图,不能随机;
  • 放大了放不下怎么办:封面从 150 一路加到 240,横排的容器迟早撑爆,得有布局层面的解法。

底下这一节埋一个报错,第 6 节会回收它。最开始我把封面文字的 QSS 写成了这样:

/* 旧版:靠 QSS 给"图片"上色——这从来就不是图片 */
#heroCover {
    background: #ec4141;
    color: #ffffff;
    font-size: 40pt;
    border-radius: 8px;
}

这段不报错,但它暴露了旧思路的天花板:所有"图"的视觉效果都压在 QSS 上,调色靠改 stylesheet,调大小靠改 setFixedSize,调字号靠改 font-size——三处分散,而且永远只是色板,不会变成图。

下面是干完之后的完整记录,包括我踩的每一个坑。


2. 效果展示

按老规矩,先给效果再讲原理。

请添加图片描述

这是发现音乐页。顶部横幅下面是"推荐歌单"四个横向排列的封面:私人漫游、每日推荐、华语流行榜、轻音乐。它们不再是纯色块,而是带渐变底色、半透明装饰圆的封面图,每个色系都不一样。这一行现在放在一个横向滚动区里——封面放大到 240×240 后,四个并排已经超过内容区宽度,可以左右拖动查看。

这里每一行都不是装饰:封面的渐变起点和终点色来自配色表,装饰圆是两次 drawEllipse,居中的歌单名是 drawText,而圆角是 QPainterPath 的裁剪——不是 QSS 的 border-radius。换句话说,这张图本身就是圆的,贴到哪都是圆的。

请添加图片描述

这是点进"我喜欢的音乐"之后的歌单详情页。左侧是一张 180×180 的大封面,▲ 播放全部按钮贴在标题下面,再往下是歌曲表格。封面比推荐页的大一圈,因为它承担的是"这一页的主视觉"角色。

请添加图片描述

底部播放条的封面更小,只有 52×52,但它是活的:点任意一首歌,setNowPlaying 会按歌名换一张图。同一首歌每次都得到同一张——这是因为配色种子是歌名 hash 算出来的,不是随机数。

请添加图片描述

这是工作白噪音页,雨声、咖啡馆、森林、篝火四张场景图,每张都是渐变底加一个符号。这一页的图标之前是 40pt,大得撑满卡片,后来收到了 24pt。

请添加图片描述

这几张截图都是在真机上跑的。有一处边界要交代:封面图是程序生成的抽象图,不是真实专辑照片。要换成真图,得先解决 HAP 资源路径怎么被 Qt 访问——那是另一个题目,这篇不碰。


3. 原理:一张封面图到底是怎么画出来的

Qt 里"在内存里画一张图"这件事,模型比想象的简单。核心就三个类:QPixmap 是画布,QPainter 是笔,QPainterPath 是裁剪模板。流程是:先建一张透明的图片当画布,拿 painter 在上面画渐变、画圆、写字,最后把这张画好的 pixmap 贴到 QLabel 上。

把它翻译成这一步要做的事,就是一张表:

步骤用的 API产物为什么这么做
建画布QPixmap(w, h) + fill(Qt::transparent)一张透明图圆角外要透明,不能是白底
开抗锯齿setRenderHint(QPainter::Antialiasing)—圆角和斜边不锯齿
裁剪形状QPainterPath + setClipPath圆角矩形或正圆图自带圆角,不靠 QSS
铺渐变QLinearGradient + fillRect渐变底比纯色有层次
加装饰drawEllipse ×2半透明圆让图看起来"设计过"
写字/图标setFont + drawText居中文字让封面有内容标识
贴到界面QLabel::setPixmap显示出来一张真正的图

这里有一个全文最重要的模型判断:封面是一张离屏画好的位图,QLabel 只是把它挂到界面上;它和 QSS 的 background 没有任何关系。 想通这一点,后面所有坑都好解释——为什么要把 QSS 里的背景改成 transparent,为什么圆角要画在图里而不是靠 border-radius,为什么调大小改的是 makeArt 的参数而不是 stylesheet。

为什么这个判断值得单独拎出来?因为旧思路把三件事搅在了一起:图的内容、图的大小、图的圆角,全分散在 setFixedSize、font-size、border-radius 三个地方。新思路把它们收敛到一个函数 makeArt(text, w, h, seed, circle)——传文字、传尺寸、传种子、传形状,返回一张画好的图。所有视觉参数都在一处,调起来才不会东一榔头西一棒子。

这两个细节决定了后面所有的调优逻辑:图是画出来的,所以能任意放大;配色是按种子算的,所以能稳定复现。


4. 工程怎么搭

工程沿用前面几篇的鸿蒙 Qt 骨架,新增图片相关代码后,cpp 目录是这样:

qt-hello/entry/src/main/cpp/
├── main.cpp                 # 入口:加载 QSS,启动 MusicPlayerWindow
├── style.h                  # QSS 原始字符串(图片类选择器背景已改透明)
├── musicplayerwindow.h      # 窗口类声明(仍无 Q_OBJECT)
└── musicplayerwindow.cpp    # 封面生成 makeArt + 11 页构建 + 联动

这次整理最关键的变化,是把"图片"从一个 QSS 概念变成一个数据概念。以前图片是 --coverColor: #ec4141 这种样式值,现在图片是 makeArt() 返回的一个 QPixmap 对象。三条边界因此成立:

  • 生成逻辑不依赖界面:makeArt 放在匿名 namespace 里,是个纯函数,给它文字和尺寸它就画图,不知道 QLabel 的存在;
  • 配色不依赖随机数:种子用 qHash(text) 算,同一种文字永远同一个结果,重启也不变;
  • 界面不依赖资源文件:没有 qrc、没有外部路径,整个 HAP 不需要为几张封面多带任何东西。

最小接入代码就是贴一张图。三步:调生成函数、拿到 pixmap、set 上去:

// musicplayerwindow.cpp - colorBox(节选)
auto colorBox = [](QWidget *parent, const QString &text, int w, int h,
                   const QString &name, bool circle = false) -> QLabel * {
    auto *b = new QLabel(parent);
    b->setObjectName(name);
    b->setFixedSize(w, h);
    b->setPixmap(makeArt(text, w, h, artSeed(text), circle));
    b->setAlignment(Qt::AlignCenter);
    return b;
};

这里没有通道协议——因为不涉及跨端插件,图片全程在 C++ 侧生成。这一点和系列里那些 Flutter/RN 文章不同:那些要把能力封装成 MethodChannel 给 Dart 调,这里直接在窗口类里画完贴上去,没有 Native 与 UI 之间的往返。

收在两个容易被忽略的细节上。第一,colorBox 的第一个参数是 parent,当封面被塞进滚动区时,parent 得传滚动区里的宿主 widget,不能传外面的 page——否则图片会画在错误的层级上。第二,setFixedSize(w, h) 和 makeArt(text, w, h, ...) 的 w/h 必须一致,图片尺寸和 Label 尺寸对不上,要么留白要么被压缩。


5. 把代码讲透

5.1 配色表:为什么是十组而不是十张图

封面图的第一层是配色。我用一个结构体数组存配色,每组三个颜色:渐变起点、渐变终点、文字色。

// musicplayerwindow.cpp - ART_PALETTES(节选)
struct ArtPalette {
    const char *from;   // 渐变起点色
    const char *to;     // 渐变终点色
    const char *ink;    // 文字/装饰色
};

static const ArtPalette ART_PALETTES[] = {
    { "#ff6b6b", "#c92a2a", "#ffffff" },  // 红
    { "#4dabf7", "#1864ab", "#ffffff" },  // 蓝
    { "#51cf66", "#2b8a3e", "#ffffff" },  // 绿
    { "#b197fc", "#6741d9", "#ffffff" },  // 紫
    // ... 共 10 组
};

请添加图片描述

三个细节值得单独说。

第一,每组三个色不是为了好看,是为了可读性。 前九组的文字色都是白色,因为渐变两端都够深;第八组黄色底色太亮,白字会看不清,所以文字色换成了 #5f3b00 深褐。这个判断是看实际效果改的——黄色那张图写出来第一版是白字,真机上一看几乎融进背景,才换的深色。

第二,色值用 const char* 而不是 QColor。 这是一张静态表,程序启动时不用构造十个 QColor 对象;等真要画的时候再 QColor(QString::fromLatin1(pal.from)) 临时转。十张图这点开销可以忽略,但把数据表和运行时对象分开,调试时改色值更直观。

第三,为什么要十组。 太少了,相邻歌单会撞色,看起来像复制粘贴;太多了,配色风格不统一,界面会花。十组是我调到既够区分、又不至于杂乱的一个数。这是主观值,你要是觉得不够,改这个数组就行——加一组配色不需要动任何别的代码。

反直觉陷阱:不要用随机数选配色。 我一开始图省事用 qrand(),结果每次启动同一首歌封面颜色都不一样,底部播放条的封面会跳色。歌单封面这种东西要有"身份感",同一个名字就该是同一张图。这就是下一节种子函数存在的理由。

5.2 稳定配色:qHash 让同一首歌永远是同一张图

配色种子用 qHash 算:

// musicplayerwindow.cpp - artSeed()
int artSeed(const QString &text)
{
    const uint h = qHash(text) & 0x7fffffffU;
    return int(h % uint(ART_PALETTE_COUNT));
}

请添加图片描述

三个细节值得单独说。

第一,为什么要 & 0x7fffffffU。 qHash 返回 uint,但转成 int 后可能是负数——最高位是符号位。负数取模在 C++ 里结果还是负数,拿去索引数组就越界了。掩码把最高位清掉,保证结果落在 [0, 2^31),再取模就一定是合法下标。这一位掩码省掉的是一段很难查的崩溃。

第二,取模用 ART_PALETTE_COUNT 而不是写死的 10。 配色表加一组、减一组,种子函数自动适配。写死 10 的话,哪天删了一组配色,数组越界就开始 Random 崩溃。

第三,种子来源是文字本身。 传进来的 text 对推荐封面是歌单名,对播放条封面是歌名首字。同一个名字 → 同一个 hash → 同一个配色。这比"按列表下标取色"稳得多:插入、删除一个歌单,后面所有封面不会整体错位换色。

反直觉陷阱:不要以为 hash 碰撞是个问题。 十组配色,中文歌单名 hash 撞到同一组很正常——两个不同歌单同色,用户根本不会注意。我在意的是"同名稳定",不是"所有名字颜色都不同"。这两个目标不一样,别搞混。

这一节的方案只在 Qt5 的 qHash(QString) 上验证过。Qt6 改了 hash 的实现,同一个字符串算出的值会不同——但"同名稳定"这个性质仍然成立,只是具体配色会换一批。迁移到 Qt6 时要重新看一遍颜色分布。

5.3 画一张图:四步把色板变成封面

核心函数 makeArt 把一张图画出来。这是全文最值钱的一段。

// musicplayerwindow.cpp - makeArt()(节选)
QPixmap makeArt(const QString &text, int w, int h, int seed, bool circle = false)
{
    const ArtPalette &pal = ART_PALETTES[seed % ART_PALETTE_COUNT];

    QPixmap pic(w, h);
    pic.fill(Qt::transparent);
    QPainter p(&pic);
    p.setRenderHint(QPainter::Antialiasing, true);

    QPainterPath clip;
    if (circle) {
        clip.addEllipse(0, 0, w, h);
    } else {
        clip.addRoundedRect(0, 0, w, h, qMin(w, h) / 7.0, qMin(w, h) / 7.0);
    }
    p.setClipPath(clip);

    QLinearGradient grad(0, 0, w, h);
    grad.setColorAt(0.0, QColor(QString::fromLatin1(pal.from)));
    grad.setColorAt(1.0, QColor(QString::fromLatin1(pal.to)));
    p.fillRect(0, 0, w, h, grad);

    p.setPen(Qt::NoPen);
    p.setBrush(QColor(255, 255, 255, 38));
    p.drawEllipse(QRectF(w * 0.52, -h * 0.28, w * 0.72, h * 0.86));
    p.setBrush(QColor(0, 0, 0, 26));
    p.drawEllipse(QRectF(-w * 0.22, h * 0.46, w * 0.66, h * 0.74));

    // ... 文字部分见 5.4
    p.end();
    return pic;
}

请添加图片描述

三个细节值得单独说。

第一,画布要先填透明再裁剪。 pic.fill(Qt::transparent) 不能省。如果省掉,QPixmap 初始内容是未定义的(通常是黑或白),圆角裁剪之后,圆角外的区域会露出那层脏底色,看起来就是"圆角图外面套了个方块"。填了透明,圆角外才是真的没有东西。

第二,圆角画在图里,不靠 QSS。 QPainterPath 的 addRoundedRect 把绘制区域裁成圆角矩形,setClipPath 之后所有绘制都被限制在这条路径里。这样生成的图本身就是圆的,贴到任何容器都是圆角。旧思路靠 QSS 的 border-radius,那只是把 QLabel 的绘制区域裁圆,pixmap 的四个角还是会顶出来——两者不是一回事。

第三,装饰圆要画在裁剪之后。 先 setClipPath 再 drawEllipse,装饰圆超出圆角边界的部分会被自动裁掉,不会冒出去。顺序反了的话,装饰圆会盖在圆角外面,边框就不干净了。

反直觉陷阱:别用 fillRect 直接画渐变而忘了裁剪路径。 fillRect 填的是整个矩形,它不会自动感知 QSS 的 border-radius。裁剪必须在 painter 层面做——这也是为什么我把 cardBox、heroCover 这些选择器的 background 全改成了 transparent,让图自己说话。

这一节用的 QPainter、QLinearGradient、QPainterPath 都在 QtGui 模块,工程的 target_link_libraries 已经链了 Qt5::Gui,不需要加任何依赖。

5.4 字号:从 40pt 收到克制的几行判断

文字这一块是这次改动里反复最多的——用户先说"图标太大了",才有了现在这套字号逻辑。

// musicplayerwindow.cpp - makeArt() 文字部分
p.setPen(QColor(QString::fromLatin1(pal.ink)));
QFont f = p.font();
f.setBold(true);
int px;
if (text.size() > 3) {
    // 多字:按可用宽度估字号,留边距,并封顶
    px = qMin(qMin(w / (text.size() + 1), h / 4), 16);
} else {
    // 单字/图标:正方形图取边长 1/5,宽图取高 1/9,别超过 20
    px = (w > h * 1.5) ? qMin(h / 9, 16) : qMin(qMin(w, h) / 5, 20);
}
px = qMax(9, px);   // 下限,保证可读
f.setPointSize(px);
p.setFont(f);
p.drawText(0, 0, w, h, Qt::AlignCenter, text);

请添加图片描述

三个细节值得单独说。

第一,多字和单字走两套公式。 单字(♥、♪、途、夜这种图标字)可以放大到 20px 封顶,因为一个字再大也不会溢出;多字(“私人漫游”"华语流行榜"这种歌单名)必须按宽度估——w / (字数 + 1) 给每个字留出平均宽度,再和 h / 4 取较小值,最后封顶 16。一个公式管所有情况,结果就是要么溢出要么太小。

第二,宽图单独判。 w > h * 1.5 判定这是视频缩略图那种宽图,字号按高度算而不是按宽度。宽图按宽度算会得到一个巨大的字号,字会顶到上下边缘。

第三,上下限都要有。 qMax(9, px) 保证小图里字不会缩到看不见;封顶保证大图里字不撑满。40pt 那个版本就是没有上限,♥ 一个字把整张封面撑满了,才有了这次的收紧。

反直觉陷阱:字号不能只看字体大小,要看它相对图的比例。 同样 20px,在 52px 的播放条封面上很大,在 240px 的推荐封面上很小。所以这里全部用比例算,而不是给一个固定 pt 值——这也是为什么 QSS 里写死 font-size: 40pt 是错的,它和图的尺寸完全脱钩。

5.5 放大与滚动:150 到 240 的布局接力

用户一路要求"封面搞大一点",尺寸从 150 加到 240,这中间布局得跟上。

// musicplayerwindow.cpp - 发现页推荐区(节选)
auto *cardScroll = new QScrollArea(page);
cardScroll->setObjectName(QStringLiteral("cardScroll"));
cardScroll->setWidgetResizable(true);
cardScroll->setVerticalScrollBarPolicy(Qt::ScrollBarAlwaysOff);
cardScroll->setHorizontalScrollBarPolicy(Qt::ScrollBarAsNeeded);
cardScroll->setFixedHeight(268);
auto *cardHost = new QWidget(cardScroll);
auto *cardRow = new QHBoxLayout(cardHost);
cardRow->setSpacing(16);
// 240×240 封面,四个并排
cardScroll->setWidget(cardHost);
lay->addWidget(cardScroll);

请添加图片描述

三个细节值得单独说。

第一,为什么非得套滚动区。 240×240 的封面四张并排,加三道 16px 间距,总宽约 1008px,而内容区只有八百多。硬塞进去的结果就是后两张被挤出可视区域,或者整个布局被撑变形。QScrollArea 让容器宽度和封面总宽解耦——封面可以一直放大,放不下的部分横向滚。

第二,setWidgetResizable(true) 的取舍。 开了之后,宿主 widget 会跟着视口宽度拉伸,addStretch(1) 让封面靠左排列;不开的话宿主保持封面总宽,滚动区照样能滚,但视口比内容窄时行为略不同。这里开不开都能滚,选开是为了让空白区域跟着窗口走,观感更自然。

第三,滚动条样式复用全局。 style.h 里已经有 QScrollBar:horizontal 的扁平样式,这个滚动区不用单独写——objectName 设成 cardScroll 只是为了背景透明、去掉默认灰边框,滚动条本身沿用全局。这是前面几篇沉淀下来的好处:样式系统是统一的,新加容器不用从头调。

反直觉陷阱:别试图靠缩小封面来"塞下"四张。 用户要的就是大封面,缩小等于违背需求。正确的判断是:布局服从内容,不是内容迁就布局。放不下就滚,这是资源管理器、相册这类界面都用的成熟模式。

这一节的限制要说清楚:横向滚动依赖鼠标滚轮或触摸板横滑,触屏上要手动拖。真机上如果横滑不灵敏,得再补一套左右按钮——这块还没验证,先标注「待补」。


6. 我踩过的坑(每一条都有真实报错)

这一节可能是全文最值钱的部分。以下坑全部来自这次开发的真实报错和排查记录,其中有几条是用户实测后反馈的视觉问题,一并记在这里。

坑一:把 QStringLiteral 用在变量上,编译直接挂。

最早写导航项时我图快,把 const char* 变量塞进了 QStringLiteral:

error: cannot initialize a parameter of type 'const char *' with an lvalue of type 'const QString'
    child->setText(0, QStringLiteral(item.name));

QStringLiteral 只接受字面量,不接受变量。变量要用 QString::fromUtf8()。改完是 child->setText(0, QString::fromUtf8(item.name))。

一开始以为 QStringLiteral 只是"快一点的 QString 构造",后来才反应过来它是编译期把字面量存进只读段的宏——变量没有编译期值,根本没法用。

QStringLiteral 的参数必须是字面量,变量一律 QString::fromUtf8()。

坑二:重写 cpp 时漏了 #include <QSplitter>。

多页面改造那次,QSplitter 的 include 被我重写没了,编译报:

error: invalid use of incomplete type 'class QSplitter'
    m_splitter = new QSplitter(Qt::Horizontal, this);

头文件里只前置声明了 QSplitter,cpp 里 new 它就需要完整定义。补上 #include <QSplitter> 就好。

一开始以为是 Qt 版本问题,翻了半天文档,后来才反应过来是前置声明惹的祸——头文件里能用指针,是因为只声明了类型;cpp 里要构造对象,必须有完整定义。

前置声明只够用指针,new 对象必须 include 完整头文件。

坑三:封面文字 QSS 写死 40pt,一个符号撑满整张图。

这是用户反馈的"图标太大了"。旧代码:

#noiseIcon { font-size: 40pt; }
/* heroCover 的图标字在 makeArt 里按边长 1/3 算,110px 封面约 36px */

真机上看,白噪音那四个符号(☂ ☕ ♣ ✦)把卡片撑得满满当当,歌单封面上的 ♥ 也是。

一开始以为是图片生成有问题,后来才反应过来是字号和图片尺寸完全脱钩——40pt 写死在 QSS 里,不管图是 52px 还是 240px,字都是 40pt。修复是两处一起改:#noiseIcon 从 40pt 收到 24pt,makeArt 的字号改成按图的尺寸比例算并封顶(见 5.4)。

字号必须相对图片尺寸算,写死 pt 值迟早撑爆。

坑四:把封面从 150 加到 240,横排放不下,布局被撑变形。

用户连续几次说"封面太小了",我一路从 150 加到 190,最后到 240。加到 190 时还行——四张 190 加间距约 802px,内容区约 812px,刚好卡着。加到 240 就撑爆了:四张加间距约 1008px,内容区根本放不下,后两张被挤出去。

一开始想继续压间距、缩 margins 来"挤一挤",后来才反应过来这是在 wrong direction——用户明确要的就是大封面,压缩布局等于抵消需求。正确的判断是布局服从内容:套一个 QScrollArea 横向滚动,封面想多大就多大,放不下的横滑看。

内容尺寸和容器宽度冲突时,让容器滚动,别让内容缩水。

坑五:QSS 的 background 没清干净,圆角图外面露出方块底色。

刚把色块换成图片那版,封面是圆角了,但四个角外面隐约有一圈灰底。原因是这些选择器的 QSS 还留着旧背景:

/* 旧:图片是圆的了,背景还是方的 */
#cardBox {
    background: #fafafa;
    border: 1px solid #eeeeee;
    border-radius: 8px;
}

图片本身圆角透明,但 QLabel 的 background 还在画,圆角外的矩形区域就露出来了。

一开始以为是 makeArt 的裁剪没生效,把 QPainterPath 翻来覆去检查,后来才反应过来问题在 QSS:图是画对了,是标签的底色在捣乱。修复是把 cardBox、podcastCover、videoThumb、feedAvatar、feedCover、heroCover、coverArt 这七个选择器的 background 全改成 transparent、border 去掉。

图片自带圆角后,QSS 背景必须清成透明,否则圆角外露方块。

坑六:底部播放条封面是死的,切歌不换图。

第一版底部封面贴了一张固定图,点不同的歌封面纹丝不动。检查发现 buildPlayBar 里直接 cover->setPixmap(...) 就完了,没有存成成员,setNowPlaying 根本碰不到它。

修复是三步:头文件加 QLabel *m_coverArt 成员;buildPlayBar 里把局部变量改成成员并贴初始图;setNowPlaying 里按歌名换图。

// musicplayerwindow.cpp - setNowPlaying()(节选)
if (m_coverArt) {
    m_coverArt->setPixmap(makeArt(title.left(1), 52, 52, artSeed(title)));
}

一开始以为是 connect 没接上,查了半天信号,后来才反应过来是根本没有可更新的成员指针——播放条上的封面是个局部变量的孤儿。

要联动的控件必须存成成员,局部变量出不了构建函数。

坑七:用随机配色,同一首歌每次启动封面颜色都变。

这个坑前面 5.2 节提过一句,这里展开。第一版选配色图省事用了 qrand(),结果每次启动应用,同一首歌的封面颜色都不一样,底部播放条切来切去会跳色,看着很廉价。

一开始以为是配色表不够多导致"看起来像变了",后来打日志看 seed 才发现每次都是新随机数。修复就是 artSeed 那个函数——用 qHash(text) 代替随机数,同名稳定。

需要"身份感"的视觉元素,配色种子必须来自内容本身,不能用随机数。

坑八:能跑不等于方案对——色板版其实从没解决"图片"问题。

这条是工程化层面的。前面几版用 colorBox 加 QSS,界面能跑、能看,用户也能接受,但它解决的是"看起来像封面",不是"封面是一张图"。这俩的区别在要放大、要换图、要圆角的时候才暴露出来——色板版每加一个需求就要在 QSS、setFixedSize、字号三处改,图版只改 makeArt 的参数。

一开始觉得色板版"够用了",后来才反应过来它是把复杂度摊到了三个地方,每次调整都要三处同步,早晚会漏。重构成一张真正的位图后,所有视觉参数收敛到一个函数,这才是能长期维护的形态。

"能跑"和"方案对"是两回事:把分散在三处的参数收敛到一个函数,才是可维护的解法。


7. 现在怎么用:从色板到封面图

如果你也在鸿蒙 PC 上用 Qt 做界面,又碰上"图片显示"这件事,这就是我这几天趟出来的路:

  • 环境里 rcc 跑不了,就别碰 qrc——样式写 C++ 原始字符串,图片用 QPainter 运行时画;
  • 外部图片路径在 HAP 沙箱不可靠,就把图片变成代码产物,不变成文件依赖;
  • 配色要稳定,用 qHash(内容) 当种子,别用随机数;
  • 圆角画在图里(QPainterPath),QSS 背景清成透明;
  • 字号按图片尺寸比例算并封顶,别写死 pt;
  • 封面放大放不下,套横向滚动,别压缩内容。

构建还是老三样:DevEco 里勾自动签名,右键 entry 模块 Run。改了 cpp 不用重新 Sync(CMakeLists 没动),直接 Build。真机验证结果:五个页面的封面都正常显示,切歌换图正常,横向滚动可用;横滑灵敏度这一项还没在触屏上验证,标「待补」。

硬限制清单,免得读者踩到同一堵墙:

  • qrc / rcc 在这套 SDK 上跑不了(x86 宿主工具),图片资源不能走 Qt 资源系统;
  • 外部图片文件路径在 HAP 沙箱里不确定,QPixmap(path) 方案需要先趟资源路径;
  • QPainter 画的图是抽象封面,不是真实照片,要真图得解决资源打包;
  • qHash(QString) 在 Qt6 改了实现,迁移时同名仍稳定但具体配色会变;
  • 横向滚动依赖横滑/滚轮,触屏灵敏度待验证;
  • 全程无 Q_OBJECT——图片生成是纯函数,不碰 moc,这条约束守住了。
Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐