怪兽马尔克

CineSeek：免费的VIP视频解析站点

Fri, 14 Aug 2026 12:00:00 GMT

最近做了一个新的影视项目，叫 CineSeek。

它现在还没有开源，功能也没有做得很大，目前只接入了腾讯视频这一条内容源。首页推荐、频道浏览、搜索、播放和弹幕这些基本流程已经跑通，播放解析暂时使用虾米解析接口。

部署地址：

https://cineseek.markqq.com

我没有一开始就把所有平台都接进去。先选一个来源，把数据、页面和播放链路做完整，再考虑后面的扩展，可能更适合这个项目现在的状态。

先做一个可以浏览的首页#

CineSeek 的首页先从内容开始，而不是只放一个搜索框。

顶部是焦点推荐，可以在几部内容之间切换；下面按照“重磅热播”和“为你推荐”等区域组织内容。电视剧、电影、综艺、动漫等频道放在左侧导航中，也保留了少儿、纪录片、体育和中视频等入口。

CineSeek 首页

首页数据由腾讯视频 Provider 提供。上游返回的卡片、图片、标题、类型和链接，会先被整理成统一的媒体数据，再交给页面展示。

这样首页推荐、频道列表和搜索结果虽然长得不一样，但最后使用的是同一套媒体模型。以后接入其他平台时，页面不用跟着每个平台的字段重新修改。

目前只有腾讯视频#

CineSeek 当前启用的 Provider 只有腾讯视频。

爱奇艺和芒果 TV 已经在 Provider 注册表里预留了位置，不过还没有实现。后续如果继续扩展平台，需要分别处理各个平台的首页、搜索、频道、详情和播放方式，再转换成统一的数据结构。

腾讯这一条链路目前拆成了几个部分：共享模块负责请求端点和原始值读取，卡片解析器负责递归遍历和字段映射，首页、搜索、片库、推荐和详情则各自处理自己的数据。

现在这样拆开，主要是为了让一个页面的数据变化不要牵扯到所有地方。等第二个平台真正接入时，也能更清楚地看到两个 Provider 之间的差异。

搜索之后，直接打开播放页#

搜索页负责把内容找出来。

输入片名、演员或关键词之后，CineSeek 会请求搜索接口，展示搜索结果、类型、海报和简介。搜索建议和热搜也有单独的接口，输入还没有完成时，可以先给出一些可选内容。

CineSeek 搜索结果

找到内容之后，可以直接进入播放页。播放页会显示当前剧集、影片资料、演员表和选集列表。电视剧按照集数展示按钮，并标记限免、预告、VIP 和 SVIP 等状态。

播放解析和播放器#

目前播放解析使用虾米接口。

播放时，服务端先尝试获取 HLS 或 MP4 直链，再交给播放器。如果直链解析失败，则切换到备用的 iframe 播放线路。对页面来说，这只是同一个播放流程里的两条线路。

CineSeek 播放页

播放器使用 Artplayer 和 HLS.js。播放页还支持剧集切换、上一集、下一集以及弹幕显示。弹幕按照播放时间窗口请求，不会在页面打开时一次性加载全部数据；播放到对应时间段时，再获取相应内容。

现在最重要的事情不是把播放器做得多复杂，而是让用户能够从搜索结果顺利走到播放页，并且在解析失败时得到清楚的反馈。

页面失败时保留一点余地#

影视内容的上游接口并不总是稳定，所以 CineSeek 做了一些简单的降级处理。

首页首屏会先使用 fallback 数据，客户端加载完成后再请求实时内容。频道页面和推荐内容请求失败时，尽量保留最近一次成功的数据；搜索失败时则不生成伪造结果。

API 错误也会统一返回 error、code 和 retryable 字段，让页面能够判断这次请求是否适合重试。播放直链解析失败时，则优先切换备用线路，而不是让整个播放页直接结束。

这些处理并不能让第三方服务变得稳定，只是尽量让页面在偶尔失败时不要显得突然失去控制。

后面会做什么#

下一步会考虑爱奇艺和芒果 TV。

不过新的 Provider 不只是换一个请求地址。每个平台的首页结构、搜索结果、频道分类、详情字段和播放方式都可能不同，需要分别处理，再转换成统一的媒体模型。

所以我会先把腾讯这一条链路继续整理好，包括播放失败时的提示、更多详情数据、选集交互和移动端体验。等 Provider 的边界稳定下来，再接入其他平台会更自然一些。

目前 CineSeek 还是一个正在变化的项目。先让它能够稳定地找到一部片、打开播放页、切换剧集，再慢慢把其他事情补上。

关于上游内容和使用边界#

CineSeek 不存储影视内容。页面中的标题、图片、简介、播放地址和弹幕数据，都来自上游内容源或第三方解析服务。

腾讯视频相关接口不是版本化的官方应用 SDK，解析服务也可能随时变化。内容的可用性、版权状态和服务条款不由这个项目保证。

使用时请自行确认相关内容和接口的版权、服务条款以及所在地的法律要求。

CineSeek 当前部署在：

https://cineseek.markqq.com

MarkAI：做一个属于自己的 AI 工作台

Fri, 07 Aug 2026 12:00:00 GMT

最近一直在整理 MarkAI。

它并不是一个只接入某一家模型的聊天页面，而是我想做成的一套 AI 工作台：可以在同一个界面里切换不同的模型，进行联网搜索，读取文件，生成文档、表格和图表，也可以把它部署在自己的服务器上。

项目地址：

https://github.com/markcxx/mark-ai

为什么要做一个自己的工作台#

现在使用 AI 的场景越来越多，但不同的事情经常需要打开不同的工具。

普通对话在一个页面里，联网搜索在另一个页面里；需要分析 PDF 或表格时，要重新上传文件；想把回答整理成 Word 或 Excel，又要再做一次转换。

这些事情本身都不难，只是来回切换的次数多了以后，信息会被分散在不同的地方。

所以我想做一个相对集中的工作界面。模型只是其中的一部分，文件、工具、生成结果和会话本身也应该被当作同一条工作流来处理。

这个想法后来逐渐变成了 MarkAI。

一个以会话为中心的界面#

MarkAI 的基本单位是会话。

左侧是会话列表，主区域负责消息和输入。用户可以在当前会话里选择模型、打开联网搜索、上传附件，或者启用某个工具。不同的能力不会被拆成互相孤立的页面，而是尽量留在同一条对话里。

MarkAI 聊天工作台

桌面端的会话侧栏可以调整宽度，主面板则专注于消息、模型选择、附件和输入区。移动端会把侧栏切换成临时抽屉，同时保留消息操作和输入区域的安全边距。

我比较在意的是内容的阅读感。

普通模式会限制消息的阅读宽度，避免长文本铺满整个屏幕；需要查看表格、代码或图表时，又可以切换到宽屏模式。它们都是一些不显眼的选择，但会影响长时间使用时的感觉。

不同模型放在同一个入口#

MarkAI 支持多种模型提供商。

Gemini 使用原生 runtime，其他大多数提供商则通过 OpenAI-compatible runtime 接入。模型在系统中使用 provider/model 的形式标识，因此即使不同供应商有同名模型，也不会混在一起。

目前仓库里提供了 Google Gemini、OpenAI、DeepSeek、MiniMax、Moonshot、阿里云百炼、智谱、OpenRouter、硅基流动、火山方舟、Groq、Mistral、Together AI、xAI、HuggingFace 和无问芯穹等提供商模板。

这些模板只负责提供默认的 Base URL、runtime 和一些推荐模型。真正使用时，仍然需要配置自己的 API Key 和模型列表。

这样做的好处是，模型切换不再需要修改页面代码。管理员或用户可以在设置中选择默认模型，也可以针对不同任务选择不同的模型。

MarkAI 模型提供商设置

消息不只有正文#

在普通的聊天应用里，一条消息通常就是一段文本。但模型开始推理、调用工具、生成文件之后，单纯的文本结构就不够了。

MarkAI 会把正文、推理过程、工具调用、生成文件和翻译保存为不同类型的消息片段。

OpenAI-compatible 服务有时会返回结构化 reasoning，有时会在正文里使用 <think> 标签。服务端需要在任意 SSE 分块边界上把这些内容归一化，否则一个标签刚好被分成两半时，就可能把推理文本错误地显示到最终回答里。

现在消息可以显示推理过程、推理耗时、生成耗时和 token 用量，也支持停止、继续和重新生成。重新生成之后，不同版本的回复也会保留下来。

MarkAI 的消息、推理与用量展示

消息操作也尽量做得完整一些：复制、编辑、删除、翻译、语音朗读、选择到此处和批量操作都可以在消息上完成。

语音播放不是把整篇文本一次性塞进去，而是按消息片段处理。这样暂停、继续和重新播放时，都更容易对应到当前正在阅读的内容。

工具跟着会话走#

MarkAI 里有一个插件中心，用来管理内置 Tool 和 Skill。

工具需要先安装到当前账户，再按会话启用。这样不同会话可以保持不同的工作方式：查资料的会话开启联网搜索，整理表格的会话开启计算或文件工具，普通聊天则不必加载额外能力。

MarkAI 插件中心

目前内置工具包括联网搜索、网页阅读、可靠计算、Word 生成、Excel 生成、ECharts、Mermaid 和 Markmap 等。

模型可以先搜索网页，再根据引用继续回答；也可以读取上传的 PDF、DOCX、XLSX、CSV 或普通文本文件，然后把结果整理成新的内容。

工具的结果不会被当作普通文本直接拼到消息里，而是作为结构化片段保存。这样在重新打开会话时，原来的工具调用、来源和生成文件仍然能够被识别。

文件理解和生成#

文件能力是我在 MarkAI 里比较重视的一部分。

上传文件之后，系统会按照类型进行处理：PDF、DOCX、XLSX、CSV 和常见文本可以提取内容，图片则作为附件交给模型理解。文件可以保存在本地目录，也可以在云端模式下使用 Cloudflare R2。

MarkAI 文件管理

输入文件只是第一步。更有用的情况是，模型把分析结果继续生成可下载的文件。

例如让模型根据一份数据生成 Excel，或者把一段材料整理成 Word 文档；需要展示趋势时，可以生成 ECharts；需要表达层级关系时，可以生成 Mermaid 或 Markmap。

这些内容最后都会进入统一的文件存储和下载流程，而不是只能停留在聊天气泡里。

本地模式和云端模式#

MarkAI 可以在本地运行，也可以部署成带账户系统的服务。

本地模式使用 SQLite，不需要配置账户系统。会话、设置、工具状态和用户文件都保存在当前服务器上，适合个人在电脑上使用。

云端模式则使用 PostgreSQL、Better Auth 和 Cloudflare R2。它提供邮箱登录、Google/GitHub SSO、注册策略、等候名单、用户管理和审计记录，更适合放到服务器上供多个用户使用。

两种模式共享同一套主要界面和业务逻辑，区别主要集中在数据存储、认证和文件服务上。

