xsl/feifei
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
feifei/开发文档-第1关.md
T
Feast 3237386e00 init
2026-10-13 20:40:09 +08:00

11 KiB
Raw Permalink Blame History

第 1 关开发文档：1-1 左手基准键 ASDF

对应规划：分关难度规划.md → 第 1 章 · 基准键入门 → 1-1。
本文只覆盖第 1 关的实现范围，作为后续关卡的模板。第 1 关同时要搭好练习页的通用骨架，后关复用，不重做。

1. 目标

让完全新手在不看键盘的情况下，用正确指法打出左手四个基准键：

键 手指
A 左手小指
S 左手无名指
D 左手中指
F 左手食指

本关不考速度，只考正确率和指法习惯。
通关条件：正确率 ≥ 90%（无速度门槛）。

2. 范围

2.1 本关要做

  • 关卡选择页中，1-1 默认解锁，可进入
  • 练习页：待打文本、实时对错着色、键盘指法图、实时数据条
  • 约 40 个目标键，字符集仅 a s d f（小写）
  • 击键判定、正确率、键/分、进度
  • 结束结算：通过 / 未通过，可重打
  • 通过后解锁 1-2
  • 记录本关历史最好正确率（本地存储）

2.2 本关不做

  • 右手键 j k l ;、空格、大写、数字、符号
  • 速度门槛、限时模式
  • 中文拼音、单词、文章
  • 热力图统计（可先预留数据结构，本关不展示）
  • 账号 / 云同步

3. 页面与信息架构

建议单页 HTML，用视图切换，不必多文件路由。

启动
 └─ 关卡选择（第 1 章四关列表）
      └─ 练习中（1-1）
           └─ 结算弹层
                ├─ 再打一次 → 回到练习中（重新抽题）
                └─ 返回选关 → 关卡选择

3.1 关卡选择页（本关相关）

元素 说明
章标题 第 1 章 · 基准键入门
关卡卡片 1-1 标题「左手基准键 ASDF」；状态：已解锁 / 已通关
关卡卡片 1-2～1-4 未通关 1-1 前置灰，不可点
最佳成绩 若打过 1-1，显示历史最高正确率

3.2 练习页布局（自上而下）

  1. 顶栏：关卡名「1-1 左手基准键」、返回选关
  2. 数据条：进度 已打/总数、正确率、速度（键/分）、用时
  3. 文本区：一行待打字符，当前目标键放大/下划线，已打正确为绿、错误为红
  4. 键盘区：QWERTY 示意图，强制显示；当前目标键高亮；四指提示
  5. 提示文案：「食指放在 F，小指放在 A，不要看键盘」

结算用遮罩弹层盖在练习页上，不跳新页。

4. 关卡配置

实现时用一份配置驱动，后关只改配置、少改逻辑。

{
  id: "1-1",
  chapter: 1,
  title: "左手基准键 ASDF",
  charset: ["a", "s", "d", "f"],
  length: 40,
  allowSpace: false,
  caseSensitive: false,          // 本关只产生小写；Shift+A 视为错误
  passAccuracy: 0.90,
  passKpm: null,                 // 本关不卡速度
  unlockNext: "1-2",
  showKeyboard: true,            // 强制显示，不可关
  generate: "random-from-charset"
}

4.1 题目生成规则

  • 从 charset 均匀随机抽取 length 个字符，连成一串，例如：asdfafsdasfd...
  • 不要出现空格、换行
  • 建议约束：同一字符连续不超过 3 次（避免 aaaa 失去指法切换训练）
  • 每次进入或「再打一次」都重新生成，不固定题库

4.2 允许输入

按键 行为
a s d f 有效击键，进入对错判定
其他字母 / 数字 / 符号 记为一次错误击键，不前进光标（卡住当前目标，直到打对）
Shift / CapsLock 产生的 A 等 视为错误（本关只认小写）
Backspace 忽略，本关不允许改错（对标金山打字通初级指法：打错就记错，必须打对当前键才继续）
Enter Tab Esc 忽略，不计入对错
Alt Meta Ctrl 组合 忽略

