简介：这份沪教版小学数学一年级知识点归纳文档，面向一年级学生家长、课后辅导教师及备课老师，用于系统梳理教材核心考点、辅助日常复习与期末查漏补缺。资源包内共1个docx文件，约40KB，篇幅紧凑、便于打印与随时翻阅。内容覆盖加减法运算规律、比一比与括号填数方法、加减法互逆关系，以及数位与计数单位、数的排列与大小比较、相邻数与整十数、人民币单位换算、时间初步认识与12时和24时计时法互化、两位数加减整十数与一位数等模块，并以位值表、数射线、分与合等工具帮助理解。其中时间换算与钟面读时部分配有大量对照示例，可直接用于家庭辅导或课堂随堂练习讲解，适合需要一份体系化复习提纲的读者。目前该资源已有552人学习，可作为一年级数学知识点速查与巩固的参考材料。
1. 一年级数学知识点归纳，为什么值得用脚本生成一份 docx
教研组发来一句话需求：出一份「沪教版小学数学一年级知识点归纳.docx」，下周发给家长。很多人的第一反应是打开 Word 手工敲、手工排版，第一次三个小时，第二次改两个单元，格式又崩了。真正省事的做法是反过来的：先把知识点变成结构化数据，再让脚本把它渲染成 docx。文档只是产物，数据才是资产。
一年级数学的内容看着简单，坑却不少：数、量、图形、人民币、时间这几条线交叉，还要照顾「20 以内加减法」和「100 以内数的认识」的先后顺序。手工文档一旦要按单元拆、按难度标、按题型归类，就会变成多份重复劳动。而结构化之后，同一份数据可以输出单元版、学期版，也能顺手导出题卡。
这篇文章面向的读者是教育信息化方向的后端、脚本工程师，以及习惯用 Python 处理办公文档的技术人。下面从知识点建模讲到 python-docx 渲染，再讲模板复用和反向解析，每一段都能直接抄去改。适合谁：手上有一批教材目录要变成 docx 交付物，且不想再做第二遍手工排版的人。
2. 把沪教版一年级数学知识点拆成可渲染的数据结构
2.1 先盘点内容，再决定字段
直接开写代码之前，得先把一学期讲什么捋清楚。沪教版一年级的整体脉络大致是：10 以内的数与加减法、20 以内的数与进退位加减法、100 以内数的认识与加减、认识图形（长方体、正方体、圆柱、球）、认识人民币、时间的初步认识。这是常见划分，具体单元名以手头那版教材目录为准，别照着别人的表抄，教材调整过目录是常事。
盘点的目的是抽字段。一份知识点归纳文档，最小的可渲染信息就四类：这条知识点属于哪个单元、它叫什么、正文归纳写什么、有没有配套例题。再加两个工程字段：难度标记（用于生成不同版本）和检索标签（方便以后找回来）。字段不是越多越好，多了会让录入成本翻倍。
下面这张表是我一般会先拉出来的盘点表，用 Excel 或 CSV 录，之后直接喂给脚本。列的含义决定了后面 schema 怎么定：
| 列名 | 含义 | 示例 | 是否必填 |
|---|---|---|---|
| unit | 单元名，作为一级标题 | 20 以内数的认识 | 是 |
| title | 知识点标题，二级或三级 | 数的组成与读写 | 是 |
| level | 层级，1 单元 / 2 小节 / 3 细点 | 2 | 是 |
| body | 归纳正文，一段话 | 十位上的数表示几个十…… | 是 |
| examples | 例题，多条用换行分隔 | 12 里面有几个十和几个一 | 否 |
| tags | 标签，逗号分隔 | 基础,数的组成 | 否 |
| diff | 难度，A 基础 / B 提高 | A | 否 |
表格里的 level 是关键设计。它决定了这条记录渲染成 Heading 1 还是 Heading 2，也决定了文档目录能不能自动生成。不要把层级写在标题文字里（比如标题就写「一、」，然后靠人称判断），那样后面解析回来会很痛苦。
2.2 用 dataclass 定义知识点 schema 并落盘成 JSON
确认字段之后，落成一个 Python 数据结构。用 dataclass 而不是裸 dict，原因是字段拼错时能立刻报错，而不是生成一份缺章节的文档。
from dataclasses import dataclass, field, asdict from typing import List import json @dataclass class Point: unit: str # 单元名，渲染成一级标题 title: str # 知识点标题 level: int # 1=单元级 2=小节级 3=细点级 body: str = "" # 归纳正文 examples: List[str] = field(default_factory=list) # 例题列表 tags: List[str] = field(default_factory=list) # 检索标签 diff: str = "A" # A=基础 B=提高 def load(path: str) -> List[Point]: with open(path, encoding="utf-8") as f: raw = json.load(f) # 逐条构造，字段名写错会在此抛 TypeError，避免生成半成品文档 return [Point(**item) for item in raw] if __name__ == "__main__": points = load("data/grade1_points.json") # 按 unit 分组，保持录入顺序，后续渲染直接消费 groups = {} for p in points: groups.setdefault(p.unit, []).append(p) print(len(points), "条知识点", len(groups), "个单元")这段代码的逻辑很直白：load负责把 JSON 变成对象列表，Point(**item)是防御性写法，JSON 里多一个拼错的键会直接报错，比生成完文档再肉眼找漏页划算得多。groups用setdefault分组并保序，Python 3.7 之后 dict 保序，所以渲染顺序和录入顺序一致，不用额外排序字段。
参数说明：level用整数而不是枚举，是为了后面直接f"Heading {p.level}"；examples和tags用field(default_factory=list)而不是[]，这是 dataclass 的硬性要求，可变默认值共享会出现所有记录例题串在一起的问题，踩过一次就记住了。
2.3 章节层级到 docx 标题级别的映射规则
结构化数据到手后，要定死一套映射，否则每次渲染出来的文档样式都不一样。映射关系写进配置，别散在代码里。
LEVEL_STYLE = { 1: {"style": "Heading 1", "size": 16, "bold": True, "align": "center"}, 2: {"style": "Heading 2", "size": 14, "bold": True, "align": "left"}, 3: {"style": "Heading 3", "size": 12, "bold": True, "align": "left"}, } BODY_STYLE = {"size": 12, "line_spacing": 1.5, "first_indent": 2} # 首行缩进 2 字符Heading 1这类名称必须和模板里真实存在的样式名完全一致，中文版 Word 里有时是「标题 1」，用脚本建的空文档则是Heading 1，两种混用会静默退化成正文样式。稳妥做法是渲染前先打印所有样式名核对一遍：[s.name for s in doc.styles]。这一步花十秒，能省掉一次「标题怎么没加粗」的排查。
正文的first_indent用「字符」为单位而不是磅值，python-docx没有直接的字符缩进 API，要通过paragraph_format.first_line_indent = Pt(size * 2)换算，字号 12 磅时就是 24 磅。这个换算在换字号以后必须同步改，否则缩进会看起来偏大偏小。
3. 用 python-docx 生成知识点归纳文档的最小可用版本
3.1 环境准备与一次跑通的渲染脚本
依赖只有两个：python-docx负责生成，docxtpl后面做模板时再用。装的时候注意包名和导入名不一样。
pip install python-docx docxtpl # 验证 python -c "import docx; print(docx.__version__ if hasattr(docx,'__version__') else 'ok')"然后是核心渲染函数。它的职责只有三件：按 level 写标题、写正文、把例题按条目写出来。
from docx import Document from docx.shared import Pt from docx.enum.text import WD_ALIGN_PARAGRAPH from docx.oxml.ns import qn from typing import List from schema import Point, LEVEL_STYLE, BODY_STYLE # 上一章的配置 CN_FONT = "楷体" # 正文中文字体，小学文档通常用楷体 HEAD_FONT = "黑体" # 标题中文字体 def cn(run, font=CN_FONT, size=12, bold=False): """统一设置中英文字体，eastAsia 必须单独设，否则中文回退成宋体""" run.font.name = "Times New Roman" # 西文与数字 run.font.size = Pt(size) run.font.bold = bold run._element.rPr.rFonts.set(qn("w:eastAsia"), font) def render(points: List[Point], out: str): doc = Document() seen = set() # 已输出的单元，避免重复写一级标题 for p in points: if p.unit not in seen: seen.add(p.unit) h = doc.add_heading(p.unit, level=1) h.alignment = WD_ALIGN_PARAGRAPH.CENTER for r in h.runs: cn(r, HEAD_FONT, LEVEL_STYLE[1]["size"], True) cfg = LEVEL_STYLE.get(p.level, LEVEL_STYLE[3]) h = doc.add_heading(p.title, level=p.level) for r in h.runs: cn(r, HEAD_FONT, cfg["size"], True) para = doc.add_paragraph() para.paragraph_format.line_spacing = BODY_STYLE["line_spacing"] para.paragraph_format.first_line_indent = Pt(BODY_STYLE["size"] * 2) cn(para.add_run(p.body), CN_FONT, BODY_STYLE["size"]) for ex in p.examples: ep = doc.add_paragraph(style="List Number") cn(ep.add_run(ex), CN_FONT, BODY_STYLE["size"]) doc.save(out) if __name__ == "__main__": render(load("data/grade1_points.json"), "沪教版小学数学一年级知识点归纳.docx")逻辑说明：seen集合控制单元标题只出现一次，因为 JSON 是按知识点平铺的，同一个 unit 会有多条记录。add_heading(level=p.level)直接吃 level 字段，这就是前面坚持用整数的回报。例题用List Number样式而不是手工敲「1.」，Word 会自动续号，插入或删除时不用重排。
参数说明：first_line_indent用Pt(12*2)算出 24 磅，等于两个字符宽；cn()里西文字体单独设成 Times New Roman，是因为数学文档里数字和运算符多，全部用楷体渲染数字会显得松散。
3.2 三个必调的样式参数
样式里最容易被忽略、又最影响观感的是这三个。
第一个是w:eastAsia。run.font.name = "楷体"只作用于西文，中文会走默认字体。上面cn()函数里那句rFonts.set(qn("w:eastAsia"), font)才是真正让中文变楷体的地方，漏掉它，标题加粗看起来都正常，正文却全是宋体。
第二个是行距。一年级文档字号大、行距紧会挤成一团。line_spacing = 1.5是绝对倍数，也可以用Pt(22)指定固定行距，后者在混排图片时更可控。
第三个是表格和正文的字号一致性。python-docx 新建表格时单元格默认用Normal样式，字号往往和正文不同，生成出来表格里的字会比正文小一圈。稳妥做法是建完表格后遍历所有cell.paragraphs[0].runs统一调用cn()。
3.3 知识点表格与例题图片的插入方式
归纳文档里最常出现的是「数的组成」对照表，比如十位与个位的对应关系。这类内容用表格比用文字清楚。
def add_point_table(doc, headers, rows): t = doc.add_table(rows=1, cols=len(headers)) t.style = "Table Grid" # 带边框，中文文档几乎都用这个 for i, h in enumerate(headers): cell = t.rows[0].cells[i] cn(cell.paragraphs[0].add_run(h), HEAD_FONT, 11, True) for row in rows: cells = t.add_row().cells for i, v in enumerate(row): cn(cells[i].paragraphs[0].add_run(str(v)), CN_FONT, 11) # 表格整体居中 t.alignment = WD_ALIGN_PARAGRAPH.CENTER return t add_point_table(doc, ["十位", "个位", "读作", "组成"], [["1", "2", "十二", "1 个十和 2 个一"], ["2", "0", "二十", "2 个十"]])插入图片用doc.add_picture(path, width=Cm(6))，宽度建议用厘米固定值，不要用 Inches 混着来，容易在小页边距下溢出。图片段落要单独设居中，doc.add_picture返回的 InlineShape 挂在一个新段落上，取doc.paragraphs[-1].alignment调即可。例题配图建议按知识点编号命名（如u2_03.png），渲染时按title查表，比在 JSON 里写绝对路径更容易搬迁。
提示：教材配图有版权边界，脚本里最好留一个图片可选开关，没有配图时只输出文字表格，别让渲染流程因为找不到图直接崩掉。
4. 一年级各单元知识点归纳的模板化与排版问题排查
4.1 用 docxtpl 复用一份模板
上一章的脚本是从零建文档，样式全靠代码堆。如果教研组给了固定封面、页眉页脚、统一的字号规范，更省事的做法是让他们先做一份templates/summary.docx，里面写好样式，脚本只负责填内容。
from docxtpl import DocxTemplate from docx.shared import Pt tpl = DocxTemplate("templates/summary.docx") # units 是 [{name, points:[{title, body, examples}]}] 结构的嵌套列表 tpl.render({ "grade": "一年级", "term": "第一学期", "units": units, }) tpl.save("沪教版小学数学一年级知识点归纳.docx")模板里的写法是{% for u in units %}循环，占位符{{ u.name }}填单元名，内层再{% for p in u.points %}铺知识点。docxtpl 的价值在于样式归模板管、数据归脚本管，换封面只动模板，不动一行 Python。
参数说明：render的上下文里不要放Point对象直接渲染，docxtpl 对 dataclass 支持一般，稳妥做法是先asdict()转成 dict 再传。表格行循环要用{%tr for %}语法，写在表格行内的单元格里，用普通{% for %}会在表格外生成一堆空行。
4.2 三个高频坑：字体丢失、表格跨页、软回车
第一个坑是字体丢失。模板里的样式名和LEVEL_STYLE对不上，标题会退化成正文。排查方式是在渲染后回读，打印每个段落的style.name和第一个 run 的字体名，对不上的立刻暴露。
第二个坑是长表格跨页断开。知识点对照表超过一页时，第二页没有表头，家长翻着看会懵。解决办法是给表头行加重复属性：
from docx.oxml.ns import qn from docx.oxml import OxmlElement def repeat_header(row): trPr = row._tr.get_or_add_trPr() el = OxmlElement("w:tblHeader") # 标记为表头，跨页自动重复 el.set(qn("w:val"), "true") trPr.append(el) repeat_header(t.rows[0])第三个坑是软回车。手工从旧文档复制知识点时，段内常带Shift+Enter，读出来是w:br而不是新段落，脚本按段落切分时会把两条知识点粘成一条。处理办法是在写入前统一清洗：body.replace("\v", "\n").replace("\r", "")，把垂直制表符和回车都换成换行或直接去掉。
4.3 生成结果的校验：回读与 XML 差异对比
光看排版不够，交付前最好做一次机器校验。第一层是数量核对，回读段落和表格数量，和源数据算出来的期望值比对。
from docx import Document doc = Document("沪教版小学数学一年级知识点归纳.docx") heads = [p.text for p in doc.paragraphs if p.style.name.startswith("Heading")] assert len(heads) == len(units) + sum(len(u["points"]) for u in units), "标题数与数据不符" assert all(p.text.strip() for p in doc.paragraphs if p.style.name == "Normal"), "存在空正文段" print("校验通过：单元", len(units), "知识点", sum(len(u['points']) for u in units))第二层是版本差异。改过模板后想确认只有内容变了、样式没动，可以把 docx 当 zip 解开只比正文 XML。
mkdir -p build/a build/b unzip -o -q "沪教版小学数学一年级知识点归纳.docx" -d build/a # 格式化后比对，避免单行 XML 差异看不出重点 python - <<'PY' import re for tag in ("a", "b"): xml = open(f"build/{tag}/word/document.xml", encoding="utf-8").read() xml = xml.replace("><", ">\n<") # 拆行，便于 diff open(f"build/{tag}.txt", "w", encoding="utf-8").write(xml) PY diff build/a.txt build/b.txt | head -50这样比对的好处是样式定义在word/styles.xml，正文在document.xml，两者分开看，能立刻判断是内容问题还是模板问题。
注意：解包后的
word/media目录会带上所有图片，版本对比时记得把它排除，否则 diff 结果会被二进制内容刷屏。
5. 从归纳文档反向提取：拆包、转 Markdown 与题卡导出
不少人做完 docx 才发现，真正需要的是能贴进网页、能导入题卡工具的结构化内容。既然文档是脚本生成的，反向提取就顺理成章——按样式名切段落，还原成层级结构。
from docx import Document import csv doc = Document("沪教版小学数学一年级知识点归纳.docx") units, cur_unit, cur_point = [], None, None for p in doc.paragraphs: style, text = p.style.name, p.text.strip() if not text: continue if style == "Heading 1": cur_unit = {"name": text, "points": []} units.append(cur_unit) elif style == "Heading 2" and cur_unit is not None: cur_point = {"title": text, "body": ""} cur_unit["points"].append(cur_point) elif style == "Normal" and cur_point is not None: cur_point["body"] += text # 合并同知识点的多段正文这段代码的关键判断是style.name，所以前面生成时给的Heading 1/2一定要规范，反过来也说明样式名是这份文档的隐含接口。body用+=累加，是因为一个知识点的归纳正文可能被渲染成多个段落，直接覆盖会只留最后一段。
拿到结构后，导出 Markdown 只是一次字符串拼接：一级用#、二级用##、正文加两个空格换行。导出题卡则更适合 TSV，字段固定成「正面 / 背面 / 标签」，直接给记忆类工具导入。
| 导出目标 | 字段映射 | 注意事项 |
|---|---|---|
| Markdown | 标题层级对应#/## | 正文里的*_要转义 |
| TSV 题卡 | 正面=知识点标题，背面=正文 | 单元格内不能出现制表符 |
| JSON | 原样保留 unit/title/body | 用ensure_ascii=False落盘 |
实操里有个容易忽略的细节：导出的 Markdown 如果拿去过代码仓库做版本管理，中文文件名会被转义，建议在导出时把「沪教版小学数学一年级知识点归纳.docx」这类名字映射成grade1-math-shanghai.md这样的英文 slug，同时把中文原名写进文档头部的元信息里。这样既保留了可检索的中文标题，又避免了不同系统下文件名编码不一致带来的麻烦。
另外，反向提取出来的例题条目建议单独存一份examples.json，和正文分离。例题会随教学进度不断增删，正文相对稳定，混在一起的话，每次改一道题都要重新生成整份文档，diff 里全是噪音。分开存之后，文档负责讲解，题库负责练习，两边各自演进，脚本只在最终打包时把它们合并成一份 docx。
本文还有配套的精品资源，点击获取