这也是我选择自托管的原因之一：想要简单使用时，可以只保留 SQLite；需要更完整的服务形态时，再切换到云端数据库和对象存储。

部署并不复杂#

本地运行只需要 Node.js 22 和一个可用的模型 API Key：

Terminal window

1
git clone https://github.com/markcxx/mark-ai.git
2
cd mark-ai
3
npm install
4
cp .env.example .env.local
5
npm run dev

然后打开 http://localhost:3000 即可。

仓库也提供了 Dockerfile 和 Compose 示例。生产环境可以使用 Next.js standalone 输出，把服务放在 Nginx、Caddy 或其他反向代理之后。

如果只想在本地使用，SQLite 模式已经足够；如果需要账户、多人使用和云端文件，则可以配置 PostgreSQL 和 Cloudflare R2。

还在继续整理#

MarkAI 目前已经有了比较完整的工作台形状，但仍然有不少地方需要继续打磨。

模型供应商的接口会变化，文件解析也会遇到新的格式；复杂的生成任务需要更好的进度反馈，移动端还有一些交互可以继续简化。

我希望它最后保持一种安静的状态：不需要用户记住太多入口，也不需要为了完成一个小任务打开很多页面。模型、文件和工具各自完成自己的工作，然后在同一个会话里留下可以继续使用的结果。

MarkAI 的源码和部署说明都已经放在 GitHub：

markcxx/mark-ai

CoCo Downloader：从几个简单的接口开始

Sat, 21 Mar 2026 12:00:00 GMT

最开始做 CoCo Downloader，并不是因为我有一个特别完整的产品计划。

只是偶然发现，有几个第三方音乐网站的接口比较简单，分析起来并不困难。于是我顺手写了一个小工具，把歌曲搜索出来，再把相关的信息和地址整理到一起。

那时的想法很直接，甚至算不上什么正式项目。能搜到歌，能看到歌名和歌手，基本就已经够用了。

后来这个项目被越来越多的人发现，开始有人提建议，也有人提出新的需求。我原来只接入了几个来源，后来便陆续增加了更多平台。项目也从一个简单的页面，慢慢变成了现在的 CoCo Downloader。

项目地址：

https://github.com/markcxx/coco-downloader

从几个接口开始#

不同音乐平台之间，搜索结果和接口返回的数据并不完全一样。

有的接口返回歌曲名、歌手和专辑信息，有的还会提供歌词、音质或播放地址。有些来源可以直接拿到结果，有些则需要再请求一次接口，才能得到实际的播放地址。

刚开始接入的来源不多，所以这些差异还可以直接写在页面逻辑里。但随着平台越来越多，继续这样处理就会变得麻烦：页面需要知道每个来源的参数、字段和异常情况，修改一个地方，也可能影响其他来源。

后来我把这些实现拆到了 provider 层。

现在 Web 端的结构大致是：

1
页面组件
2
    ↓
3
API Routes
4
    ↓
5
统一的数据处理
6
    ↓
7
不同音源的 Provider

页面只处理统一格式的歌曲数据，具体某个平台要怎样搜索、怎样解析、怎样获取播放地址，则交给对应的 provider 完成。

目前项目中接入的来源包括爱听、波点音乐、布谷音乐、歌曲宝、歌曲海、煎饼音乐系列、JOOX、米兔音乐、LivePoo、咪咕音乐，以及一些其他第三方 API。

这些来源并不是永久稳定的。接口可能变化，返回字段可能调整，某些来源也可能暂时无法使用。因此 provider 层除了让结构更清晰，也方便在某个来源发生变化时单独修改。

Web 端#

Web 端使用 Next.js、React 和 TypeScript 构建。它现在主要围绕搜索结果展开：输入歌曲名或歌手，得到多个来源的结果，然后试听、查看歌词，或者发起下载。

默认页面并不复杂，搜索框放在比较显眼的位置，下面是歌曲列表和播放器。对我来说，这种界面已经足够了。音乐工具不需要在第一屏放太多东西，能尽快找到想找的歌更重要。

CoCo Downloader Web 端首页

Web 端的 API Routes 分别处理不同的事情：

api/search 负责搜索；
api/url 负责获取播放地址；
api/download 负责下载流程；
api/lyric 负责歌词；
lib/providers/impl 保存各个来源的具体实现。

搜索之后，结果会按照统一的数据结构展示出来。不同来源的字段差异被留在 provider 内部处理，页面不需要知道某个来源的接口具体长什么样。

CoCo Downloader Web 端搜索结果

播放器只是为了确认歌曲#

CoCo Downloader 里有播放器，但它的目的并不是做一个完整的在线音乐平台。

很多时候，同一首歌会有不同的版本，歌名可能相同，歌手名称也可能相近。只看搜索结果，很难确认自己找到的到底是不是想要的那一首。

所以我加了播放功能。

搜索到歌曲之后，可以先试听一下，确认歌手、版本和音质是否符合预期，再决定要不要下载。播放器的作用就是这么简单：让用户在保存之前，先听一听这首歌是不是自己要找的歌。

播放器目前支持播放、暂停、上一曲、下一曲、进度拖动、音量控制和播放模式切换。底部播放栏会一直保留在页面中，切换搜索结果时，不需要离开当前页面。

歌词页面则是播放器的另一种展开。当需要确认一首歌，或者只是想跟着听的时候，歌词会比一行标题更有用。

CoCo Downloader Web 端歌词播放器

下载和音质选择#

确认歌曲之后，可以从搜索结果直接发起下载。单首歌曲适合临时保存，多首歌曲则会进入下载任务列表。

批量下载时，任务会集中显示在下载抽屉中，可以看到每一首歌曲的处理状态。这样至少能够知道哪些任务已经完成，哪些还在进行中。

CoCo Downloader Web 端下载任务

不同来源提供的音质并不一样。大部分逆向接口并不支持自定义音质，有些来源默认会返回较高音质；网易云相关的部分接口则提供了音质选择。

因此项目里的音质选择不是一个对所有来源都适用的统一开关，而是根据具体来源返回的内容决定。能选择什么，最终还是要看对应接口提供了什么。

后来又做了桌面端#

Web 端完成之后，我又做了桌面端。

桌面端使用 PyQt5 和 QFluentWidgets 编写，代码放在项目的 desktop 目录中。它没有复用 Web 页面，而是重新实现了一套更接近本地应用的界面。

桌面端包含主窗口、首页、下载页和设置页，也有搜索卡片、播放栏和下载任务卡片。用户可以设置下载目录和文件命名规则，应用配置会保存到用户自己的系统目录中，而不是直接写入安装目录。

桌面端的目录大致分成几层：

1
desktop/
2
├─ app/view/                  # 页面和窗口
3
├─ app/components/            # 播放栏、搜索卡片、下载任务卡片
4
├─ app/services/              # 搜索、播放、下载服务
5
├─ app/services/providers/    # 不同音源
6
├─ app/common/                # 配置、资源、样式和信号
7
└─ app/resource/              # 图片、图标、翻译和样式资源

Web 端和桌面端的界面不同，但背后的问题很接近：搜索需要统一，播放需要统一，下载也需要统一，只有不同平台的接口实现各自保留差异。

CoCo Downloader 桌面端首页

桌面端还可以继续制作 Windows 安装包或便携版本。相比 Web 端，它需要处理更多窗口、资源和打包相关的问题，不过安装之后直接从桌面打开，也有另一种方便。

CoCo Downloader 桌面端歌词页面

项目是怎样慢慢变大的#

CoCo Downloader 的很多功能，并不是一开始就计划好的。

最初只是接入几个比较容易分析的第三方网站。后来承蒙站内朋友推广，项目获得了一些关注，也有人希望搜索结果更多，于是我继续增加音源。

音源变多之后，需要重新整理 provider 结构；搜索结果变多之后，需要考虑重复歌曲和不同来源之间的数据差异；加入下载之后，又需要处理下载目录、文件名和任务状态。

播放器也是在这个过程中加进去的。它不负责建立一个完整的播放生态，只是让搜索和下载之间多一个确认步骤。

这些功能单独看都不大，但组合起来之后，项目就不再是一个简单的请求接口页面了。需要处理的事情变多，代码也需要不断整理。

有时候是先把功能做出来，再回头调整结构；有时候是某个来源突然变化，才发现原来的写法不够灵活。开发过程并不总是按照计划推进，更多时候是遇到一个问题，再解决一个问题。

开源之后#

项目放到 GitHub 上之后，慢慢有了更多关注。

截至目前，仓库已经有五百多个 Star。对一个从临时想法开始的项目来说，这已经是比较意外的结果。

最初我只是觉得几个接口比较有意思，想把它们组合起来试试看。后来看到有人真的在使用，才开始认真考虑项目的目录结构、部署方式和不同客户端的维护。

一个项目被别人使用之后，很多原本可以忽略的问题都会变得明显。

自己只在本地运行时，某些异常情况可能很难遇到；别人使用时，网络环境、系统版本和操作习惯都不一样。反馈并不一定都是功能需求，有时只是一个很小的错误提示，或者一个不太容易发现的操作问题。

这些反馈让项目慢慢变得比最开始更完整。

使用和部署#

Web 端可以直接在本地启动：

Terminal window

1
npm install
2
npm run dev

也可以使用 Docker 部署：

Terminal window

1
docker compose up -d

桌面端则需要进入 desktop 目录：

Terminal window

1
cd desktop
2
pip install -r requirements.txt
3
python CoCo-downloader.py

项目的具体说明和更新内容，可以在 GitHub 仓库中查看：

markcxx/coco-downloader

关于第三方接口#

CoCo Downloader 不存储音乐文件。

项目中的歌曲信息、歌词、播放地址和下载地址，来自不同的第三方接口。接口的稳定性、返回结果、音质和版权情况，都由对应的第三方服务决定。

所以项目更接近一个音乐检索、试听和下载工具，而不是音乐资源仓库。

项目使用 MIT License，主要用于个人学习、技术研究和交流。使用时请尊重音乐版权，并遵守所在地的法律法规。

最后#

现在回头看，CoCo Downloader 的起点其实很小。

只是发现几个接口容易分析，于是写了一个页面；后来因为被更多人看到，才继续增加平台和功能。它没有一个特别宏大的开始，也没有一条完全按照计划铺开的路线。

项目现在还会继续维护。第三方接口会变化，新的来源可能还会加入，Web 端和桌面端也有一些地方需要继续整理。

不过这些事情并不着急。能在需要的时候打开它，搜索一首歌，试听一下，然后确认这就是自己想要的版本，已经是这个项目最初也最实际的用途了。

OpenAI API 格式规范与实现指南

Sun, 24 Aug 2025 09:00:00 GMT

概述#

OpenAI API 是一套标准化的 RESTful API 接口，用于与大型语言模型进行交互。本文档详细介绍了如何实现兼容 OpenAI API 格式的服务接口。

核心特性#

标准化格式：遵循 OpenAI 官方 API 规范
流式响应：支持实时流式输出
多模型支持：可适配不同的语言模型
错误处理：完善的错误响应机制
认证安全：Bearer Token 认证方式

