shiyi-math-practice

面向中国大陆一年级小学生的数学练习网站，参考北师大版小学数学一年级教材（2024 版）的学习主题设计。项目使用 Vite + React + TypeScript 构建，题库和练习记录都保存在本地，适合孩子每天在电脑或平板浏览器中进行短时间算术练习。

这是一个家庭自用的学习辅助项目，不是官方教材配套平台，也不包含教材原文复制内容。

项目背景

本项目最初为一年级小朋友李安岚设计。她正处在从“会算”到“能独立读题、理解题意、稳定完成练习”的阶段，因此网站重点不是做复杂教育系统，而是提供一个温暖、清晰、可反复使用的本地练习环境。

项目内容围绕中国大陆小学一年级数学学习场景展开，参考北师大版小学数学一年级教材（2024 版）的常见主题，包括 20 以内加减法、100 以内数的认识、大小比较、人民币、找规律、观察物体、有趣的图形和解决问题等。

适用对象

• 主要使用者：中国大陆一年级小学生，尤其适合 6 到 7 岁儿童。
• 辅助使用者：家长，可以查看练习记录、带孩子复盘错题，也可以继续扩展题库。
• 使用场景：每日 10 题、专项巩固、错题再练、纸质错题打印。

设计原则

• 简单稳定：纯前端本地运行，不依赖后端、数据库或登录系统。
• 儿童友好：字体大、按钮大、每次只显示一道题，减少干扰。
• 温和反馈：答错时提示“我们再想一想”，避免挫败感。
• 及时复盘：答错即进入错题本，避免反复蒙答案。
• 可继续扩展：题库集中在本地 TypeScript 文件中，便于后续添加新题。
• 隐私安全：练习记录和错题只保存在当前浏览器的 localStorage 中，不上传服务器。

在线访问

如果 GitHub Pages 已启用，可以访问：

https://jackli01030.github.io/shiyi-math-practice/

也可以按下面的方式在本地运行。

安装和运行

npm install
npm run dev

开发服务器启动后，浏览器打开终端里显示的本地地址，一般是 http://localhost:5173。

可用命令

npm run dev        # 启动本地开发页面
npm run typecheck  # 检查 TypeScript
npm run build      # 构建生产版本

GitHub Pages 部署

推送到 main 分支后，GitHub Actions 会自动运行类型检查和静态构建，并发布到 GitHub Pages。

首次使用时，在 GitHub 仓库的 Settings -> Pages 中，将 Build and deployment 的 Source 设为 GitHub Actions。部署完成后访问：

https://jackli01030.github.io/shiyi-math-practice/

这个项目是纯前端静态站点，错题和练习记录仍然只保存在浏览器 localStorage。

功能概览

• 首页：显示“李安岚的数学练习乐园”，提供每日练习、专项练习、错题再练入口。
• 每日练习：从本地题库中抽取 10 道题，覆盖教材常见单元：加与减、生活中的数、观察物体、有趣的图形、人民币、找规律和解决问题。
• 专项练习：可以选择 20以内加法、20以内减法、100以内数的认识、大小比较、100以内简单加减、人民币、找规律、观察物体、有趣的图形、解决问题。
• 错题再练：练习中需要再想一想的题会保存到浏览器 localStorage，答对后会标记为已掌握。
• 错题打印：错题页可以导出 PDF 或打印纸质错题练习纸。
• 练习记录：首页显示最近几次练习的小记录，方便爸爸查看。
• 答题反馈：答对会出现大烟花和兔子庆祝，答错会出现落叶提示。
• 图形题：部分题目会在文字题干上方显示苹果、硬币、图形、物体等图形区。
• 拼音辅助：题干、选项、图形说明和反馈里的汉字会显示带声调拼音。

题库规模

当前题库在 src/data/questions.ts 中按北师大版一年级数学（2024 版）常见学习主题本地整理和生成，共 442 道题，其中 168 道带图形区。

题型数量：

• 20以内加法：45 道
• 20以内减法：45 道
• 100以内数的认识：47 道
• 大小比较：54 道
• 100以内简单加减：66 道
• 人民币：35 道
• 找规律：40 道
• 观察物体：25 道
• 有趣的图形：40 道
• 解决问题：45 道

另外加入了 1 页“数的运算专项质量达标”测试卷题目，共 27 道，已拆分到对应题型中。

项目结构

src/
  components/      # 通用组件，比如顶部栏、分类卡片、答题组件
  pages/           # 首页、每日练习、专项练习、错题再练页面
  data/            # 本地题库
  utils/           # 抽题、计时格式、localStorage 工具
  types/           # TypeScript 类型
  App.tsx
  main.tsx

添加题目

题目都在 src/data/questions.ts。每道题使用下面的结构：

{
  id: "add-001",
  type: "20以内加法",
  question: "8 + 7 = ?",
  options: ["13", "14", "15", "16"],
  answer: "15",
  explanation: "8 加 7，可以先凑成 10，再接着数 5 个，就是 15。"
}

图形题可以额外加 visual 字段：

{
  id: "shape-001",
  type: "有趣的图形",
  question: "图中有几个三角形？",
  options: ["1", "2", "3", "4"],
  answer: "3",
  explanation: "先找到所有三角形，再一个一个数清楚。",
  visual: {
    caption: "数一数图形",
    rows: [["🔴", "🔺", "🟦", "🔺", "🟨", "🔺"]]
  }
}

添加新题时，请保持 id 不重复，并保证 options 里有且只有一个正确答案。

导出错题 PDF

进入“错题再练”页面后，如果有待练错题，会看到“导出PDF/打印”按钮。点击后会打开浏览器打印窗口：

• 想打印纸质版，直接选择打印机。
• 想保存 PDF，在打印窗口里选择“存储为 PDF”。

导出的错题纸会包含题目、选项、作答空格，以及单独的答案和提示页。

许可证

本项目采用 MIT License，详见 LICENSE。