FluentRead 字幕菜单状态同步修复:X 播放器控制栏卸载后的菜单独立刷新实现

原创2026-09-26 11:22:492,255 阅读
文章标签:前端国际化人工智能大模型本地部署语音

FluentRead 字幕菜单状态同步修复:X 播放器控制栏卸载后的菜单独立刷新实现

导读

本文记录 FluentRead(开源双语翻译浏览器插件)针对 X(Twitter)视频播放器的一处状态同步缺陷完成的修复:当播放器卸载原生控制栏时,已打开的字幕菜单必须脱离入口按钮独立刷新,否则会出现"点击已生效、界面仍显示旧状态"的假死现象。文章完整还原问题复现路径、根因定位、修复方案与源码实现,并给出基于 Playwright 的生产扩展回归测试复测方法,可直接用于同类"宿主卸载 UI 锚点"场景的排查与验证。

一、问题背景:控制栏卸载后菜单状态"假死"

在 X 播放器页面,FluentRead 会在播放器内注入字幕入口按钮与字幕菜单。X 是单页应用(SPA),播放器控制栏由前端框架动态渲染,在收起控制栏、切换视频或全屏切换等场景下,原生控制栏节点会被卸载后重新挂载。

此前实现存在一个前提假设:菜单刷新时要求入口按钮仍在 DOM 中。该假设在控制栏被卸载的场景下被打破——用户点击菜单项后,配置已经生效(例如关闭了 AI 字幕),但菜单上的开关、显示模式与 AI 状态仍然渲染旧值,形成"功能已生效、界面未同步"的状态。

原报告给出的稳定复现路径如下:

关闭 AI 后字幕消失,按钮仍为 aria-checked=true,文字仍是"关闭 AI 字幕 / 已就绪"。

即用户关闭 AI 字幕成功,字幕层已移除,但入口按钮与菜单仍展示 AI 字幕"已就绪"的开启状态。

二、根因定位:菜单刷新错误依赖入口按钮在场

修复对应的核心逻辑位于 src/features/video-subtitle/content/runtime.ts 的 updatePlayerUiState() 函数。该函数是菜单 UI 的同步入口,负责按钮、显示模式、字幕校时行、AI 字幕状态与本地化文本的整体刷新。

关键问题出在刷新路径上:刷新开始时先通过 buttonElement 或 document.getElementById 获取入口按钮,随后在更新菜单之前就 return 退出。X 控制栏收起后入口按钮被卸载,getElementById 取不到按钮,菜单的后续刷新语句被一并跳过——于是"开关、模式与 AI 状态仍显示旧值"。

源码中的修复注释(runtime.ts)精确描述了这一约束的破坏点:

X 控制栏收起后入口按钮会卸载,但已打开的菜单仍可操作;菜单状态不能依赖入口按钮在场,否则功能已生效却仍显示旧状态。

也就是说:菜单是用户当前正在交互的对象,其状态必须始终跟随真实配置刷新;入口按钮是否存在于 DOM 只是按钮自身的渲染条件,不应成为菜单刷新链路的前置条件。

三、修复方案:菜单独立刷新,按钮属性按需更新

修复思路分为两层:

  1. 菜单状态独立刷新:updatePlayerUiState() 改为在取得 menu 节点后立即继续执行菜单渲染逻辑(模式单选状态、AI 状态、字幕校时、本地化文本、下载反馈、布局同步),不再依赖按钮在场。按钮的 aria-pressed、aria-expanded 等属性更新放在条件判断中,仅在按钮确实存在时才写入,避免对已卸载节点做无效操作。
  2. 入口按钮按需重建:X 控制栏重挂载后,播放器绑定层会重新注入按钮,按钮初始状态由 updatePlayerUiState() 再次同步,读取的是最新配置,从而"旧状态清除"。

修复后的行为在报告中描述为:

修改后按钮恢复为"生成 AI 字幕",旧状态清除。

四、修复前后对比

以下对比截图来自本次修复报告目录 docs/reports/video-menu-state-20260913/,展示关闭 AI 字幕时菜单与按钮的状态差异:

修改前 修改后
关闭 AI 后菜单仍显示旧状态 关闭 AI 后菜单立即更新
  • 修改前:AI 字幕开关按钮文字为"关闭 AI 字幕",状态区显示"已就绪",aria-checked=true——与"字幕已消失"的实际状态矛盾;
  • 修改后:按钮文字恢复为"生成 AI 字幕",状态区清空,aria-checked=false——菜单与真实字幕显示状态一致。