API 规范#

基础 URL 结构#

1
GET  /v1/models                    # 获取模型列表
2
POST /v1/chat/completions          # 聊天完成接口
3
GET  /health                       # 健康检查

HTTP 头部要求#

1
Content-Type: application/json
2
Authorization: Bearer YOUR_API_KEY
3
Accept: application/json

状态码规范#

状态码	含义	使用场景
200	成功	正常响应
400	请求错误	参数验证失败
401	未授权	API Key 无效
404	未找到	路由不存在
422	参数错误	请求格式错误
500	服务器错误	内部处理异常

请求格式#

聊天完成请求 (POST /v1/chat/completions)#

基本参数#

1
{
2
  "model": "gpt-3.5-turbo",
3
  "messages": [
4
    {
5
      "role": "system",
6
      "content": "You are a helpful assistant."
7
    },
8
    {
9
      "role": "user",
10
      "content": "Hello, how are you?"
11
    }
12
  ],
13
  "stream": false,
14
  "temperature": 0.7,
15
  "max_tokens": 1000,
16
  "top_p": 1.0,
17
  "frequency_penalty": 0.0,
18
  "presence_penalty": 0.0,
19
  "stop": null,
20
  "user": "user-123"
21
}

展开收起

参数详解#

参数	类型	必需	默认值	说明
model	string	✓	-	模型名称
messages	array	✓	-	对话消息列表
stream	boolean	✗	false	是否流式响应
temperature	number	✗	1.0	随机性控制 (0.0-2.0)
max_tokens	integer	✗	null	最大生成 token 数
top_p	number	✗	1.0	核采样参数 (0.0-1.0)
frequency_penalty	number	✗	0.0	频率惩罚 (-2.0-2.0)
presence_penalty	number	✗	0.0	存在惩罚 (-2.0-2.0)
stop	string/array	✗	null	停止序列
user	string	✗	null	用户标识

消息格式#

1
{
2
  "role": "user|assistant|system|function",
3
  "content": "消息内容",
4
  "name": "可选的名称",
5
  "reasoning": "可选的推理内容（用于 reasoning 模型）"
6
}

角色说明：

system: 系统提示，设定 AI 的行为
user: 用户消息
assistant: AI 助手的回复
function: 函数调用结果

响应格式#

非流式响应#

1
{
2
  "id": "chatcmpl-123456789",
3
  "object": "chat.completion",
4
  "created": 1677652288,
5
  "model": "gpt-3.5-turbo",
6
  "choices": [
7
    {
8
      "index": 0,
9
      "message": {
10
        "role": "assistant",
11
        "content": "Hello! I'm doing well, thank you for asking.",
12
        "reasoning": "用户问候，我应该礼貌回应"
13
      },
14
      "finish_reason": "stop"
15
    }
16
  ],
17
  "usage": {
18
    "prompt_tokens": 20,
19
    "completion_tokens": 15,
20
    "total_tokens": 35
21
  }
22
}

展开收起

响应字段说明#

字段	类型	说明
id	string	响应唯一标识符
object	string	对象类型
created	integer	创建时间戳
model	string	使用的模型
choices	array	生成的选择列表
usage	object	Token 使用统计

finish_reason 说明#

值	说明
stop	自然结束
length	达到最大长度
content_filter	内容过滤
function_call	函数调用

流式响应#

Server-Sent Events (SSE) 格式#

流式响应使用 SSE 格式，每个数据块以 data: 开头：

1
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
2

3
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":" there!"},"finish_reason":null}]}
4

5
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
6

7
data: [DONE]

流式响应结构#

1
{
2
  "id": "chatcmpl-123456789",
3
  "object": "chat.completion.chunk",
4
  "created": 1677652288,
5
  "model": "gpt-3.5-turbo",
6
  "choices": [
7
    {
8
      "index": 0,
9
      "delta": {
10
        "role": "assistant",
11
        "content": "Hello",
12
        "reasoning": "推理内容（可选）"
13
      },
14
      "finish_reason": null
15
    }
16
  ]
17
}

展开收起

流式响应要点#

Content-Type: text/event-stream
缓存控制: Cache-Control: no-cache
连接保持: Connection: keep-alive
结束标记: 最后发送 data: [DONE]
错误处理: 异常时发送错误信息并结束流

错误处理#

错误响应格式#

1
{
2
  "error": {
3
    "message": "Invalid API key provided",
4
    "type": "invalid_request_error",
5
    "param": "api_key",
6
    "code": "invalid_api_key"
7
  }
8
}

常见错误类型#

错误类型	HTTP 状态码	说明
invalid_request_error	400	请求格式错误
invalid_api_key	401	API Key 无效
insufficient_quota	429	配额不足
model_not_found	404	模型不存在
server_error	500	服务器内部错误

FastAPI 实现#

项目结构#

1
project/
2
├── main.py              # 应用入口
3
├── models.py            # 数据模型
4
├── api_server.py        # API 路由
5
├── converter.py         # 格式转换
6
├── config.py            # 配置管理
7
└── requirements.txt     # 依赖包

数据模型定义 (models.py)#

1
from typing import List, Optional, Union, Dict, Any
2
from pydantic import BaseModel, Field
3
from enum import Enum
4

5
class Role(str, Enum):
6
    """消息角色枚举"""
7
    SYSTEM = "system"
8
    USER = "user"
9
    ASSISTANT = "assistant"
10
    FUNCTION = "function"
11

12
class Message(BaseModel):
13
    """聊天消息模型"""
14
    role: Role
15
    content: str
16
    name: Optional[str] = None
17
    reasoning: Optional[str] = None
18

19
class ChatCompletionRequest(BaseModel):
20
    """聊天完成请求模型"""
21
    model: str
22
    messages: List[Message]
23
    temperature: Optional[float] = Field(default=1.0, ge=0.0, le=2.0)
24
    top_p: Optional[float] = Field(default=1.0, ge=0.0, le=1.0)
25
    n: Optional[int] = Field(default=1, ge=1)
26
    stream: Optional[bool] = False
27
    stop: Optional[Union[str, List[str]]] = None
28
    max_tokens: Optional[int] = Field(default=None, ge=1)
29
    presence_penalty: Optional[float] = Field(default=0.0, ge=-2.0, le=2.0)
30
    frequency_penalty: Optional[float] = Field(default=0.0, ge=-2.0, le=2.0)
31
    user: Optional[str] = None
32

33
class Usage(BaseModel):
34
    """使用情况统计"""
35
    prompt_tokens: int
36
    completion_tokens: int
37
    total_tokens: int
38

39
class Choice(BaseModel):
40
    """选择项模型"""
41
    index: int
42
    message: Message
43
    finish_reason: Optional[str] = None
44

45
class ChatCompletionResponse(BaseModel):
46
    """聊天完成响应模型"""
47
    id: str
48
    object: str = "chat.completion"
49
    created: int
50
    model: str
51
    choices: List[Choice]
52
    usage: Usage
53

54
class Delta(BaseModel):
55
    """流式响应增量"""
56
    role: Optional[str] = None
57
    content: Optional[str] = None
58
    reasoning: Optional[str] = None
59

60
class StreamChoice(BaseModel):
61
    """流式选择项"""
62
    index: int
63
    delta: Delta
64
    finish_reason: Optional[str] = None
65

66
class ChatCompletionStreamResponse(BaseModel):
67
    """流式聊天完成响应"""
68
    id: str
69
    object: str = "chat.completion.chunk"
70
    created: int
71
    model: str
72
    choices: List[StreamChoice]

展开收起

API 路由实现 (api_server.py)#

1
from fastapi import FastAPI, HTTPException, Request
2
from fastapi.middleware.cors import CORSMiddleware
3
from fastapi.responses import StreamingResponse
4
import logging
5
import time
6
from typing import AsyncGenerator
7

8
from models import (
9
    ChatCompletionRequest,
10
    ChatCompletionResponse,
11
    ChatCompletionStreamResponse,
12
    StreamChoice,
13
    Delta
14
)
15

16
app = FastAPI(
17
    title="OpenAI Compatible API",
18
    description="OpenAI 格式兼容的 API 服务",
19
    version="1.0.0"
20
)
21

22
# CORS 中间件
23
app.add_middleware(
24
    CORSMiddleware,
25
    allow_origins=["*"],
26
    allow_credentials=True,
27
    allow_methods=["*"],
28
    allow_headers=["*"],
29
)
30

31
@app.get("/")
32
async def root():
33
    """根路径"""
34
    return {
35
        "message": "OpenAI Compatible API Server",
36
        "version": "1.0.0",
37
        "endpoints": {
38
            "chat": "/v1/chat/completions",
39
            "models": "/v1/models",
40
            "health": "/health"
41
        }
42
    }
43

44
@app.get("/health")
45
async def health_check():
46
    """健康检查"""
47
    return {"status": "healthy", "timestamp": int(time.time())}
48

49
@app.post("/v1/chat/completions")
50
async def create_chat_completion(request: ChatCompletionRequest, http_request: Request):
51
    """创建聊天完成"""
52
    # 获取 API Key
53
    auth_header = http_request.headers.get("Authorization")
54
    if not auth_header or not auth_header.startswith("Bearer "):
55
        raise HTTPException(
56
            status_code=401,
57
            detail={
58
                "error": {
59
                    "message": "Invalid API key provided",
60
                    "type": "invalid_request_error",
61
                    "code": "invalid_api_key"
62
                }
63
            }
64
        )
65

66
    api_key = auth_header[7:]  # 移除 "Bearer " 前缀
67

68
    try:
69
        if request.stream:
70
            # 流式响应
71
            return StreamingResponse(
72
                generate_stream_response(request, api_key),
73
                media_type="text/event-stream",
74
                headers={
75
                    "Cache-Control": "no-cache",
76
                    "Connection": "keep-alive",
77
                    "Content-Type": "text/event-stream"
78
                }
79
            )
80
        else:
81
            # 非流式响应
82
            response = await generate_completion(request, api_key)
83
            return response
84

85
    except Exception as e:
86
        raise HTTPException(
87
            status_code=500,
88
            detail={
89
                "error": {
90
                    "message": str(e),
91
                    "type": "server_error",
92
                    "code": "internal_error"
93
                }
94
            }
95
        )
96

97
async def generate_completion(request: ChatCompletionRequest, api_key: str) -> ChatCompletionResponse:
98
    """生成非流式完成响应"""
99
    # 这里实现你的模型调用逻辑
100
    # 示例实现
101
    response_id = f"chatcmpl-{int(time.time())}"
102

103
    # 模拟响应
104
    return ChatCompletionResponse(
105
        id=response_id,
106
        created=int(time.time()),
107
        model=request.model,
108
        choices=[
109
            Choice(
110
                index=0,
111
                message=Message(
112
                    role="assistant",
113
                    content="这是一个示例响应"
114
                ),
115
                finish_reason="stop"
116
            )
117
        ],
118
        usage=Usage(
119
            prompt_tokens=10,
120
            completion_tokens=5,
121
            total_tokens=15
122
        )
123
    )
