Skip to content

统一媒体预览 ​

组成 ​

渲染层的 MediaPreview 负责媒体列表、加载、失败恢复、缩放与共用操作; MediaPreviewShell 负责标题栏、浮层占用、焦点、Esc 与移动端返回。 图片 OCR 独立在 usePreviewOcr 中,仍使用聊天图片上下文和原有识别服务。

普通图片、视频、空间和群相册、资料图片、历史头像、发送前视频共用这一实现。 商城表情只复用外壳,保留整包网格、单张详情、解密参数及分级 Esc。 聊天内联视频、通话、动态背景和装扮缩略图不改成浮层播放器。

PreviewMedia 使用稳定 key,包含图片/视频类型、显示来源、封面、回退地址、 可选原图加载器、保存来源及 OCR 上下文。显示来源和保存来源独立:例如相册显示预览图时, 保存仍指向原图;只有封面的视频按图片保存,不将封面交给视频播放器。 浏览器 Blob 只借用到预览结束,不把跨进程无效的 Blob 地址提交给保存服务。

mediaPreviewStore 按所属文档保存命令式预览;同一文档的新预览替换旧预览, 不同窗口互不替换。受控预览也参与同一文档的占用管理。 所有命令式入口直接使用 openMediaPreview({ items, ownerDocument?, onClose? }), 应用仅挂载一个 MediaPreviewHost,不再保留分图片/视频的组件、打开函数或宿主筛选。 单项预览也使用媒体项数组,保存来源由统一入口准备;业务提供的保存来源仍优先。

交互 ​

  • 顶部显示标题、加载范围内计数和关闭;底部统一缩放、保存、图片复制及可用的 OCR。 相册管理、媒体评论、历史头像日期等放入独立业务操作区,不重复提供保存按钮。
  • 原比例时左右方向键切项,放大后方向键平移;输入框、菜单、OCR 文本区和原生播放器 保留自己的按键。多项预览左右空白切项,不循环;单项点击空白关闭。
  • 视频保留原生播放、进度、音量和全屏控件,并支持画面缩放和平移。 拖动处理避开播放器下沿控件区域。鼠标操作原生控件后归还预览焦点,Tab 进入时保留焦点。
  • Esc 只处理最上层表面;保存提示等业务浮层允许位于预览上方。 关闭后归还触发焦点,换视频或关闭时暂停旧播放器。
  • 发送前预览跟随所属聊天标签页隐藏,隐藏时暂停,不撤销仍被附件或预览使用的 Blob。

聊天媒体数据源 ​

ChatMediaGallery 在消息列表级组织媒体,不从 DOM 收集,因此不受虚拟列表挂载范围限制。 聊天图片和普通视频按消息与元素顺序混排;视频封面继续用于内联播放,另设放大入口, 进入浮层前暂停内联播放器。动画表情、商城表情、圆形视频不混入序列,闪照沿用独立入口。 合并转发以当前记录独立成组,不递归混入嵌套记录。

普通聊天使用当前会话范围,搜索记录携带当前发送者、关键词、类别和日期条件。 新媒体实时追加,不抢当前项和缩放;来源身份使用既有时间线身份,媒体位置附加元素序号, 不能按 URL 去重,也不能把消息 ID 当数据库行号。

account.mediaPreviewPage 校验账号与数据源身份,接收会话、过滤条件、锚点和方向, 使用既有 (msgSeq, sendTime, msgId) 游标分别读取本地表与已有离线漫游缓存。 每个来源最多读取 300 条原始消息,先按时间线规则合并、去重并截断窗口,再筛媒体, 未返回的原始消息由后续游标继续读取。它不联网补拉漫游历史,不计算精确总数。 没有数据库历史分页能力的列表仍浏览其已加载消息。

聊天预览通过 prefetchAdjacent 在接近已加载范围首尾时提前准备相邻媒体,不切换当前项, 也不等待查询才显示当前图片或视频。首尾箭头只在实际存在相邻项时启用;尚在查询或已到头 时置灰,方向键与空白点击同样不触发越界提示。新媒体追加或历史媒体补入后重新按当前项 位置判断,原先置灰的箭头自动恢复可用。

空媒体批次不等于结束:聊天预览沿游标自动继续查找,其他分页来源保留继续入口; 读取错误在当前位置重试,聊天的后台重试仍不切换当前项。 关闭或切换账号后停止客户端分页,迟到的媒体、分页与 OCR 结果不能回写到新的预览。

视频原片加载 ​

聊天视频优先读取 QQ 本地原片及已有完整缓存。缺失时由宿主现签原片地址,将播放器的 Range/If-Range 转发给来源,按真实的 200/206/416 响应流式传回,不要求先下载 整片;保留分段位置与总长,让播放器可读取尾部索引及拖动进度。网络请求沿用宿主网络栈和 省流量策略,预览缓存与 Web/Remote 媒体传输不登记任务;主动保存仍走原有保存任务。

覆盖完整文件且有明确长度的响应,在读取完毕、长度与视频格式核对后才原子发布缓存。 局部分段、断流和取消均不发布完整缓存,临时分段及时清理;缓存不可写不阻断播放。 关闭或换项导致的流取消会停止上游;Web/Remote 在响应头前断连同样传递取消信号。 首字节与正文停滞分别计时,不使用覆盖整段播放的总时限。

回归入口 ​

  • apps/desktop/test/video_preview_response.test.ts 与 media_protocol_video.test.ts:首段提前返回、 范围透传、完整缓存、取消与来源切换、错误及停滞,不产生预览任务。

  • apps/desktop/test/video_preview_web.test.ts 与 browser/run-video-preview-streaming.mjs: Web 断连取消、真实 Chromium 慢速起播与尾部索引 MP4 拖动;浏览器用例按环境变量启用。

  • apps/desktop/test/unified_media_preview.test.ts:混排、消息渲染入口、实时追加、分页、账号切换、 商城外壳、旧事件与 OCR 请求失效。

  • packages/service/test/media_preview_page.test.ts:真实明文 SQLite、本地双向游标、同时间同序号、 稀疏批次、筛选、会话隔离与离线缓存合并。

  • apps/desktop/test/browser/run-media-preview.mjs:桌面与 390/320px 窄屏、深浅主题、OCR、 重试、混排、空白切项、评论按键隔离、实时追加及商城表情。

  • apps/desktop/test/browser/run-qzone-native-controls.mjs:真实 Chromium 原生控件点击, 覆盖放大后的播放、拖动进度、静音,以及 Esc 和键盘焦点。

浏览器脚本使用已有 Playwright 与 Chromium,可通过 WEQ_PLAYWRIGHT_IMPORT、 WEQ_BROWSER_EXECUTABLE 指定路径;WEQ_MEDIA_PREVIEW_ARTIFACTS 指定截图目录。 夹具不访问真实 QQ 数据,脚本退出时关闭自身浏览器和临时服务。

当前文档对应 v2.7.4 · 已发布内容以 CHANGELOG 为准