joey5628/doodle-mini
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 完成四种字母描红开发

Browse Source
This commit is contained in:
R524809
2026-04-17 17:03:36 +08:00
parent 15ad5cce75
commit 9febf7da4f
16 changed files with 479 additions and 480 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/生成方案/字母描红设计方案.md
+89 -100
View File
@@ -12,7 +12,7 @@
覆盖四种练习形态：
1. **单字母学习页**：选定一个字母，含书写示意、阅读句（如 *L is for Lion*）、配图，下方四线三格描红行。
1. **单字母学习页**：选定一个字母，含书写示意、阅读句（如 _L is for Lion_）、配图，下方四线三格描红行。
2. **整页 26 字母**：26 个字母各占一行（或等价满版排列），四线三格内描红。
3. **上大小写下小写**：上半区展示大写 A–Z，下半区展示小写 a–z。
4. **两列 26 字母**：一页内左列 A–M、右列 N–Z（或同构小写），每行含示范与描红格。
@@ -25,14 +25,12 @@
从产品视角是四种题型；从引擎视角可收敛为**同一排版模板 + 同一数据生成器**，通过 `generatorConfig.mode` 区分。
| 用户可见类型 | 排版本质 | 模板 `template` | 生成器 `generator` |
| --------- | ------------------ | ----------------- | ---------------- |
| 单字母学习页 | 教学区 + 描红区（混合型纵向分区） | `tracing-writing` | `letter-tracing` |
| 26 字母整页描红 | 纯描红满版（多行） | `tracing-writing` | `letter-tracing` |
| 上大写 / 下小写 | 纯描红双区块（展示 + 轻描红） | `tracing-writing` | `letter-tracing` |
| 两列 26 字母 | 纯描红双栏 | `tracing-writing` | `letter-tracing` |
| 用户可见类型 | 排版本质 | 模板 `template` | 生成器 `generator` |
| --------------- | --------------------------------- | ----------------- | ------------------ |
| 单字母学习页 | 教学区 + 描红区（混合型纵向分区） | `tracing-writing` | `letter-tracing` |
| 26 字母整页描红 | 纯描红满版（多行） | `tracing-writing` | `letter-tracing` |
| 上大写 / 下小写 | 纯描红双区块（展示 + 轻描红） | `tracing-writing` | `letter-tracing` |
| 两列 26 字母 | 纯描红双栏 | `tracing-writing` | `letter-tracing` |
**结论**：一个 `TracingWritingRenderer`（扩展四线三格能力）+ 一个 `LetterTracingGenerator`，用 `mode` 参数驱动四种版面，无需四种独立页面类型（除非产品坚持拆入口卡片）。
@@ -42,31 +40,31 @@
### 3.1 `single-letter`（单字母学习页）
- **上部（约 40%～45% 内容高）**：教学区
- 配图（与字母绑定的词汇插图，内置 26 组映射 + 资源 key / CDN URL）
- 大写 + 小写展示
- 阅读句：`*X* is for *Word`*
- 书写顺序示意（可用简化箭头/步骤编号，首版可弱化）
- **下部（约 50%）**：描红区
- 至少两行四线三格：一行大写、一行小写（或按配置多行）
- 每行：示范格（实线/深色）+ 若干渐淡虚线格 + 可选空白格
- **上部（约 40%～45% 内容高）**：教学区
- 配图（与字母绑定的词汇插图，内置 26 组映射 + 资源 key / CDN URL）
- 大写 + 小写展示
- 阅读句：`*X* is for *Word`\*
- 书写顺序示意（可用简化箭头/步骤编号，首版可弱化）
- **下部（约 50%）**：描红区
- 至少两行四线三格：一行大写、一行小写（或按配置多行）
- 每行：示范格（实线/深色）+ 若干渐淡虚线格 + 可选空白格
### 3.2 `full-alphabet`（26 字母整页）
- 26 行（大写或二选一为小写），每行对应一个字母。
- 每行：四线三格横排多个单元格——首格示范，后续为渐淡描红或空白。
- 26 行（大写或二选一为小写），每行对应一个字母。
- 每行：四线三格横排多个单元格——首格示范，后续为渐淡描红或空白。
- 行高由可用高度 / 26 自动换算，保证打印可读（需与 `fontSize`、DPI 导出策略一致）。
### 3.3 `upper-lower-split`（上大写、下小写）
- 上区块：标题如「大写字母」+ 两行（或紧凑网格）排完 A–Z，每字母一格四线三格，偏**展示**（描红可弱：首格实线 + 空白）。
- 分隔线。
- 上区块：标题如「大写字母」+ 两行（或紧凑网格）排完 A–Z，每字母一格四线三格，偏**展示**（描红可弱：首格实线 + 空白）。
- 分隔线。
- 下区块：标题如「小写字母」+ 同理排完 a–z。
### 3.4 `two-column`（两列）
- 左列 A–M（或 a–m），右列 N–Z（或 n–z）。
- 每行结构与 `full-alphabet` 类似：示范 + 多格描红。
- 左列 A–M（或 a–m），右列 N–Z（或 n–z）。
- 每行结构与 `full-alphabet` 类似：示范 + 多格描红。
- 中间留白或细分隔线，避免幼儿视觉混淆。
---
@@ -75,9 +73,9 @@
用于英文字母书写指导（区别于汉字田字格）：
- **顶线**：大写字母上沿参考。
- **中虚线**：小写无升部字母的上沿（x-height 概念）。
- **基线**：字母落笔主参考线。
- **顶线**：大写字母上沿参考。
- **中虚线**：小写无升部字母的上沿（x-height 概念）。
- **基线**：字母落笔主参考线。
- **底线**：降部（如 g、p、y）下沿参考。
大写主体落在顶线—基线之间；小写主体多在中虚线—基线之间，降部延伸至底线。渲染器需实现 `drawFourLineGrid(cellRect)`，并与 `fontSize`、基线对齐算法统一。
@@ -96,99 +94,97 @@
┌─────────────────────────────────────────┐
│ ← 返回 英语字母描红 ❤️ │
│ ← 返回 英语字母描红 ❤️ │
├─────────────────────────────────────────┤
│ │
│ │
│ ┌─────────────────────────────────┐ │
│ ┌─────────────────────────────────┐ │
│ │ │ │
│ │ │ │
│ │ A4 打印效果预览区 │ │
│ │ A4 打印效果预览区 │ │
│ │ (Canvas 实时渲染) │ │
│ │ (Canvas 实时渲染) │ │
│ │ │ │
│ │ │ │
│ └─────────────────────────────────┘ │
│ └─────────────────────────────────┘ │
│ │
│ │
│ ⚙️ 参数设置 │
│ ⚙️ 参数设置 │
│ ┌─────────────────────────────────┐ │
│ ┌─────────────────────────────────┐ │
│ │ │ │
│ │ │ │
│ │ 练习类型： │ │
│ │ 练习类型： │ │
│ │ ┌──────┐┌──────┐┌──────┐ │ │
│ │ ┌──────┐┌──────┐┌──────┐ │ │
│ │ │ 单字母 ││ 整页 ││大小写│ │ │ ← 核心切换
│ │ │ 单字母 ││ 整页 ││大小写│ │ │ ← 核心切换
│ │ │ 学习页 ││ 描红 ││对照 │ │ │
│ │ │ 学习页 ││ 描红 ││对照 │ │ │
│ │ └──────┘└──────┘└──────┘ │ │
│ │ └──────┘└──────┘└──────┘ │ │
│ │ ┌──────┐ │ │
│ │ ┌──────┐ │ │
│ │ │ 两列 │ │ │
│ │ │ 两列 │ │ │
│ │ │ 描红 │ │ │
│ │ │ 描红 │ │ │
│ │ └──────┘ │ │
│ │ └──────┘ │ │
│ │ │ │
│ │ │ │
│ │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ │
│ │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ │
│ │ │ │
│ │ │ │
│ │ 大小写：[大写 ▼] │ │ ← mode 2/4 时显示
│ │ 大小写：[大写 ▼] │ │ ← mode 2/4 时显示
│ │ │ │
│ │ │ │
│ │ 选择字母：A [选中] B [选中]... │ │ ← mode 1 时显示
│ │ 选择字母：A [选中] B [选中]... │ │ ← mode 1 时显示
│ │ │ │
│ │ │ │
│ │ 每行描红格数：[5 ▼] │ │ ← mode 1/2/4 时显示
│ │ 每行描红格数：[5 ▼] │ │ ← mode 1/2/4 时显示
│ │ │ │
│ │ │ │
│ └─────────────────────────────────┘ │
│ └─────────────────────────────────┘ │
│ │
│ │
│ ┌──────────┐ ┌──────────────┐ │
│ ┌──────────┐ ┌──────────────┐ │
│ │ 🔄 换一批 │ │ 📥 保存到相册 │ │
│ │ 🔄 换一批 │ │ 📥 保存到相册 │ │
│ └──────────┘ └──────────────┘ │
│ └──────────┘ └──────────────┘ │
│ │
│ │
└─────────────────────────────────────────┘
### 5.2 参数项与 Mode 的显隐
| 配置项 | `single-letter` | `full-alphabet` | `upper-lower-split` | `two-column` |
| ---------- | --------------- | --------------- | ------------------- | ------------ |
| 练习类型（mode） | 显示 | 显示 | 显示 | 显示 |
| 选择字母 | 显示（单选） | 隐藏 | 隐藏 | 隐藏 |
| 大小写 | 隐藏（默认双写） | 显示 | 隐藏（固定双区） | 显示 |
| 每行描红格数 | 显示 | 显示 | 隐藏或固定为 1 | 显示 |
| 换一批 | 可切换下一字母 | 可不展示或禁用 | 可不展示 | 可不展示 |
| 配置项 | `single-letter` | `full-alphabet` | `upper-lower-split` | `two-column` |
| ---------------- | ---------------- | --------------- | ------------------- | ------------ |
| 练习类型（mode） | 显示 | 显示 | 显示 | 显示 |
| 选择字母 | 显示（单选） | 隐藏 | 隐藏 | 隐藏 |
| 大小写 | 隐藏（默认双写） | 显示 | 隐藏（固定双区） | 显示 |
| 每行描红格数 | 显示 | 显示 | 隐藏或固定为 1 | 显示 |
| 换一批 | 可切换下一字母 | 可不展示或禁用 | 可不展示 | 可不展示 |
参数面板由 `WorksheetConfig.userConfigurable` 描述；前端根据当前 `mode` **过滤**不适用字段（或在 JSON 层拆成 4 条配置，每条只含本 mode 的 `userConfigurable`）。
### 5.3 入口策略
- **推荐**：发现页 / 英语分类下 **4 张卡片**，对应 4 个 `worksheet id`，均进入**同一通用 worksheet 页面**，仅默认 `generatorConfig` 不同。
- **推荐**：发现页 / 英语分类下 **4 张卡片**，对应 4 个 `worksheet id`，均进入**同一通用 worksheet 页面**，仅默认 `generatorConfig` 不同。
- **可选**：单页内提供「练习类型」Segment，切换 `mode` 并合并默认参数后重绘（与多卡片二选一或并存）。
---
@@ -221,15 +217,15 @@ interface LetterTracingGeneratorConfig {
生成器产出**与平台无关**的数据，供 `TracingWritingRenderer` 消费：
- `single-letter`：`{ teaching: { upper, lower, word, sentence, imageRef }, rows: TracingRow[] }`
- `full-alphabet` / `two-column`：`{ columns?: 1 | 2, rows: TracingRow[] }`
- `single-letter`：`{ teaching: { upper, lower, word, sentence, imageRef }, rows: TracingRow[] }`
- `full-alphabet` / `two-column`：`{ columns?: 1 | 2, rows: TracingRow[] }`
- `upper-lower-split`：`{ upperBlock: TracingRow[] | GlyphCell[], lowerBlock: ... }`
`TracingRow` 建议包含：`displayChar`、`cells: { char, opacity, isGuide }[]`、`gridType: 'four-line'`。
### 6.3 词汇与配图数据
- 维护 `Record<'A'..'Z', { word: string; imageKey: string }>`（或云端下发）。
- 维护 `Record<'A'..'Z', { word: string; imageKey: string }>`（或云端下发）。
- 图片走内置分包资源或云存储 URL，由 [产品设计文档](../产品设计文档.md) §7.3 中「云素材」规则约束：**插图是设计资产，可 CDN；整页描红仍客户端拼版**。
---
@@ -238,23 +234,21 @@ interface LetterTracingGeneratorConfig {
### 7.1 职责
- 沿用现有 `BaseTemplateRenderer` 流程：背景、页眉、说明文案、内容区、页脚。
- 根据 `data.mode` 分支调用 `drawSingleLetterPage` / `drawFullAlphabetPage` / `drawUpperLowerSplitPage` / `drawTwoColumnPage`。
- 沿用现有 `BaseTemplateRenderer` 流程：背景、页眉、说明文案、内容区、页脚。
- 根据 `data.mode` 分支调用 `drawSingleLetterPage` / `drawFullAlphabetPage` / `drawUpperLowerSplitPage` / `drawTwoColumnPage`。
- 统一使用 **A4 逻辑坐标**（与技术文档 §7.1 Canvas 管线一致）。
### 7.2 与汉字描红的差异
| 维度 | 汉字练字（`character-tracing`） | 字母描红（`letter-tracing`） |
| --- | ------------------------- | ---------------------- |
| 格子 | 田字格 | 四线三格 |
| 字形 | SVG 笔画路径 | 优先 `fillText` + 字体轮廓 |
| 版面 | 多字多格排布 | 四种 mode 分区逻辑 |
| 维度 | 汉字练字（`character-tracing`） | 字母描红（`letter-tracing`） |
| ---- | ------------------------------- | ---------------------------- |
| 格子 | 田字格 | 四线三格 |
| 字形 | SVG 笔画路径 | 优先 `fillText` + 字体轮廓 |
| 版面 | 多字多格排布 | 四种 mode 分区逻辑 |
### 7.3 参考现有实现
- `service/wordDrawService.ts`：布局分区、渐淡格思路可对齐。
- `service/wordDrawService.ts`：布局分区、渐淡格思路可对齐。
- `mathPages/shared/service/numberWriteDraw.ts`：四线三格线型可参考。
---
@@ -330,7 +324,7 @@ interface LetterTracingGeneratorConfig {
```json
{
"id": "letter-tracing-two-column",
"id": "letter-tracing-case-pairing",
"title": "字母描红（两列）",
"category": "english",
"subcategory": "letter-tracing",
@@ -354,24 +348,19 @@ interface LetterTracingGeneratorConfig {
## 九、实现落地清单（工程侧）
| 项 | 说明 |
| ------------------------ | -------------------------------------------------------------------------- |
| `LetterTracingGenerator` | `core/generators/` 或英语分包 `shared/generators/`，注册到 `generatorRegistry` |
| `TracingWritingRenderer` | 扩展四线三格 + 四种 `draw*Page` |
| 字母词汇与配图映射 | `core/data/alphabet.ts` 或云端配置 |
| 通用 worksheet 页 | `pages/worksheet/worksheet`（或过渡期 `englishPages` 专用页再迁） |
| 项 | 说明 |
| ------------------------ | ---------------------------------------------------------------------------------------- |
| `LetterTracingGenerator` | `core/generators/` 或英语分包 `shared/generators/`，注册到 `generatorRegistry` |
| `TracingWritingRenderer` | 扩展四线三格 + 四种 `draw*Page` |
| 字母词汇与配图映射 | `core/data/alphabet.ts` 或云端配置 |
| 通用 worksheet 页 | `pages/worksheet/worksheet`（或过渡期 `englishPages` 专用页再迁） |
| `ALL_WORKSHEETS` | 增加 4 条 `WorksheetDefinition`，`category` 对齐英语，`legacyPage` 可指向 worksheet 路由 |
| 分包 | 按需新增 `englishPages`，避免主包膨胀 |
| 分包 | 按需新增 `englishPages`，避免主包膨胀 |
---
## 十、修订记录
| 日期 | 版本 | 说明 |
| ---------- | ---- | ---- |
| 日期 | 版本 | 说明 |
| ---------- | ---- | -------- |
| 2026-04-03 | v1.0 | 初稿入库 |