124

125
async def generate_stream_response(request: ChatCompletionRequest, api_key: str) -> AsyncGenerator[str, None]:
126
    """生成流式响应"""
127
    response_id = f"chatcmpl-{int(time.time())}"
128
    created = int(time.time())
129

130
    try:
131
        # 模拟流式输出
132
        content_chunks = ["这是", "一个", "流式", "响应", "示例"]
133

134
        for chunk in content_chunks:
135
            stream_response = ChatCompletionStreamResponse(
136
                id=response_id,
137
                created=created,
138
                model=request.model,
139
                choices=[
140
                    StreamChoice(
141
                        index=0,
142
                        delta=Delta(content=chunk),
143
                        finish_reason=None
144
                    )
145
                ]
146
            )
147
            yield f"data: {stream_response.model_dump_json()}\n\n"
148

149
            # 模拟延迟
150
            import asyncio
151
            await asyncio.sleep(0.1)
152

153
        # 发送结束标记
154
        final_response = ChatCompletionStreamResponse(
155
            id=response_id,
156
            created=created,
157
            model=request.model,
158
            choices=[
159
                StreamChoice(
160
                    index=0,
161
                    delta=Delta(),
162
                    finish_reason="stop"
163
                )
164
            ]
165
        )
166
        yield f"data: {final_response.model_dump_json()}\n\n"
167
        yield "data: [DONE]\n\n"
168

169
    except Exception as e:
170
        # 错误处理
171
        error_response = {
172
            "error": {
173
                "message": str(e),
174
                "type": "server_error",
175
                "code": "internal_error"
176
            }
177
        }
178
        yield f"data: {json.dumps(error_response)}\n\n"
179
        yield "data: [DONE]\n\n"
180

181
@app.get("/v1/models")
182
async def list_models():
183
    """获取模型列表"""
184
    return {
185
        "object": "list",
186
        "data": [
187
            {
188
                "id": "gpt-3.5-turbo",
189
                "object": "model",
190
                "created": 1677610602,
191
                "owned_by": "openai"
192
            },
193
            {
194
                "id": "gpt-4",
195
                "object": "model",
196
                "created": 1687882411,
197
                "owned_by": "openai"
198
            }
199
        ]
200
    }

展开收起

配置管理 (config.py)#

1
import os
2
from typing import List
3
from dotenv import load_dotenv
4

5
load_dotenv()
6

7
class Config:
8
    """应用配置类"""
9

10
    def __init__(self):
11
        # 服务器配置
12
        self.host: str = os.getenv("HOST", "0.0.0.0")
13
        self.port: int = int(os.getenv("PORT", "8000"))
14
        self.debug: bool = os.getenv("DEBUG", "false").lower() == "true"
15

16
        # API 配置
17
        self.api_prefix: str = os.getenv("API_PREFIX", "/v1")
18
        self.cors_origins: List[str] = os.getenv("CORS_ORIGINS", "*").split(",")
19

20
        # 模型配置
21
        self.default_model: str = os.getenv("DEFAULT_MODEL", "gpt-3.5-turbo")
22
        self.max_tokens: int = int(os.getenv("MAX_TOKENS", "2048"))
23

24
        # 安全配置
25
        self.api_keys: List[str] = os.getenv("API_KEYS", "").split(",")
26

27
    def validate_api_key(self, api_key: str) -> bool:
28
        """验证 API Key"""
29
        if not self.api_keys or not self.api_keys[0]:
30
            return True  # 如果没有配置 API Key，则不验证
31
        return api_key in self.api_keys
32

33
config = Config()

展开收起

应用入口 (main.py)#

1
import uvicorn
2
from api_server import app
3
from config import config
4

5
if __name__ == "__main__":
6
    uvicorn.run(
7
        "api_server:app",
8
        host=config.host,
9
        port=config.port,
10
        reload=config.debug,
11
        log_level="info" if not config.debug else "debug"
12
    )

认证与安全#

Bearer Token 认证#

1
from fastapi import HTTPException, Depends
2
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
3

4
security = HTTPBearer()
5

6
async def verify_api_key(credentials: HTTPAuthorizationCredentials = Depends(security)):
7
    """验证 API Key"""
8
    if not config.validate_api_key(credentials.credentials):
9
        raise HTTPException(
10
            status_code=401,
11
            detail={
12
                "error": {
13
                    "message": "Invalid API key provided",
14
                    "type": "invalid_request_error",
15
                    "code": "invalid_api_key"
16
                }
17
            }
18
        )
19
    return credentials.credentials
20

21
# 在路由中使用
22
@app.post("/v1/chat/completions")
23
async def create_chat_completion(
24
    request: ChatCompletionRequest,
25
    api_key: str = Depends(verify_api_key)
26
):
27
    # 处理请求
28
    pass

展开收起

请求限制#

1
from slowapi import Limiter, _rate_limit_exceeded_handler
2
from slowapi.util import get_remote_address
3
from slowapi.errors import RateLimitExceeded
4

5
limiter = Limiter(key_func=get_remote_address)
6
app.state.limiter = limiter
7
app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
8

9
@app.post("/v1/chat/completions")
10
@limiter.limit("10/minute")
11
async def create_chat_completion(request: Request, ...):
12
    # 处理请求
13
    pass

最佳实践#

1. 错误处理#

1
# 统一错误处理中间件
2
@app.middleware("http")
3
async def error_handling_middleware(request: Request, call_next):
4
    try:
5
        response = await call_next(request)
6
        return response
7
    except Exception as e:
8
        return JSONResponse(
9
            status_code=500,
10
            content={
11
                "error": {
12
                    "message": "Internal server error",
13
                    "type": "server_error",
14
                    "code": "internal_error"
15
                }
16
            }
17
        )

展开收起

2. 日志记录#

1
import logging
2
from datetime import datetime
3

4
# 配置日志
5
logging.basicConfig(
6
    level=logging.INFO,
7
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
8
)
9
logger = logging.getLogger(__name__)
10

11
# 请求日志中间件
12
@app.middleware("http")
13
async def log_requests(request: Request, call_next):
14
    start_time = datetime.now()
15

16
    # 记录请求
17
    logger.info(f"Request: {request.method} {request.url}")
18

19
    response = await call_next(request)
20

21
    # 记录响应
22
    process_time = (datetime.now() - start_time).total_seconds()
23
    logger.info(f"Response: {response.status_code} - {process_time:.3f}s")
24

25
    return response

展开收起

3. 参数验证#

1
from pydantic import validator
2

3
class ChatCompletionRequest(BaseModel):
4
    model: str
5
    messages: List[Message]
6
    temperature: Optional[float] = 1.0
7

8
    @validator('temperature')
9
    def validate_temperature(cls, v):
10
        if v < 0.0 or v > 2.0:
11
            raise ValueError('temperature must be between 0.0 and 2.0')
12
        return v
13

14
    @validator('messages')
15
    def validate_messages(cls, v):
16
        if not v:
17
            raise ValueError('messages cannot be empty')
18
        return v

展开收起

4. 性能优化#

1
# 异步处理
2
import asyncio
3
from concurrent.futures import ThreadPoolExecutor
4

5
executor = ThreadPoolExecutor(max_workers=4)
6

7
async def process_model_request(request_data):
8
    """异步处理模型请求"""
9
    loop = asyncio.get_event_loop()
10
    result = await loop.run_in_executor(
11
        executor,
12
        sync_model_call,
13
        request_data
14
    )
15
    return result
16

17
# 连接池管理
18
from httpx import AsyncClient
19

20
class ModelClient:
21
    def __init__(self):
22
        self.client = AsyncClient(
23
            timeout=30.0,
24
            limits=httpx.Limits(max_connections=100, max_keepalive_connections=20)
25
        )
26

27
    async def call_model(self, data):
28
        response = await self.client.post(
29
            "https://api.model-provider.com/v1/completions",
30
            json=data
31
        )
32
        return response.json()

展开收起

示例代码#

客户端调用示例#

1
import requests
2
import json
3

4
# 非流式请求
5
def test_completion():
6
    url = "http://localhost:8000/v1/chat/completions"
7
    headers = {
8
        "Content-Type": "application/json",
9
        "Authorization": "Bearer your-api-key"
10
    }
11
    data = {
12
        "model": "gpt-3.5-turbo",
13
        "messages": [
14
            {"role": "user", "content": "Hello, how are you?"}
15
        ],
16
        "temperature": 0.7,
17
        "max_tokens": 100
18
    }
19

20
    response = requests.post(url, headers=headers, json=data)
21
    print(response.json())
22

23
# 流式请求
24
def test_stream():
25
    url = "http://localhost:8000/v1/chat/completions"
26
    headers = {
27
        "Content-Type": "application/json",
28
        "Authorization": "Bearer your-api-key"
29
    }
30
    data = {
31
        "model": "gpt-3.5-turbo",
32
        "messages": [
33
            {"role": "user", "content": "Tell me a story"}
34
        ],
35
        "stream": True
36
    }
37

38
    response = requests.post(url, headers=headers, json=data, stream=True)
39

40
    for line in response.iter_lines():
41
        if line:
42
            line = line.decode('utf-8')
43
            if line.startswith('data: '):
44
                data_content = line[6:]
45
                if data_content == '[DONE]':
46
                    break
47
                try:
48
                    chunk = json.loads(data_content)
49
                    content = chunk['choices'][0]['delta'].get('content', '')
50
                    if content:
51
                        print(content, end='', flush=True)
52
                except json.JSONDecodeError:
53
                    pass
54
    print()  # 换行
55

56
if __name__ == "__main__":
57
    test_completion()
58
    test_stream()

展开收起

JavaScript 客户端示例#

1
// 非流式请求
2
async function testCompletion() {
3
    const response = await fetch('http://localhost:8000/v1/chat/completions', {
4
        method: 'POST',
5
        headers: {
6
            'Content-Type': 'application/json',
7
            'Authorization': 'Bearer your-api-key'
8
        },
9
        body: JSON.stringify({
10
            model: 'gpt-3.5-turbo',
11
            messages: [
12
                { role: 'user', content: 'Hello, how are you?' }
13
            ],
14
            temperature: 0.7,
15
            max_tokens: 100
16
        })
17
    });
18

19
    const data = await response.json();
20
    console.log(data);
21
}
22

23
// 流式请求
24
async function testStream() {
25
    const response = await fetch('http://localhost:8000/v1/chat/completions', {
26
        method: 'POST',
27
        headers: {
28
            'Content-Type': 'application/json',
29
            'Authorization': 'Bearer your-api-key'
30
        },
31
        body: JSON.stringify({
32
            model: 'gpt-3.5-turbo',
33
            messages: [
34
                { role: 'user', content: 'Tell me a story' }
35
            ],
36
            stream: true
37
        })
38
    });
39

40
    const reader = response.body.getReader();
41
    const decoder = new TextDecoder();
42

43
    while (true) {
44
        const { done, value } = await reader.read();
45
        if (done) break;
46

47
        const chunk = decoder.decode(value);
48
        const lines = chunk.split('\n');
49

50
        for (const line of lines) {
51
            if (line.startsWith('data: ')) {
52
                const data = line.slice(6);
53
                if (data === '[DONE]') {
54
                    return;
55
                }
56

57
                try {
58
                    const parsed = JSON.parse(data);
59
                    const content = parsed.choices[0]?.delta?.content;
60
                    if (content) {
61
                        process.stdout.write(content);
62
                    }
63
                } catch (e) {
64
                    // 忽略解析错误
65
                }
66
            }
67
        }
68
    }
69
}

