dsh-courseware 0.1.0

package/engine/pptxgen/examples.py

@@ -0,0 +1,290 @@
+"""内置示例：一份完整的《分数的初步认识》课件规格。"""
+
+from __future__ import annotations
+
+DEMO_DECK_YAML = """\
+# ============================================================
+# 课件规格示例 —— 人教版小学数学三年级上册《分数的初步认识》
+# 生成：pptxgen build examples/示例课件_分数的初步认识.yaml \\
+#          -t examples/assets/内置模板_16x9.pptx
+# ============================================================
+
+deck:
+  title: 分数的初步认识
+  subtitle: 人教版 小学数学 三年级上册 第八单元
+  subject: 数学
+  grade: 三年级
+  teacher: 王老师
+  school: 阳光小学
+  date: 2025年 春
+
+# 模板文件（也可用命令行 -t 覆盖）
+template: assets/内置模板_16x9.pptx
+
+options:
+  answer_mode: end        # end=答案统一放最后 | inline=每题下方 | none=不显示
+  page_numbers: true
+  chrome: auto            # auto=自动复制模板装饰层 | off=关闭
+
+slides:
+
+  # ---------------- 封面 ----------------
+  - type: cover
+    title: 分数的初步认识
+    subtitle: 把一个物体平均分，认识几分之一
+
+  # ---------------- 目录 ----------------
+  - type: toc
+    title: 本节课我们将学习
+    items:
+      - 认识几分之一
+      - 比较几分之一的大小
+      - 分数的简单计算
+      - 生活中的分数
+
+  # ---------------- 章节一 ----------------
+  - type: section
+    title: 认识几分之一
+    subtitle: 从"平均分"开始
+    items:
+      - 什么是平均分
+      - 几分之一的读写
+      - 分数各部分的名称
+    note: 用 2 分钟回顾"平均分"的概念，为引入分数做铺垫。
+
+  - type: objectives
+    title: 学习目标
+    goals:
+      - 结合具体情境，初步认识几分之一，会读、会写简单的分数
+      - 知道分数各部分的名称，理解分数表示的实际含义
+      - 能比较分子是 1 的两个分数的大小
+    key_points:
+      - 理解"平均分"是分数的前提
+      - 认识几分之一，掌握分数的读写法
+    hard_points:
+      - 理解几分之一表示"其中的一份"与整体的关系
+      - 同分子分数大小的比较方法
+
+  - type: content
+    title: 什么是"平均分"
+    subtitle: 把一个物体分成若干份，每份分得同样多
+    bullets:
+      - text: 把一块月饼平均分成 2 份，每份是这块月饼的一半
+        level: 0
+      - text: "写作：1/2，读作：二分之一"
+        level: 1
+      - text: 把一张长方形纸平均分成 4 份，每份是这张纸的 1/4
+        level: 0
+      - text: 每份必须"同样大"，否则不能叫平均分
+        level: 1
+    image_caption: 平均分与不平均分的对比
+    note: 拿一张纸现场对折，让学生直观感受"同样大"。
+
+  - type: content
+    title: 认识几分之一
+    bullets:
+      - text: 把一个物体或图形平均分成几份，其中的 1 份就是它的几分之一
+        level: 0
+      - text: 平均分成 3 份，其中的 1 份就是 1/3
+        level: 1
+      - text: 平均分成 5 份，其中的 1 份就是 1/5
+        level: 1
+      - text: 分数各部分的名称
+        level: 0
+      - text: 中间的横线叫分数线，表示"平均分"
+        level: 1
+      - text: 下面的数叫分母，表示平均分成几份
+        level: 1
+      - text: 上面的数叫分子，表示取了其中的几份
+        level: 1
+    note: 板书 1/3，逐一指认分数线、分母、分子。
+
+  # ---------------- 例题 ----------------
+  - type: example
+    title: 例题讲解
+    bullets:
+      - 把一根 8 米长的绳子平均分成 4 段，每段是这根绳子的几分之几？
+    steps:
+      - 找出关键信息：总长度 8 米，平均分成 4 段
+      - 因为是"平均分成 4 段"，所以分母是 4
+      - 求"每段"，即取其中的 1 份，所以分子是 1
+      - 答：每段是这根绳子的 1/4
+    note: 强调"平均分成几段"决定分母，与具体长度无关——这是易错点。
+
+  - type: content
+    title: 比较几分之一的大小
+    subtitle: 分子都是 1 时，分母越大，分数反而越小
+    bullets:
+      - text: 把同样大的两张纸，一张平均分成 2 份，一张平均分成 4 份
+        level: 0
+      - text: 分成 2 份的那份更大，所以 1/2 > 1/4
+        level: 1
+      - text: 分的份数越多，每一份就越小
+        level: 0
+      - text: 结论：分子相同，分母越大，分数越小
+        level: 1
+
+  # ---------------- 随堂练习 ----------------
+  - type: practice
+    title: 随堂练习
+    bullets:
+      - 先独立完成，再同桌互相说一说是怎么想的。
+    questions:
+      - q: 把一块蛋糕平均分成 6 份，其中的 1 份是这块蛋糕的（　　）。
+        options:
+          - A. 1/2
+          - B. 1/6
+          - C. 6
+          - D. 1/3
+        answer: B
+        analysis: 平均分成 6 份，取其中 1 份，分母是 6，分子是 1，所以是 1/6。
+      - q: 下面各数中，最大的是（　　）。
+        options:
+          - A. 1/2
+          - B. 1/5
+          - C. 1/8
+          - D. 1/9
+        answer: A
+        analysis: 分子都是 1，分母越小分数越大。2 最小，所以 1/2 最大。
+      - q: 判断：把一个圆分成 3 份，每份一定是这个圆的 1/3。
+        options:
+          - A. 正确
+          - B. 错误
+        answer: B
+        analysis: 必须是"平均分"成 3 份，每份才是 1/3。题目没有说明是平均分。
+
+  # ---------------- 课堂小结 ----------------
+  - type: summary
+    title: 课堂小结
+    mindmap:
+      center: 分数的初步认识
+      branches:
+        - title: 前提
+          items: [必须是平均分, 每份同样大]
+        - title: 读写
+          items: [先写分数线, 再写分母, 最后写分子]
+        - title: 各部分名称
+          items: [分数线、分母、分子]
+        - title: 比大小
+          items: [分子相同看分母, 分母越大分数越小]
+        - title: 易错点
+          items: [没说"平均分"就不能用分数表示]
+
+  # ---------------- 课后作业 ----------------
+  - type: homework
+    title: 课后作业
+    items:
+      - 完成课本第 92 页"做一做"第 1、2 题
+      - 用一张正方形纸折出它的 1/4，并涂上颜色
+      - 找一找生活中的分数，明天上课分享一个例子
+    note: 注意：折纸作业要拍照片上传到班级群，看看谁的方法最多。
+
+  # ---------------- 结束页 ----------------
+  - type: end
+    title: 谢谢观看
+    subtitle: 数学源于生活，也用于生活
+"""
+
+
+def deck_template(title: str = "我的课件") -> str:
+    return f"""\
+# 课件规格文件 —— 填好后运行：
+#   pptxgen build 本文件.yaml -t 你的模板.pptx
+
+deck:
+  title: {title}
+  subtitle: 副标题（如：人教版 XX 学科 X 年级 X 册）
+  subject: 数学
+  grade: 三年级
+  teacher: 张老师
+  school:
+  date:
+
+# 不给模板时，会自动用 templates/ 目录下唯一的 pptx
+template:
+
+options:
+  answer_mode: end
+  page_numbers: true
+  chrome: auto
+
+slides:
+  - type: cover
+    title: {title}
+    subtitle: 副标题
+
+  - type: toc
+    title: 目 录
+    items:
+      - 第一部分
+      - 第二部分
+
+  - type: section
+    title: 第一部分
+    subtitle: 本节的引入语
+
+  - type: objectives
+    title: 学习目标
+    goals:
+      - 目标一
+      - 目标二
+    key_points:
+      - 重点
+    hard_points:
+      - 难点
+
+  - type: content
+    title: 知识点标题
+    subtitle: 一句话概括
+    bullets:
+      - text: 要点一
+        level: 0
+      - text: 要点一的补充说明
+        level: 1
+      - text: 要点二
+        level: 0
+    # image: assets/xxx.png     # 可选配图（相对路径按本文件所在目录解析）
+    # image_side: right         # right / left / top / bottom
+    note: 讲稿备注会写进 PPT 的备注栏
+
+  - type: practice
+    title: 随堂练习
+    questions:
+      - q: 题干？
+        options:
+          - A. 选项一
+          - B. 选项二
+        answer: A
+        analysis: 解析说明
+
+  - type: summary
+    title: 课堂小结
+    points:
+      - 小结要点一
+      - 小结要点二
+
+  - type: homework
+    title: 课后作业
+    items:
+      - 作业一
+    note: 温馨提示
+
+  - type: end
+    title: 谢谢观看
+    subtitle: 下节课见
+"""
+
+
+# 页型速查（用于 README 和帮助信息）
+SLIDE_TYPE_HELP = [
+    ("cover", "封面", "title / subtitle / teacher / school / date"),
+    ("toc", "目录", "title / items[]"),
+    ("section", "章节过渡", "title / subtitle / items[] / index(自动编号)"),
+    ("objectives", "学习目标", "title / goals[] / key_points[] / hard_points[]"),
+    ("content", "知识点讲解", "title / subtitle / bullets[] / image / image_side / images[]"),
+    ("example", "例题讲解", "title / bullets[](题干) / steps[]"),
+    ("practice", "课堂练习", "title / questions[{q,options,answer,analysis}]"),
+    ("summary", "课堂小结", "title / mindmap{center,branches[]} 或 points[]"),
+    ("homework", "课后作业", "title / items[] / note"),
+    ("end", "结束页", "title / subtitle"),
+]