五、菜单状态机与源码级实现

字幕菜单的完整构建与渲染位于 src/features/video-subtitle/content/playerMenu.ts,它只操作 FluentRead 自己的菜单节点,不读取存储、不发起识别、不绑定全局事件,运行时(runtime.ts)负责配置、请求与清理——菜单与业务解耦后,独立刷新才成为可能。

5.1 AI 字幕按钮的状态机

renderVideoAiMenu() 根据 VideoAiMenuState 计算按钮文案与状态,其分支决定 aria-checked 与文字:

  • available=false → video.aiUnavailable("AI 字幕不可用");
  • downloading → video.aiDownloadingModel(模型下载中);
  • checking → video.aiCheckingModel(检查模型中);
  • ready(fullActive && phase==='ready')→ video.aiDisable,即"关闭 AI 字幕",同时状态区显示"已就绪";
  • processing → video.aiStop;
  • 存在 error → video.aiRetry("重试生成 AI 字幕");
  • 其余情况 → video.aiGenerate("生成 AI 字幕")。

这正是复现截图里出现"关闭 AI 字幕 / 已就绪"的来源:fullActive 与 phase 停在 ready,说明识别已完成且状态未因关闭而被清除。修复后关闭动作会停止完整生成(stopFullAiSubtitleGeneration())、清空 AI 字幕队列并重置阶段,renderVideoAiMenu 下一次刷新自然回到"生成 AI 字幕"。

5.2 显示模式与字幕时间行

菜单的显示方式(双语 / 仅译文 / 仅原文 / 关闭)由 renderVideoMenuMode() 渲染,VideoMenuMode 类型为 VideoSubtitleDisplayMode | 'off',四种选项共享一个单选语义(role="menuitemradio" + aria-checked)。selectMenuMode() 处理点击:off 时关闭 videoTranslationEnabled 并停止 AI 采集;选择任一显示方式时同步 videoSubtitleDisplayMode,并在字幕被隐藏(videoSubtitleVisible===false)时一并恢复可见——"弹出式菜单不再单独提供显示字幕开关;选择任一显示方式即恢复可见"。

字幕时间行(renderVideoSubtitleTiming())只在存在时间轴或已有偏移时显示,步进为 ±0.5 秒、限幅 ±10 秒,重置按钮仅在偏移非零时出现且不移动连续点击中的步进按钮。

5.3 入口按钮的挂载与恢复

播放器绑定层位于 src/features/video-subtitle/content/videoPlayerBinding.ts:以画中画与全屏控件为锚点维护入口顺序,并处理信息流、全屏及原生控件重挂载时的稳定性。控制栏重挂载后绑定层重新注入按钮,updatePlayerUiState() 再按最新配置同步其状态,因此重挂载不会带来旧状态回显——回归测试中专门验证了"控制栏重挂载保留菜单节点与状态"。

六、验证体系:91 项测试 + 浏览器回归报告

修复验证分两层,报告原文归纳如下:

  • 单元 / 集成测试:91 项相关测试通过,覆盖菜单、本地化、播放器绑定、字幕显示、完整识别生命周期与缓存客户端;
  • 工程检查:源文件注释与模块边界检查通过;测试归类审计通过;TypeScript/Vue 检查、Chrome 和 Firefox 生产构建、文档构建全部通过;
  • 浏览器回归:完整执行"关闭/恢复 AI、连续隐藏/显示、三种模式、翻译开关、跨页面配置同步、AI 说明展开、重新识别错误反馈、两类字幕下载、设置入口、控制栏重挂载和 Esc"等场景,结果记录在 浏览器报告(success: true,errors: [])。

6.1 浏览器回归环境与方法

为排除用户日常浏览器配置与真实站点的干扰,回归采用完全隔离的自动化环境:

  • 临时 profile、macos-background-cdp 启动模式、launchservices-no-foreground 焦点策略,正常尺寸窗口置于第二屏,browserFrontmost=false(避免抢走前台焦点,报告中的 frontmostBefore/frontmostAfter 均保持原前台应用);
  • 加载生产构建扩展,配合 X DOM 夹具页面(内含 videoPlayer、原生控制栏按钮、画中画与全屏控件);
  • 预置字幕缓存(向后台写入固定 cue)与固定翻译响应(拦截 Edge 翻译接口返回固定文本),不运行真实语音识别;
  • 重新识别环节通过 CDP 在扩展隔离世界内伪造一次模型查询失败,用于验证错误反馈与重试路径。