采用「必须打对才前进」：错了标红提示，光标停在当前目标，直到按下正确键。
正确率分母按「总击键次数（含错键）」计算，而不是按「已完成字符数」。见第 6 节。

5. 指法与键盘 UI

5.1 手指映射（本关只用左手）

键 手指 建议高亮色
A 小指 橙
S 无名指 黄
D 中指 绿
F 食指 蓝

其余键绘制出来但呈禁用态（降低透明度），避免误导用户去打。

5.2 键盘交互

  • 当前目标键：描边 + 放大/脉冲
  • 按下正确键：该键闪绿后熄灭，切到下一目标
  • 按下错误键：目标键闪红，可加轻微震动（CSS）
  • 键盘图下方固定文案：
    「左手：小指 A · 无名指 S · 中指 D · 食指 F」

5.3 文本区表现

假设目标串为 asdf，用户先打对 a s，第三个该打 d 却打了 f：

[a] [s] [d] [f]
 绿   绿   当前(红闪)  灰
  • 已正确：绿色
  • 当前目标：深色底 + 下划线；若刚打错则红框
  • 未打到：灰色
  • 不把错误字符插入文本（文本始终是标准答案，只改颜色/状态）

6. 判定与统计

从第一次有效击键开始计时（a/s/d/f 或其他会记错的可见字符）。纯功能键不开始计时。

6.1 字段

字段 定义
targetLength 40
cursor 当前待打下标，0～40；到 40 结束
correctHits 打对次数（每前进一格 +1，最大 40）
wrongHits 打错次数（每次错误按键 +1，可大于 40）
totalHits correctHits + wrongHits
elapsedMs 从首次有效击键到结束（或当前）的毫秒

6.2 公式

正确率 accuracy = correctHits / totalHits
进度 percent   = cursor / targetLength
速度 kpm       = correctHits / (elapsedMs / 60000)
用时 time      = elapsedMs

展示：

  • 正确率：百分数，保留 1 位小数，如 92.5%
  • 速度：整数「键/分」，未开始时显示 --
  • 进度：12 / 40 + 进度条
  • 用时：mm:ss

6.3 通关判定（结束时一次性算）

passed = accuracy >= 0.90

本关 passKpm 为空，不判断速度。
totalHits 为 0 时（理论上不会结束）正确率按 0。

6.4 结束时机

cursor === targetLength 立即结束，弹出结算。不再接收击键。

7. 结算

7.1 展示

项 说明
结果标题 「通关」或「未通关」
正确率 实际值，并标明门槛「≥ 90%」
速度 键/分（仅展示，不影响通关）
用时 mm:ss
击键 正确 / 错误 / 总计
操作 「再打一次」「返回选关」

通关时额外一行：「已解锁 1-2 右手基准键」。

7.2 进度写入

使用 localStorage，键名建议：typing-progress-v1。

{
  unlocked: ["1-1", "1-2"],     // 通关 1-1 后写入 1-2
  records: {
    "1-1": {
      bestAccuracy: 0.95,
      bestKpm: 62,
      passed: true,
      lastPlayedAt: "2026-08-13T15:30:00+08:00"
    }
  }
}

规则：

  • 初始 unlocked 含 1-1
  • 通关才把 unlockNext 加入 unlocked
  • bestAccuracy / bestKpm 只升不降
  • 未通关也写入 lastPlayedAt 和当前成绩，但不把 passed 从 true 改回 false
  • 重打失败不锁回 1-2

8. 状态机

idle        进入练习页，题目已生成，等待第一击
playing     已开始计时，接收击键
finished    40 键打完，弹出结算，忽略击键

转移：

  • idle → playing：第一次有效/错误可见击键
  • playing → finished：cursor 达到 40
  • finished → idle：点「再打一次」（新题、清零统计）
  • 任意 → 选关：点返回（练习中途返回不保存通关，可选择是否写入 lastPlayedAt；本关规定：中途退出不记成绩）