展开收起

部署配置#

Docker 部署#

1
FROM python:3.11-slim
2

3
WORKDIR /app
4

5
COPY requirements.txt .
6
RUN pip install --no-cache-dir -r requirements.txt
7

8
COPY . .
9

10
EXPOSE 8000
11

12
CMD ["uvicorn", "api_server:app", "--host", "0.0.0.0", "--port", "8000"]

docker-compose.yml#

1
version: '3.8'
2

3
services:
4
  api:
5
    build: .
6
    ports:
7
      - "8000:8000"
8
    environment:
9
      - DEBUG=false
10
      - API_KEYS=your-secret-key-1,your-secret-key-2
11
      - CORS_ORIGINS=https://yourdomain.com
12
    volumes:
13
      - ./logs:/app/logs
14
    restart: unless-stopped

requirements.txt#

1
fastapi==0.104.1
2
uvicorn[standard]==0.24.0
3
pydantic==2.5.0
4
python-dotenv==1.0.0
5
httpx==0.25.2
6
slowapi==0.1.9

总结#

本文档详细介绍了 OpenAI API 格式的规范和 FastAPI 实现方法。通过遵循这些规范和最佳实践，你可以构建一个完全兼容 OpenAI API 的服务，支持：

✅ 标准化的请求/响应格式
✅ 流式和非流式响应
✅ 完善的错误处理
✅ Bearer Token 认证
✅ 请求限制和安全控制
✅ 高性能异步处理
✅ 易于部署和扩展

这样的实现可以无缝集成到现有的 OpenAI 生态系统中，为用户提供一致的 API 体验。

使用PyQt实现加载骨架屏组件

Wed, 18 Jun 2025 22:21:00 GMT

在现代应用开发中，骨架屏（Skeleton Screen）已经成为提升用户体验的重要手段。相比传统的加载动画，骨架屏能够让用户提前感知页面结构，减少等待时的焦虑感。本文将详细介绍如何在 Qt 框架下实现一个功能完整的骨架屏组件库。

先看效果

核心设计思路#

骨架屏的本质是在内容加载期间显示一个与真实内容结构相似的占位符。这个占位符通常包含灰色的矩形、圆形等基本形状，并配有一个移动的高亮光带来模拟加载过程。

我们的设计目标是创建一个可组合的骨架屏系统，支持多种基本形状（矩形、圆角矩形、圆形），并且能够通过组合这些基本元素来构建复杂的骨架布局。更重要的是，整个骨架屏应该只有一个统一的高亮动画，而不是每个元素都有独立的动画效果。

基础架构设计#

SkeletonBase 基类#

所有骨架组件的基础是 SkeletonBase 类，它继承自 QWidget 并提供了高亮动画的核心功能：

1
class SkeletonBase(QWidget):
2
    def __init__(self, parent=None):
3
        super().__init__(parent)
4
        self._shimmer_position = -100  # 高亮位置
5
        self._animation = QPropertyAnimation(self, b"shimmer_position")
6
        self._setup_animation()
7

8
    def _setup_animation(self):
9
        """配置高亮动画"""
10
        self._animation.setDuration(1000)  # 动画时长
11
        self._animation.setStartValue(-100)  # 起始位置
12
        self._animation.setEndValue(self.width() + 100)  # 结束位置
13
        self._animation.setEasingCurve(QEasingCurve.Type.InOutQuad)
14
        self._animation.setLoopCount(-1)  # 无限循环
15

16
    @pyqtProperty(float)
17
    def shimmer_position(self):
18
        return self._shimmer_position
19

20
    @shimmer_position.setter
21
    def shimmer_position(self, value):
22
        self._shimmer_position = value
23
        self.update()  # 触发重绘

展开收起

这里有几个关键的设计决策需要解释。首先， _shimmer_position 的初始值设为 -100，这是为了让高亮光带从组件的左侧外部开始移动，确保用户能看到完整的进入动画。其次，使用 QPropertyAnimation 配合 @pyqtProperty 装饰器，这样可以让 Qt 的动画系统自动调用我们的 setter 方法，从而触发界面重绘。

绘制系统的实现#

骨架屏的视觉效果主要通过重写 paintEvent 方法来实现。这个方法需要处理两个层次的绘制：基础形状和高亮效果。

1
def paintEvent(self, event):
2
    painter = QPainter(self)
3
    painter.setRenderHint(QPainter.RenderHint.Antialiasing)
4

5
    # 绘制基础骨架形状
6
    path = self._create_shape_path()
7
    painter.fillPath(path, QColor(210, 210, 210))
8

9
    # 设置裁剪区域，确保高亮效果只在骨架形状内显示
10
    painter.setClipPath(path)
11

12
    # 绘制高亮光带
13
    self._draw_shimmer_effect(painter)

裁剪区域的设置是一个重要的技术细节。通过 painter.setClipPath(path) ，我们确保后续的绘制操作只会在指定的形状内生效。这样，即使高亮光带的渐变范围超出了骨架形状，也不会影响到其他区域。

高亮光带的实现原理#

高亮光带的核心是 QLinearGradient ，它创建了一个从透明到半透明白色再到透明的渐变效果：

1
def _draw_shimmer_effect(self, painter):
2
    gradient = QLinearGradient()
3
    gradient.setStart(self._shimmer_position - 50, 0)
4
    gradient.setFinalStop(self._shimmer_position + 50, 0)
5

6
    # 设置渐变颜色
7
    gradient.setColorAt(0, QColor(255, 255, 255, 0))
8
    gradient.setColorAt(0.5, QColor(255, 255, 255, 80))
9
    gradient.setColorAt(1, QColor(255, 255, 255, 0))
10

11
    # 绘制光带
12
    painter.fillRect(rect, QBrush(gradient))

这里的关键是理解渐变的坐标系统。 setStart 和 setFinalStop 定义了渐变的方向，在这个例子中是从左到右的水平渐变。 setColorAt 方法则定义了渐变过程中不同位置的颜色，0.0 表示起点，1.0 表示终点，0.5 表示中点。

高亮区域的宽度设为 100 像素，太窄会显得不够明显，太宽则会影响整体的精致感。

具体形状的实现#

矩形骨架项#

最基础的矩形骨架项实现相对简单，主要是创建无圆角和一个带圆角的矩形路径：

1
class SkeletonItem(SkeletonBase):
2
    """基础骨架项 - 矩形"""
3

4
    def __init__(self, width=100, height=20, parent=None):
5
        super().__init__(parent)
6
        self.setFixedSize(width, height)
7
        self._background_color = QColor(210, 210, 210)
8

9
    def paintEvent(self, event):
10
        painter = QPainter(self)
11
        painter.setRenderHint(QPainter.Antialiasing)
12

13
        rect = self.rect()
14

15
        # 绘制背景
16
        painter.fillRect(rect, self._background_color)
17

18
        # 绘制光带
19
        self.draw_shimmer(painter, rect)

展开收起

1
class RoundedRectSkeletonItem(SkeletonBase):
2
    """圆角矩形骨架项"""
3

4
    def __init__(self, width=100, height=20, radius=8, parent=None):
5
        super().__init__(parent)
6
        self.setFixedSize(width, height)
7
        self._radius = radius
8
        self._background_color = QColor(210, 210, 210)
9

10
    def paintEvent(self, event):
11
        painter = QPainter(self)
12
        painter.setRenderHint(QPainter.Antialiasing)
13

14
        rect = QRectF(self.rect())
15

16
        # 创建圆角路径
17
        path = QPainterPath()
18
        path.addRoundedRect(rect, self._radius, self._radius)
19

20
        # 绘制背景
21
        painter.fillPath(path, self._background_color)
22

23
        # 设置裁剪区域并绘制光带
24
        painter.setClipPath(path)
25
        self.draw_shimmer(painter, self.rect())

展开收起

圆形骨架项#

圆形骨架项需要特别注意的是如何创建一个真正的圆形。简单使用 addEllipse 方法可能会因为宽高不一致而产生椭圆：

1
class CircleSkeletonItem(SkeletonBase):
2
    """圆形骨架项"""
3

4
    def __init__(self, diameter=40, parent=None):
5
        super().__init__(parent)
6
        self.setFixedSize(diameter, diameter)
7
        self._background_color = QColor(210, 210, 210)
8

9
    def paintEvent(self, event):
10
        painter = QPainter(self)
11
        painter.setRenderHint(QPainter.Antialiasing)
12

13
        rect = QRectF(self.rect())
14

15
        # 创建圆形路径
16
        path = QPainterPath()
17
        path.addEllipse(rect)
18

19
        # 绘制背景
20
        painter.fillPath(path, self._background_color)
21

22
        # 设置裁剪区域并绘制光带
23
        painter.setClipPath(path)
24
        self.draw_shimmer(painter, self.rect())

展开收起

容器系统的设计#

单个骨架项只能显示简单的形状，真正的挑战在于如何将多个骨架项组合成复杂的布局，并且保持统一的高亮动画效果。

SkeletonContainer 的核心逻辑#

SkeletonContainer 类负责管理多个骨架项，并提供统一的动画控制：

1
class SkeletonContainer(QWidget):
2
    """骨架容器基类，提供整体光带效果"""
3

4
    def __init__(self, parent=None):
5
        super().__init__(parent)
6
        self._shimmer_position = -100
7
        self._animation = None
8
        self._skeleton_items = []
9
        self._is_animating = False
10

11
    @pyqtProperty(float)
12
    def shimmer_position(self):
13
        return self._shimmer_position
14

15
    @shimmer_position.setter
16
    def shimmer_position(self, value):
17
        self._shimmer_position = value
18
        # 更新所有子骨架项的光带位置
19
        for item in self._skeleton_items:
20
            if hasattr(item, '_shimmer_position'):
21
                item._shimmer_position = value
22
                item.update()
23

24
    def add_skeleton_item(self, item):
25
        """添加骨架项到容器"""
26
        if isinstance(item, SkeletonBase):
27
            self._skeleton_items.append(item)
28
            # 停止子项的独立动画
29
            item.stop_animation()
30

31
    def start_animation(self):
32
        """开始整体光带动画"""
33
        if self._animation:
34
            self._animation.stop()
35

36
        self._animation = QPropertyAnimation(self, b"shimmer_position")
37
        self._animation.setDuration(1000)
38
        self._animation.setStartValue(-100)
39
        self._animation.setEndValue(self.width() + 100)
40
        self._animation.setLoopCount(-1)
