跳转至

MCQ 互动题目模式配置指南

状态: ✅ 已完成

创建日期: 2026-03-16 最后更新: 2026-03-16

本文档说明 wiki MCQ 互动题目系统（javascripts/mcq-interactive.js）支持的两种模式及其配置方法。

两种模式对比

功能 练习模式（默认） 考试模式
触发方式 无需任何标记 页面中加入 <!-- exam-mode -->
选择后反馈 立即显示 ✅/❌ + 解析 不显示，仅高亮选中项（蓝色）
修改答案 不可修改（选后锁定） 可随时修改
顺序 随机打乱 固定顺序（与 Markdown 源文件一致）
分数显示 实时更新（右上角） 交卷后一次性显示
右侧导航 标准 TOC 题号导航网格（灰/蓝/绿/红）
提交按钮 无 底部"提交考试 / Submit Exam"
API 数据 每题选择后上报 每次选/改答案上报；交卷时上报总分
离线支持 有（localStorage 队列） 有（同一队列）

练习模式（Practice Mode）

配置方式

无需任何配置，所有 MCQ 页面默认启用练习模式。只需在 Markdown 中按标准格式写题目即可。

题目格式

**Q1.** 题目文字

(A) 选项A
(B) 选项B
(C) 选项C
(D) 选项D

**Answer: (B)**

> 可选：解析文字（blockquote 格式）

关键规则： - 答案行格式：**Answer: (X)**，其中 X 为 A/B/C/D 之一 - 解析用 > blockquote（可省略） - 题目之间用 --- 分隔

题组标记（可选）

用于将多道题绑定为一组（例如共享同一段材料），打乱顺序时保持组内整体移动：

<!-- group -->

**Q3.** 基于上图，题目文字

(A) ...
(B) ...
(C) ...
(D) ...

**Answer: (C)**

**Q4.** 同组第二题（与 Q3 共享材料）

(A) ...
...

**Answer: (A)**

<!-- /group -->

规则： - <!-- group --> 和 <!-- /group --> 必须成对出现 - 组内题目在打乱时整体移动，组内顺序不变 - 不需要分组时无需添加

考试模式（Exam Mode）

配置方式

在 Markdown 文件的题目内容区域中加入隐藏的 div 标记：

<div id="exam-mode" style="display:none"></div>

注意： 不能使用 HTML 注释（<!-- exam-mode -->），因为 MkDocs 构建时会把注释去掉。必须用 <div> 元素。

推荐位置： 文档头部元数据之后、第一道题之前：

# Chemistry 12 — U4 Practice Exam MCQ

> 状态: ✅ 已完成
> 创建日期: 2026-03-14

---

<div id="exam-mode" style="display:none"></div>

**Q1.** 题目文字
...

重要： 标记必须放在正文（.md-content）中，不能放在 YAML front matter 里。

考试模式行为

  1. 加载时： 不打乱顺序，不显示实时分数，右侧 TOC 替换为题号导航网格
  2. 作答时： 选项显示蓝色边框高亮，可点击其他选项修改答案，对应题号变蓝
  3. 提交前： 有未答题时弹出确认对话框（有 N 道题未作答，确认交卷？）
  4. 提交后： 显示每题 ✅/❌、正确答案、解析；题号变绿/红；显示总分；提交按钮禁用

题号导航网格颜色

颜色 含义
灰色 未作答
蓝色 已选择（未提交）
绿色 正确（提交后）
红色 错误或未作答（提交后）

实现原理

触发检测

detectExamMode() 函数在 initMCQ() 初始化时运行，查找 document.getElementById('exam-mode') 元素。如果存在则设置 isExamMode = true。

initMCQ()
├── 处理题目（wrapInCard，含 data-correct 和 data-selected 属性）
├── detectExamMode()
├── if (isExamMode):
│   ├── addSubmitButton(N)     — 底部交卷按钮
│   └── buildQuestionNav(N)    — 右侧题号导航
└── else:
    ├── addScoreTracker(N)      — 实时计分器
    └── shuffleQuiz()           — 打乱题目顺序

SPA 导航兼容

MkDocs Material 使用 instant navigation（SPA 模式）。每次页面切换时： - isExamMode 重置为 false - resetExamModeUI() 清理上一页的题号导航、恢复 TOC、断开 IntersectionObserver - initMCQ() 在新页面重新检测模式并初始化

数据上报（API）

事件 type 触发时机 extra 字段
每次选/改答案 quiz_answer 立即 { qNum, correct, selected, isCorrect: null }
交卷 quiz 提交时 { correct, total, pct }
练习模式每题 quiz_answer 立即 { qNum, correct, selected, isCorrect: true/false }
练习模式最后一题 quiz 最后一题后 { correct, total, pct }

离线时自动存入 localStorage('wiki_stats_offline_queue')，网络恢复后自动上报。

Stats 页面（/stats）

访问 https://wiki.itsail.net/stats?token=TOKEN 查看数据。

筛选

页面顶部有类型筛选按钮：All | visit | quiz | quiz_answer

  • 筛选器通过 URL 参数保持，分页时不丢失：?token=TOKEN&type=quiz
  • quiz 可查看所有交卷记录（总分）
  • quiz_answer 可查看每道题的答题记录

排序

点击表头可按该列排序（再次点击切换升/降序）：

列 排序方式
id 数字升/降
type 字母
url 字母
time 时间戳数字
score 文本

相关文件

文件 说明
javascripts/mcq-interactive.js MCQ 核心逻辑（练习 + 考试双模式）
stylesheets/custom.css MCQ 样式（含深色模式）
functions/stats.js Stats 页面（含筛选/排序）
functions/api/stats.js 数据接收 API（POST /api/stats）

快速参考

启用考试模式： 在 Markdown 正文中加一行 <div id="exam-mode" style="display:none"></div>

启用题组（练习模式）： 

<!-- group -->
（一组题）
<!-- /group -->

题目答案格式（两种模式均适用）： 

**Answer: (B)**