报告明确标注其边界:"这些结果验证菜单与字幕显示状态,不代表真实 X 页面或 Whisper 识别质量验证",且"未借鉴参考仓库"。

6.2 回归覆盖的关键断言

从测试脚本 scripts/run-video-menu-state-test.cjs 可以看到完整覆盖点:

  • 按钮定位:播放器宽度 960/572/360/320px 下,入口按钮固定在画中画与全屏按钮之间且不越出视频边界;宿主移位、宿主删除图标、控制栏整体替换、全屏进出后均能恢复;
  • 关闭 AI:移除控制栏后菜单仍可点击,aria-checked 立即翻转为 false,按钮文字回到"生成 AI 字幕",状态区清空,字幕层消失;
  • 显示模式:双语/仅译文/仅原文/关闭四段切换保持单选,字幕层 class 同步切换,"关闭"同时收起时间行;
  • 跨页面配置同步:在 popup 中修改 videoSubtitleVisible/videoSubtitleDisplayMode 后,已打开的菜单立即反映;
  • 模型确认流程:首次生成先在菜单内确认模型与大小(约 100 MB / 约 150 MB),取消可返回,确认后下载失败给出单行错误且不跳转设置页;缓存命中时直接恢复 AI 字幕,不弹出模型确认;
  • 下载:原文、译文、双语三类 SRT 下载正常,双语文件把原文与译文放在同一 cue 的两行里;
  • 同语言跳过翻译:识别结果已是目标语言(如繁体中文 → 简体中文)时不请求翻译服务,双语只显示原文一行,仅译文模式仍显示该句(脚本通过统计 fixtureTranslationCalls 断言调用次数不变);
  • 重挂载与关闭:控制栏重挂载保留菜单节点与状态,Esc 先退模型确认视图、再关菜单;设置入口打开视频设置页;
  • 菜单布局:手机横屏播放器使用矮行双列(wide),竖屏与桌面保持单列(stack),菜单不滚动、不越出播放器。

七、复测方法:运行生产扩展回归脚本

复测入口为 scripts/run-video-menu-state-test.cjs,需要显式传入四个参数:

node scripts/run-video-menu-state-test.cjs \
  --extension-dir .output/chrome-mv3 \
  --playwright-root <playwright 运行时根目录> \
  --focus-safe-helper <focus-safe helper 模块路径> \
  --artifacts-dir <报告与截图输出目录>

参数说明:

  • --extension-dir:生产扩展构建目录,默认 .output/chrome-mv3;
  • --playwright-root:测试通过 createRequire 加载 Playwright 运行时的根目录(脚本内以 video-menu-proof.cjs 解析);
  • --focus-safe-helper:用于启动"不抢占前台焦点"浏览器会话的辅助模块(必填,缺失即报错);
  • --artifacts-dir:输出 report.json、菜单截图(before-close-ai.png 等)与 SRT 下载样例的目录,默认 /private/tmp/fluentread-video-menu-state。

此外支持可选的 --browser-path(默认 /Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge)与 --ffmpeg(默认 /opt/homebrew/bin/ffmpeg,用于生成 960×540 的测试视频夹具)。

脚本默认使用后台隔离的 Edge,临时 profile 创建于系统临时目录,测试结束后自动清理并写出 report.json,不会连接日常浏览器配置,也不会触发真实语音识别或真实翻译请求(翻译由 service worker 内替换的 fetch 返回固定响应)。

八、结论与同类场景借鉴

本次修复的核心结论可以提炼为一条可复用的工程原则:UI 弹层的状态刷新链路不能把"触发入口节点的在场"作为前置条件。当宿主页面(X 播放器控制栏等)可能动态卸载其原生节点时,已打开且可继续交互的浮层必须直接从权威配置源刷新,入口节点的属性更新只作为浮层刷新的附属操作。

对 FluentRead 而言,这一修复同时受益于既有的模块边界设计:菜单构建(playerMenu.ts)与业务编排(runtime.ts)分离,使菜单能够在不依赖按钮在场的前提下独立重绘;而按钮的重建与恢复由绑定层(videoPlayerBinding.ts)负责,三者的职责边界清晰,也是 91 项相关测试能够稳定覆盖该回归的前提。

登录后查看全文
FluentRead