# 练习页顶栏六项功能(/app/game) - 页面:`https://www.tanqudao.com/app/game` - 课节:Lesson 1 Morning Wake-Up(`c-mn15edqe-qirc12` / `l-mn15jfdn-ikcigx`),当前为**拼图模式**(`listening` + 拆句 `split`) - 捕获:2026-10-10 23:48–23:54(UTC+8),视口约 1356×799 - 顶栏布局见 `-app-game.md`;本节只补六项顶栏能力的复刻细节 --- ## 1. 设置 ### 入口与壳层 - **位置**:顶栏右侧胶囊区,文案 **「设置」**(`button`,与「切换模式」「学习内容」等同排) - **形态**:居中弹层 `van-popup app-settings-popup`(`role` 无 dialog,内含标题 **「设置」**、右上角 **关闭**) - **默认 Tab**:**音效**(与 `GET /api/settings/display` 的 `defaultOpen: "sound"` 一致) - **Tab 可见性**:`display.visibility` 中 `pronunciation/sound/quiz/hotkeys` 均为 `true`(`listening`、`personal` 为配置项,**不在**本弹层内;「个性化」为独立顶栏按钮) - **恢复默认**:Tab 栏右侧 **「恢复默认」**,仅重置**当前 Tab** 的偏好 ### Tab:发音 | 控件 | 类型 | 本次值 | 可选/范围 | 改变后 | |---|---|---|---|---| | 切题后自动朗读(副文案:继续练习,题目切换时自动朗读) | switch | 开 | 开/关 | 切题是否自动 TTS | | 答题正确后朗读(副文案:答题成功后自动朗读) | switch | 开 | 开/关 | 答对是否自动 TTS | | 朗读次数 | − / +(只读 slider 展示) | **1 次** | 步进调节 | TTS 重复次数 | | 朗读间隔 | − / + | **1 秒** | 步进调节 | 多次朗读间隔 | | 发音人语速 | − / + | **1.0x** | 步进调节 | 语速 | | 发音人音量 | − / + | **100** | 步进调节 | 音量 | - **持久化**:`__APP_PRONUNCIATION_PREFS__`(JSON 字符串,见 `-api-auth-settings.md`) - **模式**:四种模式均影响朗读行为;打字模式同样受「切题/答对朗读」约束 ### Tab:音效 每组 **开关 + 「默认」音效下拉 + 音量滑条(0–100,step 1)+ 试听按钮(喇叭图标)**: | 分组标题 | 开关默认 | 音效 | 音量 | |---|---|---|---| | 打字音效 | 开 | 默认(可选变体,数据来自 `GET /api/sound-effects`) | 100 | | 手动切题音效 | 开 | 默认 | 100 | | 答题正确音效 | 开 | 默认 | 100 | | 答题错误音效 | 开 | 默认 | 100 | | 课程完成音效 | 开 | 默认 | 100 | - **持久化**:`__APP_SOUND_EFFECT_PREFS__`(键名 `typing/nav/correct/wrong/complete`,每项 `enabled/pick/volume`) - **模式关联**:「打字音效」主要在 **typing**;其余在 **listening / dictation / c2e / typing** 切题、判题、完课均可能触发 ### Tab:答题 | 控件 | 类型 | 本次值 | 可选 | 持久化字段(推断) | |---|---|---|---|---| | 答题正确后自动下一题 | switch | **关** | 开/关 | `autoAdvanceOnCorrect` → `__APP_PRACTICE_UI_PREFS__` | | 正确自动跳格 | switch | **关** | 开/关 | 听写/中译英多格输入 | | 切换模式重头开始 | switch | **开** | 开/关 | `restartOnModeSwitch: true` | | 答案弹窗自动显示 | switch | **关** | 开/关 | `__APP_QUIZ_ANSWER_PREFS__` | | 错误几次时显示答案 | 下拉 | **错误 3 次后** | 从不 / 错误 1–5 次后 | 同上 | - **关闭弹层**:偏好立即 `POST /api/auth/settings` 写回(与周期性心跳写回并存) ### Tab:快捷键 - 顶部说明:**不能**用单个字母;**不能**用 Shift+字母/字符等系统组合 - 可编辑项(每项 **编辑** 按钮): | 功能 | 默认绑定 | |---|---| | 播放朗读 | Ctrl + A | | 标记不熟悉 | Ctrl + Q | | 显示答案 | ↓ / ↑ | | 再来一次 | Ctrl + ; | - **持久化**:`__APP_GAME_HOTKEY_PREFS__` - **模式**:listening / dictation / c2e / typing 共用;听写/中译英/typing 另有页内 Enter、空格等(见 `-app-game.md` 底栏),不在此 Tab 改键 ### 相关接口 | 接口 | 作用 | |---|---| | `GET /api/settings/display` | Tab 默认与可见性 | | `GET /api/sound-effects` | 音效列表 | | `GET/POST /api/auth/settings` | 读写各 `__APP_*_PREFS__` | ### 状态保留 关闭弹层后设置保留(账号级 + 本地缓存);刷新练习页仍生效。 --- ## 2. 学习内容 ### 入口 - 顶栏 **「学习内容」** 按钮(`studyContentEnabled: true`,见 `-api-settings-menu-display.md`) ### 本次是否弹出 - **已弹出**居中弹层 `van-popup content-popup`(`role="dialog"`,`aria-label="学习内容"`) - 上次未看到弹层:本次在已登录、Lesson 1、拼图模式下点击即出现;**点击后未新增 fetch**(用进页已拉的课节数据渲染) ### 界面结构 - **标题栏**:「学习内容」+ **关闭** - **列表** `role="listbox"`「内容列表」:可滚动,每项为按钮 - 英文整句 `content-item-en` - 中文 `content-item-zh` - 序号 `# N`(本课 **17** 条,对应整句/card 级条目) - 左侧色条 `--content-hue` 按序号渐变(纯视觉) - **无**弹层内配图、无独立音频控件(朗读仍走练习页 TTS/题内音频) ### 交互 - 点击某条(如 `# 2 Get out of bed.`):**关闭弹层**,练习区跳到该句对应题目(词块变为 Get / out / of / bed) - 不改变 `mode`(仍为 listening) ### 数据来源 / 接口 | 接口 | 说明 | |---|---| | `GET /api/lesson-sheet?courseId&lessonId&practice=split` | 行级词/句/翻译/IPA/图/音频;弹层列表为其中**整句/card 聚合**展示 | | `GET /api/settings/menu-display` | `studyContentButtonFreeLessonLimit: 6` 等门禁配置(本课未触发会员挡板) | 课文正文结构见 `-api-lesson-sheet.md`(列字段 + 1 条样例行);弹层样例: ```json { "index": 2, "en": "Get out of bed.", "zh": "从床上起来。" } ``` ### 模式与保留 - **listening / dictation / c2e**(拆句)均可用;**typing**(整句 17 题)同样显示 17 条整句列表 - 关闭后仅保留跳转后的题号(`POST /api/practice/progress`),弹层本身无状态 --- ## 3. 个性化 ### 入口 - 顶栏 **「个性化」**(与「设置」分离,非设置 Tab) ### 界面 居中弹层 `personal-popup`,标题 **「个性化」**;右上 **恢复默认** + **关闭** 1. **颜色**(每组:色块下拉 + **默认** 重置按钮) - 输入答案字体颜色(当前 `#4162ff`) - 练习页面字体颜色(当前 `#ffffff`) - 练习页面背景颜色(当前 `#0b0d10`) - 答案卡片背景颜色(当前 `#1e1e1e`) 2. **答题正确特效**:开关(开)+ 方案下拉(**默认 / 特效1 / 特效2 / 特效3 / 特效4**)+ **预览特效** + 提示「(如感觉卡顿,可关闭)」 3. **输入区字体大小**:单选 **最小 / 略小 / 默认 / 略大 / 偏大 / 最大** 4. **结果字体大小**:同上六档 ### 观测到的保存行为 - 打开时 **`GET /api/settings/personal`**(默认 px、特效 profile 等,见 `-api-settings-personal.md`) - 改「输入区字体大小 → 略大」→ **`POST /api/auth/settings`**,`__APP_QUIZ_FONT_PRESET__`: `"large"`;改回「默认」→ 该键写回 `""` - 颜色/特效等键:`__APP_QUIZ_COLOR_PREFS__`、`__APP_QUIZ_CORRECT_FX_PREFS__`、`__APP_QUIZ_ANSWER_CARD_BRIGHTNESS__`、`__APP_QUIZ_FONT_PRESET__`(完整键表 `-api-auth-settings.md`) ### 页面变化 - 字体档位:答题区/结果区字号即时变化(数值来自 personal 接口的 `quizFontSize*` / `quizResultFontSize*`) - 颜色/背景:CSS 变量级覆盖练习页 - 特效:答对时粒子动画(profileId 与 `quizCorrectFxProfiles` 对应) ### 模式 四种练习模式**共用**同一套外观;typing 仍受「输入区/结果字体」影响 ### 状态保留 关闭面板后保留;跨设备依赖账号 `POST /api/auth/settings` --- ## 4. 重置进度 ### 入口 - 顶栏 **「重置进度」** ### 确认框 - 居中小弹层 `reset-card` - 正文:**「确定要重置吗?」**(无更细说明) - 按钮:**取消** | **确认** - 本次 **未点确认**(避免清空用户进度) ### 范围(从 UI 推断) - 按钮文案为「重置进度」,确认框未提设置/账号;结合 `-api-practice-progress.md`,推断为**当前课节**练习进度(题号、可能含模式进度),**不**含设置/个性化/音效等偏好 - 捕获期间**无** `/api/.../reset` 专用路径;确认后预期仍走 **`/api/practice/progress`** 一类写入(待确认执行时再抓包) ### 模式 对当前课节的 listening / dictation / c2e / typing 均入口可见(同一确认框) ### 取消 点 **取消** 关闭弹层,进度不变 --- ## 5. 沉浸模式 ### 入口 - 顶栏 **「沉浸模式」**(图标胶囊 `pill-immersive`) ### 进入后 UI - 顶栏 **隐藏**(DOM 仍在,`visible: false`):设置、切换模式、学习内容、重置进度、个性化、报错、沉浸模式、**显示图片** switch、**拆句/整句** 胶囊、练习计时等 - **保留/收缩**: - 左:**返回** - 右:**退出沉浸模式**(原沉浸按钮变为激活态)、**全屏** - 标题行仍显示课节与题号(如 `Lesson 1… (2/17)`) - 底栏变为 **沉浸模式操作栏** `immersive-dock`(`role="contentinfo"`): - 顶部细 **进度条** `immersive-progress` - 四按钮:**上一题 | 朗读 | 答案 | 下一题**(无快捷键文案、无「不熟悉/再来一次」) - 主练习区(配图、中文提示、词块/输入)布局居中放大,左右留白增加 ### 技术状态 - **`localStorage.__APP_GAME_IMMERSIVE_MODE__`**:`"1"` 开启,退出为 `null`(非 `"0"`) - 切换时**无**独立沉浸接口;仅见周期性 `GET/POST /api/auth/settings`(与其它心跳相同) - 根节点 class:`shell immersive`、`practice is-immersive-mode` 等 ### 退出 点 **退出沉浸模式** → 顶栏与完整底栏快捷键提示恢复;**localStorage** 清掉沉浸标记 ### 与模式关系 listening / dictation / c2e / typing 均可进沉浸;交互简化为 dock 四键(朗读/答案/切题仍可用) --- ## 6. 全屏 ### 入口 - 顶栏 **「全屏」**(`pill pill-fullscreen`);沉浸模式下仍在右上,与「退出沉浸模式」并列 ### 行为(观测 + 自动化限制) - 设计意图:调用浏览器 **Fullscreen API**(`document.documentElement.requestFullscreen()`) - 自动化环境点击后 `document.fullscreenElement` 仍为 `false`,脚本直调返回 `Permissions check failed`(无用户手势) - **无** `localStorage` 全屏标记(与沉浸不同) - 进入全屏后按钮文案/aria 预期切换为「退出全屏」(本次未能在自动化中验证) ### 与沉浸模式差别 | | 沉浸模式 | 全屏 | |---|---|---| | 本质 | 页内 CSS/布局 + 隐藏顶栏多项 | 浏览器 全屏元素 | | 持久化 | `localStorage.__APP_GAME_IMMERSIVE_MODE__` | 无(随 ESC/浏览器退出) | | 顶栏 | 精简为 返回 + 退出沉浸 + 全屏 | 全屏时浏览器隐藏地址栏等 | | 底栏 | 沉浸 dock 四键 | 非沉浸时为完整快捷键底栏 | | 接口 | 无专用 API | 无专用 API | 二者可叠加(沉浸模式下仍可点全屏)。 ### 状态保留 退出全屏不改动练习进度与设置;沉浸状态独立保留。 --- ## 文件与接口索引 - 本文:`task/tanqu分析/-app-game-顶栏功能.md` - 新增接口文件:`-api-settings-personal.md` - 调用顺序追加:`00-调用顺序.md`「顶栏六项补录」 - 个性化 POST 示例:追加在 `-api-auth-settings.md`(不覆盖原有 GET/练习页写入)