41
        self._animation.start()
42
        self._is_animating = True
43

44
    def stop_animation(self):
45
        """停止整体光带动画"""
46
        if self._animation:
47
            self._animation.stop()
48
        self._is_animating = False
49

50
    def resizeEvent(self, event):
51
        super().resizeEvent(event)
52
        if self._is_animating:
53
            self.start_animation()

展开收起

这里使用 isinstance 进行类型检查，确保只有合法的骨架项才能被添加到容器中。同时，调用 item.stop_animation() 停止子项的独立动画，避免出现多个不同步的动画效果。

动画同步机制#

容器的关键功能是将自己的动画状态同步到所有子项：

1
@shimmer_position.setter
2
def shimmer_position(self, value):
3
    self._shimmer_position = value
4
    # 同步所有子项的动画位置
5
    for item in self._skeleton_items:
6
        if hasattr(item, '_shimmer_position'):
7
            item._shimmer_position = value
8
            item.update()
9
    self.update()

工厂模式的应用#

为了简化骨架项的创建过程，我们引入了工厂模式。 Skeleton 类提供了一系列静态方法来创建不同类型的骨架项：

1
class Skeleton:
2
    """骨架屏工厂类"""
3

4
    @staticmethod
5
    def create_item(width=100, height=20):
6
        """创建基础矩形骨架项"""
7
        return SkeletonItem(width, height)
8

9
    @staticmethod
10
    def create_rounded_item(width=100, height=20, radius=8):
11
        """创建圆角矩形骨架项"""
12
        return RoundedRectSkeletonItem(width, height, radius)
13

14
    @staticmethod
15
    def create_circle_item(diameter=40):
16
        """创建圆形骨架项"""
17
        return CircleSkeletonItem(diameter)
18

19
    @staticmethod
20
    def create_circle_persona(avatar_size=50):
21
        """创建圆形头像骨架"""
22
        return CirclePersonaSkeleton(avatar_size)
23

24
    @staticmethod
25
    def create_square_persona(avatar_size=50):
26
        """创建方形头像骨架"""
27
        return SquarePersonaSkeleton(avatar_size)
28

29
    @staticmethod
30
    def create_article():
31
        """创建文章骨架"""
32
        return ArticleSkeleton()

展开收起

预设组件的实现#

基于基础的骨架项和容器系统，我们可以创建一些常用的预设组件。以文章骨架为例：

1
class ArticleSkeleton(SkeletonContainer):
2
    def __init__(self, parent=None):
3
        super().__init__(parent)
4
        self._build_layout()
5

6
    def _build_layout(self):
7
        # 标题
8
        title = Skeleton.create_rectangle(300, 24)
9
        self.add_skeleton_item(title)
10

11
        # 间距
12
        self._layout.addSpacing(16)
13

14
        # 内容行
15
        for i in range(3):
16
            width = 400 if i < 2 else 250  # 最后一行较短
17
            line = Skeleton.create_rectangle(width, 16)
18
            self.add_skeleton_item(line)
19
            self._layout.addSpacing(8)

展开收起

预设组件继承了容器的所有功能，包括统一的动画效果，同时提供了特定场景下的便利性。

技术细节与优化#

在实现过程中，有几个技术细节值得特别注意。首先是动画的性能优化，使用 QPropertyAnimation 而不是定时器来驱动动画，这样可以利用 Qt 的硬件加速功能。其次是内存管理，通过合理的父子关系设置，确保组件能够正确地被垃圾回收。

另一个重要的优化是避免不必要的重绘。只有当 shimmer_position 发生变化时，才调用 update() 方法触发重绘。这样可以显著减少 CPU 使用率，特别是在有多个骨架屏同时运行的情况下。

总结#

通过合理的架构设计和细致的实现，创建了一个既易用又灵活的骨架屏系统。它不仅能够满足常见的使用场景，还为特殊需求提供了足够的扩展空间。

使用 PyQt 实现音乐歌单卡片交互效果：从布局到动画的完整解析

Sun, 20 Apr 2025 08:09:00 GMT

在音乐类应用中，歌单卡片的视觉效果和交互体验至关重要。本文将基于 PyQt 框架，详细讲解如何实现一个带有悬停动画、圆角裁剪、遮罩效果的音乐歌单组件，涵盖布局设计、图形绘制、动画实现等核心技术点。

一、效果演示#

最终实现的歌单卡片具备以下交互效果：

基础布局：由图片区域和描述区域组成，图片区域顶部圆角，描述区域底部圆角，整体形成「胶囊」状视觉效果。
悬停交互：
- 卡片向上轻微跳动，伴随弹性缓动动画。
- 半透明遮罩层渐显，覆盖整个卡片，中央出现播放按钮。
- 描述区域背景色根据图片主题色动态变化，增强视觉关联性。

具体效果如下：

二、布局构造：分层设计实现视觉结构#

核心组件 playlistCover 采用 三层嵌套布局，结构如下：

1. 根容器（QWidget）#

设置 WA_TranslucentBackground 属性实现透明背景，配合 FramelessWindowHint 去除边框。
使用 QVBoxLayout 垂直排列子组件，边距和间距均为 0，确保紧密贴合。

2. 内容层#

图片区域（RoundedLabel）：继承自 QLabel，实现顶部圆角裁剪（后文详细解析），固定尺寸 200x200，开启 scaledContents 自动缩放图片。
描述区域（QLabel）：固定高度 80px，设置 wordWrap 自动换行，通过样式表配置字体、颜色和底部圆角（border-bottom-left-radius/border-bottom-right-radius）。

3. 遮罩层（QWidget）#

初始隐藏，尺寸与内容层一致，覆盖图片和描述区域。
内部使用 QVBoxLayout 居中放置播放按钮（RoundToolButton），按钮图标为 Fluent Design 风格的播放图标。
通过 QGraphicsOpacityEffect 控制透明度，实现渐显 / 渐隐动画。

1
# 关键布局代码
2
self.layout = QVBoxLayout(self)
3
self.layout.addWidget(self.coverLabel)
4
self.layout.addWidget(self.despLabel)
5

6
self.mask_layer = QWidget(self)
7
self.mask_layout = QVBoxLayout(self.mask_layer)
8
self.mask_layout.addWidget(self.playButton)

三、圆角构造：图片与描述的视觉衔接#

1. 图片区域：顶部圆角裁剪（自定义绘制）#

通过子类化 QLabel 实现 RoundedLabel，重写 setPixmap 方法，使用 QPainterPath 裁剪图片顶部两角：

路径绘制逻辑

：
- 从底部左侧开始，绘制左侧边到顶部圆角起点。
- 使用 arcTo 绘制左上和右上圆角（半径可配置）。
- 连接右侧边到底部，形成仅顶部圆角的闭合路径。
抗锯齿优化：开启 QPainter.Antialiasing，确保边缘平滑。

1
# 圆角裁剪核心代码
2
def _rounded_top_corners(self, pixmap, radius):
3
    result = QPixmap(size)
4
    result.fill(Qt.transparent)
5
    painter = QPainter(result)
6
    painter.setRenderHint(QPainter.Antialiasing)
7

8
    path = QPainterPath()
9
    w, h = size.width(), size.height()
10
    path.moveTo(0, h)
11
    path.lineTo(0, radius)
12
    path.arcTo(0, 0, 2*radius, 2*radius, 180, -90)  # 左上圆角
13
    path.lineTo(w - radius, 0)
14
    path.arcTo(w - 2*radius, 0, 2*radius, 2*radius, 90, -90)  # 右上圆角
15
    path.lineTo(w, h)
16
    path.closeSubpath()
17

18
    painter.setClipPath(path)
19
    painter.drawPixmap(0, 0, pixmap)
20
    return result

展开收起

2. 描述区域：底部圆角（样式表实现）#

通过样式表直接配置底部两角圆角，与图片区域的顶部圆角形成对称：

1
QLabel#despLabel {
2
    background-color: rgb(r, g, b);  /* 动态主题色 */
3
    border-bottom-left-radius: 15px;
4
    border-bottom-right-radius: 15px;
5
}

四、遮罩原理：半透明层与视觉聚焦#

遮罩层本质是一个 半透明黑色背景的容器，作用是：

视觉分层：通过 rgba(0, 0, 0, 0.6) 背景色模糊下方内容，突出播放按钮。
交互区域：覆盖整个卡片，确保鼠标事件触发时响应区域足够大。
圆角一致性：通过样式表设置全角圆角（与描述区域底部圆角呼应），实现整体视觉统一：

1
QWidget#maskLayer {
2
    background-color: rgba(0, 0, 0, 0.6);
3
    border-radius: 15px;  /* 与描述区域底部圆角半径一致 建议初始化radius变量，方便维护*/
4
}

五、遮罩动画：渐显渐隐的平滑过渡#

使用 QPropertyAnimation 控制遮罩层的透明度，实现「鼠标进入时渐显，离开时渐隐」的效果：

进入动画：透明度从 0 到 1，持续 300ms，缓动曲线为 OutQuad（快进慢出）。
离开动画：透明度从 1 到 0，持续 300ms，缓动曲线为 InQuad（慢进快出）。
事件触发：在 enterEvent 和 leaveEvent 中启动动画，并控制遮罩层的显隐状态。

1
# 动画初始化
2
self.enter_animation = QPropertyAnimation(self.opacity_effect, b"opacity")
3
self.enter_animation.setDuration(300)
4
self.enter_animation.setStartValue(0.0)
5
self.enter_animation.setEndValue(1)
6

7
self.leave_animation = QPropertyAnimation(self.opacity_effect, b"opacity")
8
self.leave_animation.setDuration(300)
9
self.leave_animation.setStartValue(1)
10
self.leave_animation.setEndValue(0.0)
11

12
# 事件触发
13
def enterEvent(self, event):
14
    self.mask_layer.show()
15
    self.enter_animation.start()
16
    super().enterEvent(event)
17

18
def leaveEvent(self, event):
19
    self.leave_animation.start()
20
    super().leaveEvent(event)

展开收起

六、跳动动画：弹性位移增强交互反馈#

卡片悬停时的上下跳动通过 位置动画 实现，核心逻辑：

位移控制：定义 animation_offset 为 20px，鼠标进入时向上移动（pos - QPoint(0, offset)），离开时返回原始位置。
缓动曲线：使用 OutCubic 曲线（流畅的弹性效果），区别于线性动画的生硬感。
动画方向：通过 QAbstractAnimation.Forward 和 Backward 控制正向 / 反向动画，避免重复创建动画对象。

1
# 跳动动画关键代码
2
self.hover_animation = QPropertyAnimation(self, b"pos")
3
self.hover_animation.setDuration(300)
4
self.hover_animation.setEasingCurve(QEasingCurve.OutCubic)  # 推荐曲线
5

6
def enterEvent(self, event):
7
    start_pos = self.pos()
8
    end_pos = start_pos - QPoint(0, self.animation_offset)
9
    self.hover_animation.setStartValue(start_pos)
10
    self.hover_animation.setEndValue(end_pos)