9. 技术约定

项 约定
形态 单文件或「HTML + CSS + JS」，先保证双击即可打开
输入 window 上 keydown；用 event.key 判定字符
防干扰 练习中 preventDefault 掉会滚动/选中的键；不要用隐藏 <input> 抢焦点（避免 IME）
本关 IME 不需要中文输入；若系统处于中文输入法，提示「请切换到英文」
样式 深色背景、大字号文本区，适合全屏练习
兼容 现代桌面 Chrome / Edge / Safari；本关按物理键盘设计，不做触屏键盘

9.1 建议模块划分（同一文件内亦可）

  1. config：关卡配置
  2. progress：读写 localStorage
  3. generator：按 charset 生成题目
  4. engine：状态机、击键、统计
  5. keyboardView：键盘高亮
  6. textView：文本着色
  7. hud：数据条
  8. resultModal：结算
  9. stageSelect：选关

第 1 关实现时就把 1～8 做成可复用，选关先只列第 1 章四关。

10. 文案

位置 文案
选关卡片标题 1-1 左手基准键
选关卡片副标 只打 A S D F，正确率 90% 即可通关
练习顶栏 第 1 关 · 左手基准键 ASDF
指法提示 食指放 F，小指放 A。请看着屏幕，不要看键盘。
通关 通关！基准键已经记住了。
未通关 再练一次。先求正确，再求速度。
输入法提示 请切换到英文输入法后再开始。

11. 验收标准

  • 打开页面即可进入 1-1，无需登录
  • 题目长度为 40，仅含 a s d f，无空格
  • 同一字符连续不超过 3 次
  • 打对前进一格，打错不前进并记一次错误
  • Backspace 不影响进度与统计
  • 正确率按 正确 / (正确+错误) 计算，≥ 90% 判定通关
  • 无速度门槛；结算仍显示键/分
  • 键盘图始终显示，当前键高亮，非 ASDF 键呈禁用态
  • 通关后 1-2 可点；未通关 1-2 仍锁
  • 刷新页面后解锁状态仍在
  • 中途返回选关不记本局成绩
  • 「再打一次」重新抽题并清零

12. 测试用例

编号 操作 期望
T1 40 次全对 正确率 100%，通关，解锁 1-2
T2 打对 36、打错 4（错键后补对） 总击键 44，正确率 ≈ 81.8%，未通关
T3 打对 36、打错 4 之外再算：正确 36 / 总击键 40 注意：因打错不前进，40 个正确键必须打满；未通关局 correctHits 仍为 40，wrongHits > 0。例如错 5 次则正确率 = 40/45 ≈ 88.9%，未通关
T4 正确率刚好 90%（40 对 + 约 4.44 错不可整除） 用 40 对 + 5 错 = 88.9% 未过；40 对 + 4 错 = 90.9% 通过。门槛按 >= 0.90
T5 练习中按 Backspace、方向键 无效果
T6 打 g 或其他非 charset 键 错误 +1，光标不动
T7 通关后刷新 1-2 仍解锁
T8 通关后再打失败 1-2 保持解锁
T9 第一键前等待 速度显示 --，用时 00:00
T10 中途点返回 无结算、不改 best、不解锁

正确率要点（务必实现一致）：
本关结束时 correctHits 恒为 40。通关只取决于错了多少次：

accuracy = 40 / (40 + wrongHits)
90% 通关  ⇒  40 / (40 + wrongHits) >= 0.90  ⇒  wrongHits <= 4

即：全程最多允许打错 4 次。

13. 后续关卡复用说明

第 1 关落地后，1-2 只需改配置：

项 1-1 1-2（预告，不在本文实现）
charset a s d f j k l ;
手指 左手四指 右手四指
通关 正确率 ≥ 90% 同 1-1
键盘禁用态 非 ASDF 非 JKL;

不要为 1-2 另写一套引擎。

Reference in New Issue View Git Blame Copy Permalink