FluentRead 字幕菜单状态同步修复:X 播放器控制栏卸载后的菜单独立刷新实现
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 只是按钮自身的渲染条件,不应成为菜单刷新链路的前置条件。
三、修复方案:菜单独立刷新,按钮属性按需更新
修复思路分为两层:
- 菜单状态独立刷新:
updatePlayerUiState()改为在取得menu节点后立即继续执行菜单渲染逻辑(模式单选状态、AI 状态、字幕校时、本地化文本、下载反馈、布局同步),不再依赖按钮在场。按钮的aria-pressed、aria-expanded等属性更新放在条件判断中,仅在按钮确实存在时才写入,避免对已卸载节点做无效操作。 - 入口按钮按需重建:X 控制栏重挂载后,播放器绑定层会重新注入按钮,按钮初始状态由
updatePlayerUiState()再次同步,读取的是最新配置,从而"旧状态清除"。
修复后的行为在报告中描述为:
修改后按钮恢复为"生成 AI 字幕",旧状态清除。
四、修复前后对比
以下对比截图来自本次修复报告目录 docs/reports/video-menu-state-20260913/,展示关闭 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 项相关测试能够稳定覆盖该回归的前提。