11
    self.hover_animation.start()
12
    ...
13

14
def leaveEvent(self, event):
15
    current_pos = self.pos()
16
    self.hover_animation.setStartValue(current_pos)
17
    self.hover_animation.setEndValue(self.original_pos)
18
    self.hover_animation.start()
19
    ...

展开收起

七、细节优化：播放按钮与主题色适配#

1. 播放按钮设置#

使用 qfluentwidgetspro 中的 RoundToolButton，具备天然圆角和点击涟漪效果：

图标设置为 FluentIcon.PLAY，图标尺寸 20x20，按钮最小尺寸 60x60，确保触控友好。
布局上通过 QVBoxLayout 居中，实现遮罩层内的垂直水平居中。

2. 动态主题色#

通过 Theme_Color.getThemeColor 方法提取图片主色调，应用于描述区域背景色，增强视觉一致性：

1
self._themecolor = Theme_Color.getThemeColor(self._imagepath)
2
r, g, b = self._themecolor
3
self.despLabel.setStyleSheet(f"background-color: rgb({r},{g},{b});")

主题色的代码请参考：如何使用python提取图片主题色 | 怪兽马尔克

八、总结与扩展#

本文通过 PyQt 的自定义绘制、动画系统和样式表，实现了一个具备完整交互效果的音乐歌单卡片。核心技术点包括：

图形裁剪：使用 QPainterPath 实现非矩形区域绘制。
动画设计：组合透明度动画和位置动画，配合缓动曲线提升体验。
分层架构：通过多层容器分离视觉和交互逻辑，便于维护和扩展。

可扩展方向：#

响应式布局：支持卡片尺寸动态调整，适配不同屏幕分辨率。
触摸交互：添加点击事件处理（clicked 信号），跳转歌单详情页。
性能优化：使用缓存机制避免重复图片裁剪，或引入异步加载处理大图片。

通过合理运用 PyQt 的图形和动画模块，开发者可以轻松实现复杂的交互效果，为桌面应用赋予现代 UI 体验。完整代码已在文末提供，欢迎下载调试！

（注：本文代码基于 PyQt 5 和 qfluentwidgets 库，需提前安装依赖：pip install pyqt5 qfluentwidgets）

完整代码如下:

1
import os
2
import sys
3
from PyQt5.QtWidgets import QApplication, QMainWindow, QLabel, QWidget, QVBoxLayout, QHBoxLayout
4
from PyQt5.QtGui import QPixmap, QPainterPath, QPainter, QMouseEvent, QIcon
5
from PyQt5.QtCore import Qt, QPropertyAnimation, QEasingCurve, pyqtSignal, QSize, QAbstractAnimation, QPoint
6

7
from PyQt5.QtWidgets import QGraphicsOpacityEffect
8

9
from qfluentwidgets import FluentIcon, ToolButton
10

11
from NetEase.common.ThemeColor import Theme_Color
12

13
class RoundedLabel(QLabel):
14
    """
15
    QLabel subclass that rounds the top-left and top-right corners of the pixmap.
16
    """
17

18
    def __init__(self, parent=None, radius=10):
19
        super().__init__(parent)
20
        self._radius = radius
21
        self._original_pixmap = None
22

23
    @property
24
    def radius(self):
25
        return self._radius
26

27
    @radius.setter
28
    def radius(self, value):
29
        self._radius = value
30
        # reapply rounding if a pixmap is already set
31
        if self._original_pixmap:
32
            self.setPixmap(self._original_pixmap)
33

34
    def setPixmap(self, pixmap):
35
        """
36
        Overrides QLabel.setPixmap to apply rounding on the top corners.
37
        """
38
        if not isinstance(pixmap, QPixmap):
39
            super().setPixmap(pixmap)
40
            return
41

42
        self._original_pixmap = pixmap
43
        rounded = self._rounded_top_corners(pixmap, self._radius)
44
        super().setPixmap(rounded)
45

46
    def _rounded_top_corners(self, pixmap, radius):
47
        """
48
        Returns a new QPixmap with only the top-left and top-right
49
        corners rounded by the given radius.
50
        """
51
        size = pixmap.size()
52
        result = QPixmap(size)
53
        result.fill(Qt.transparent)
54

55
        painter = QPainter(result)
56
        painter.setRenderHint(QPainter.Antialiasing)
57

58
        # Build a path rounding only the top corners
59
        path = QPainterPath()
60
        w, h = size.width(), size.height()
61
        r = radius
62

63
        # Start from bottom-left, go counter-clockwise
64
        path.moveTo(0, h)
65
        path.lineTo(0, r)
66
        path.arcTo(0, 0, 2 * r, 2 * r, 180, -90)
67
        path.lineTo(w - r, 0)
68
        path.arcTo(w - 2 * r, 0, 2 * r, 2 * r, 90, -90)
69
        path.lineTo(w, h)
70
        path.closeSubpath()
71

72
        painter.setClipPath(path)
73
        painter.drawPixmap(0, 0, pixmap)
74
        painter.end()
75

76
        return result
77

78
class RoundedToolButton(ToolButton):
79

80
    def __init__(self, parent=None):
81
        super().__init__(parent)
82
        self.setStyleSheet("""
83
                ToolButton {
84
                    color: black;
85
                    border-radius: 30px;
86
                    background: transparent;
87
                    outline: none;
88
                }
89

90
                ToolButton:disabled {
91
                    color: rgba(0, 0, 0, 0.36);
92
                    background: rgba(249, 249, 249, 0.3);
93
                    border: 1px solid rgba(0, 0, 0, 0.06);
94
                    border-bottom: 1px solid rgba(0, 0, 0, 0.06);
95
                }
96
        """)
97
        self.normal_icon = QIcon()
98
        self.hover_icon = QIcon()
99

100
    def setIcon(self, icon):
101
        if isinstance(icon, str):
102
            # 处理图标路径字符串
103
            self.normal_icon = QIcon(icon)
104
            base, ext = os.path.splitext(icon)
105
            hover_path = f"{base}-hover{ext}"
106
            if os.path.exists(hover_path):
107
                self.hover_icon = QIcon(hover_path)
108
            else:
109
                self.hover_icon = self.normal_icon
110
        else:
111
            self.normal_icon = icon
112
            self.hover_icon = icon
113

114
        super().setIcon(self.normal_icon)
115

116
    def setHoverIcon(self, icon):
117
        self.hover_icon = icon
118

119
    def enterEvent(self, event):
120
        super().enterEvent(event)
121
        if not self.hover_icon.isNull():
122
            super().setIcon(self.hover_icon)
123

124
    def leaveEvent(self, event):
125
        super().leaveEvent(event)
126
        super().setIcon(self.normal_icon)
127

128
class playlistCover(QWidget):
129
    played = pyqtSignal()
130
    clicked = pyqtSignal()
131

132
    def __init__(self, image_path, parent=None):
133
        super().__init__(parent=parent)
134

135
        self._imagepath = image_path
136
        self.setAttribute(Qt.WA_TranslucentBackground)
137
        self.setWindowFlag(Qt.FramelessWindowHint)
138
        self.setCursor(Qt.PointingHandCursor)
139

140
        self.layout = QVBoxLayout(self)
141

142
        self.coverLabel = RoundedLabel(self)
143
        self.coverLabel.setObjectName("coverLabel")
144
        self.coverLabel.setMinimumSize(180, 180)
145
        self.coverLabel.setScaledContents(True)
146
        self.coverLabel.setPixmap(
147
            QPixmap(self._imagepath).scaled(180, 180, Qt.IgnoreAspectRatio, Qt.SmoothTransformation))
148

149
        self.despLabel = QLabel(self)
150
        self.despLabel.setObjectName("despLabel")
151
        self.despLabel.setText("你是我的单曲循环 我是你的随机播放")
152
        self.despLabel.setWordWrap(True)
153
        self.despLabel.setAlignment(Qt.AlignTop | Qt.AlignLeft)
154
        self.despLabel.setFixedHeight(60)
155

156
        self.layout.addWidget(self.coverLabel)
157
        self.layout.addWidget(self.despLabel)
158
        self.layout.setContentsMargins(0, 0, 0, 0)
159
        self.layout.setSpacing(0)
160
        self.setLayout(self.layout)
161

162
        self.mask_layer = QWidget(self)
163
        self.mask_layer.setObjectName("maskLayer")
164
        self.mask_layer.resize(self.coverLabel.width(), self.coverLabel.height() + self.despLabel.height())
165
        self.mask_layer.setVisible(False)
166

167
        self.listenCountLabel = QLabel(self)
168
        self.listenCountLabel.setObjectName("listenCountLabel")
169
        self.listenCountLabel.setText("🎧️ 167.6万")
170
        self.listenCountLabel.move(self.coverLabel.width() - 90, self.coverLabel.y() + 10)
171

172
        self.mask_layout = QVBoxLayout(self.mask_layer)
173
        self.mask_layout.setAlignment(Qt.AlignCenter)
174
        self.playButton = RoundedToolButton(self.mask_layer)
175
        self.playButton.setIcon("./resource/play.svg")
176
        self.playButton.setMinimumSize(60, 60)
177
        self.playButton.setIconSize(QSize(60, 60))
178
        self.mask_layout.addWidget(self.playButton)
179

180
        self.opacity_effect = QGraphicsOpacityEffect(self.mask_layer)
181
        self.mask_layer.setGraphicsEffect(self.opacity_effect)
182
        self.mask_layer.move(self.x(), self.y())
183

184
        self._themecolor = Theme_Color.getThemeColor(self._imagepath)
185
        r, g, b = self._themecolor
186
        self.setStyleSheet(f"""
187
                        QWidget#maskLayer {{
188
                            background-color: rgba(0, 0, 0, 0.4);
189
                            border-radius: 15px;
190
                        }}
191
                        QLabel#despLabel {{
192
                            background-color: rgb({r},{g},{b});
193
                            font-family: Microsoft YaHei;
194
                            font-size: 15px;
195
                            color: #ffffff;
196
                            padding-top: 5px;
197
                            padding-left: 5px;
198
                            padding-right: 5px;
199
                            border-bottom-left-radius: 15px;  /* 左下角圆角 */
200
                            border-bottom-right-radius: 15px; /* 右下角圆角 */
201
                        }}
202
                        QLabel#listenCountLabel {{
203
                            background-color: transparent;
204
                            font-family: Microsoft YaHei;
205
                            font-size: 15px;
206
                            font-weight: bold;
207
                            color: #ffffff;
208
                        }}
209
                        """)
210

211
        self.enter_animation = QPropertyAnimation(self.opacity_effect, b"opacity")
212
        self.enter_animation.setDuration(300)
213
        self.enter_animation.setStartValue(0.0)
214
        self.enter_animation.setEndValue(1)
215
        self.enter_animation.setEasingCurve(QEasingCurve.OutQuad)
216

217
        self.leave_animation = QPropertyAnimation(self.opacity_effect, b"opacity")
218
        self.leave_animation.setDuration(300)
219
        self.leave_animation.setStartValue(1)
220
        self.leave_animation.setEndValue(0.0)
221
        self.leave_animation.setEasingCurve(QEasingCurve.InQuad)
222

223
        self.animation_offset = 20
224
        self.original_pos = self.pos()
225

226
        self.pos_animation = QPropertyAnimation(self, b"pos")
227
        self.pos_animation.setDuration(300)
228
        # self.pos_animation.setEasingCurve(QEasingCurve.OutBack)         # 回弹效果
229
        self.pos_animation.setEasingCurve(QEasingCurve.OutBounce)  # 弹跳效果
230
        self.__connectSignalToSlot()
231

232
    def __connectSignalToSlot(self):
233
        self.playButton.clicked.connect(lambda: self.played.emit())
234

235
    def resizeEvent(self, event):
236
        super().resizeEvent(event)
237
        self.mask_layer.setGeometry(
238
            self.coverLabel.x(),
239
            self.coverLabel.y(),
240
            self.coverLabel.width(),
241
            self.coverLabel.height() + self.despLabel.height()
242
        )
243
        self.listenCountLabel.move(self.coverLabel.width() - 90, self.coverLabel.y() + 10)
244

245
    def mousePressEvent(self, event: QMouseEvent):
246
        self.clicked.emit()
247
        super().mousePressEvent(event)
248

249
    def enterEvent(self, event):
250
        self.original_pos = self.pos()
251

252
        # 上升动画
253
        self.pos_animation.stop()
254
        start = self.original_pos
255
        end = start - QPoint(0, self.animation_offset)
256
        self.pos_animation.setStartValue(start)
257
        self.pos_animation.setEndValue(end)
258
        self.pos_animation.start()
259

260
        self.enter_animation.start()
261
        self.mask_layer.show()
262
        self.listenCountLabel.hide()
263
        super().enterEvent(event)
264

265
    def leaveEvent(self, event):
266
        current = self.pos()
267
        self.pos_animation.stop()
268
        self.pos_animation.setStartValue(current)
269
        self.pos_animation.setEndValue(self.original_pos)
270
        self.pos_animation.start()
271

272
        self.leave_animation.start()
273
        self.listenCountLabel.show()
274
        super().leaveEvent(event)
275

276
    def moveEvent(self, event):
277
        # 当组件被移动时更新原始位置
278
        if self.pos_animation.state() == QAbstractAnimation.Stopped:
279
            self.original_pos = self.pos()
280
        super().moveEvent(event)
281

282
class MainWindow(QMainWindow):
283
    def __init__(self):
284
        super().__init__()
285
        self.init_ui()
286

287
    def init_ui(self):
288
        central_widget = QWidget()
289
        self.setCentralWidget(central_widget)
290
        layout = QHBoxLayout(central_widget)
291
        layout.setContentsMargins(10, 10, 10, 10)
292
        layout.setSpacing(20)
293

294
        # 创建带图片的标签
295
        image_label = playlistCover("./resource/test.jpg")
296
        image_label_2 = playlistCover("./resource/test2.jpg")
297
        image_label_3 = playlistCover("./resource/test3.jpg")
298
        image_label_4 = playlistCover("./resource/test4.jpg")
299

300
        layout.addWidget(image_label)
301
        layout.addWidget(image_label_2)
302
        layout.addWidget(image_label_3)
303
        layout.addWidget(image_label_4)
304
        layout.setAlignment(Qt.AlignCenter)
305

306
if __name__ == "__main__":
307
    QApplication.setHighDpiScaleFactorRoundingPolicy(
308
        Qt.HighDpiScaleFactorRoundingPolicy.PassThrough)
309
    QApplication.setAttribute(Qt.AA_EnableHighDpiScaling)
310
    QApplication.setAttribute(Qt.AA_UseHighDpiPixmaps)
311
    app = QApplication(sys.argv)
312
    window = MainWindow()
313
    window.show()
314
    sys.exit(app.exec_())

展开收起

使用PyQt实现国际化功能--完整版

Fri, 11 Apr 2025 15:43:00 GMT

许久没有更新了。在这篇博客文章中，将介绍如何使用 PyQt 内置的国际化机制实现应用程序的多语言支持。整个过程主要分为以下几个部分：

项目环境及国际化简介
配置项目文件（.pro）
在代码中使用 tr() 函数
使用外部工具 lupdate 和 lrelease 提取和生成翻译文件
使用 Qt Linguist 进行翻译

1. 项目环境及国际化简介#

首先需要确保你已经安装了 PyQt 和 Qt Linguist 工具包。PyQt 提供了内置的国际化支持功能，主要通过 tr() 函数来标记需要翻译的文本。

环境要求：

Python 3.x
PyQt5 或 PySide6
Qt 开发工具（其中包含 Qt Linguist、lupdate、lrelease 等工具）

2. 配置项目文件 (.pro)#

在 Qt 项目中，使用 .pro 文件可以定义翻译相关的配置。在这里，你需要在 .pro 文件中添加 TRANSLATIONS 变量来声明翻译文件（通常为 .ts 文件）。当然命名方式可以为你的项目名称加上.pro的后缀即可。

示例 .pro 文件内容：

1
SOURCES += NetEasePlayer.py \
2
           view/SettingInterface.py \
3

4
TRANSLATIONS += resource/i18n/NetEasePlayer.zh_CN.ts \
5
        resource/i18n/NetEasePlayer.zh_HK.ts

3. 在代码中使用 `tr()` 函数#

在你的 PyQt 应用中，所有需要翻译的字符串都应该通过

self.tr()

函数来包裹。对于 Python 项目，通常在类中调用 self.tr("需要翻译的内容")。

1
from PyQt5.QtWidgets import QLabel
2

3
class MainWindow(QtWidgets.QMainWindow):
4
    def __init__(self):
5
        super(MainWindow, self).__init__()
6
        self.setWindowTitle(self.tr("我的国际化程序"))
7
        self.label = QLabel(self.tr("欢迎使用国际化功能"))
8
        self.setCentralWidget(label)
9

10
if __name__ == '__main__':
11
    import sys
12
    app = QtWidgets.QApplication(sys.argv)
13
    window = MainWindow()
14
    window.show()
15
    sys.exit(app.exec_())

展开收起

4. 使用外部工具 lupdate 和 lrelease#

Qt 提供两个外部工具用于国际化流程：

**

lupdate

**：扫描项目代码和 .pro 文件，提取 tr() 函数标记的所有待翻译文本，并生成或更新 .ts 文件。
**

lrelease

**：将 .ts 文件编译成二进制的 .qm 文件，供运行时加载使用。

当翻译内容已经被self.tr()包裹后，可以调用lupdate程序先根据.pro文件设置的项目代码路径进行扫描提取需要翻译的文本内容，接着会在TRANSLATIONS中设置的路径生成对应需要的语言版本，上述实例中给出了翻译为简体中文和繁体中文的路径。lrelease的使用后面继续讲。接下来讲解如何在Pycharm或者其他IDE中配置外部工具lupdate,方便我们的使用。

4.1. 配置外部工具#

首先需要找到安装的PyQt中的可执行文件pylupdate5.exe，此文件一般位于你的conda目录的虚拟环境中，可以配合Everything搜索一下。配置的方式按照我给的配图中设置即可。使用方法即是对.pro文件进行调用即可。

pERQvQS.md.png

同理可以找到在该目录中的lrelease.exe,配置方法截图给上。但是这个外部工具的调用需要等我们对翻译文件使用Qt Linguist 进行翻译之后再调用的。因此暂时不着急介绍使用的步骤位置。

pERlpZj.md.png

配置好这些之后，找到linguist.exe，这个文件是QT的翻译程序，如果找不到可以先到网上下载。

5. 使用 Qt Linguist 进行翻译#

Qt Linguist

是 Qt 提供的图形化翻译工具，可以方便地对 .ts 文件中的内容进行翻译。启动 Qt Linguist 后，打开生成的 .ts 文件，依次翻译其中的字符串，然后保存。

使用 Qt Linguist 的步骤说明：

打开 Qt Linguist 应用程序。

通过“文件”菜单打开刚才生成的 .ts 文件（例如：translations/myapp_zh_CN.ts）。

在主界面中选择待翻译的条目，输入翻译内容。这里是需要自己配置翻译的内容的，因为不同的英文名称在不同领域的翻译不同，因此需要自己配置翻译。只需要对识别到的翻译内容一一翻译后选择勾选已经翻译即可。

保存翻译后，关闭 Qt Linguist。

示例截图：

pERllJx.md.png

完成翻译后，记得使用 lrelease 工具将更新后的 .ts 文件转换为 .qm 文件，以便在运行时加载使用。这就需要用到刚配置好的lrelease 外部工具进行更新。更新后的目录如下。

pERlQF1.png

这一切配置好之后就可以在代码层面实现翻译功能了。

1
if __name__ == '__main__':
2
    QApplication.setHighDpiScaleFactorRoundingPolicy(
3
        Qt.HighDpiScaleFactorRoundingPolicy.PassThrough)
4
    QApplication.setAttribute(Qt.AA_EnableHighDpiScaling)
5
    QApplication.setAttribute(Qt.AA_UseHighDpiPixmaps)
6

7
    app = QApplication(sys.argv)
8
    locale = cfg.get(cfg.language).value
9
    translator = FluentTranslator(locale)
10
    NetEaseTranslator = QTranslator()
11
    NetEaseTranslator.load(locale, "NetEasePlayer", ".", "./resource/i18n")
12

13
    app.installTranslator(translator)
14
    app.installTranslator(NetEaseTranslator)
15
    demo = Window()
16
    demo.show()
17
    sys.exit(app.exec_())

展开收起

这段代码展示了如何在 PyQt 应用中实现国际化支持，尤其是结合了 QFluentWidgets 的翻译组件。通过读取用户配置中的语言设置，将当前的语言环境赋值给 locale 变量。这个步骤非常关键，因为根据不同的语言环境，后续加载相应语言的翻译文件，保证应用的界面文字能够按照用户的偏好显示。

接着实例化两个翻译器对象：一个是由 QFluentWidgets 提供的 FluentTranslator，另一个是 Qt 自带的 QTranslator。使用QFluentWidgets 的翻译器来处理其内置组件的翻译，而应用自身的翻译则通过 QTranslator 对象来加载。，通过调用其 load 方法，将指定目录下根据当前语言环境命名的翻译文件加载进来。这样做确保了无论是第三方组件还是应用自定义部分，所有文本均能够被正确翻译。通过调用 app.installTranslator 方法，先后将 QFluentWidgets 的翻译器和应用自身的翻译器添加到应用中。安装翻译器后，所有通过 tr() 标记的文本在显示时都会查找相应的翻译文件，根据当前语言环境显示出不同的语言。这样设计的原因在于使得国际化工作透明而高效，不需要在代码的其他部分反复调整，仅仅通过翻译文件的切换即可改变程序的显示语言。

这里不再展示如何将用户的偏好设置加入到界面中，有多种设计思路，这里就交给读者自由发挥了。