joey5628/doodle-mini
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
feature-3.5.0
doodle-mini/docs/生成方案/字母描红设计方案.md
T
R524809 9febf7da4f feat: 完成四种字母描红开发
2026-04-17 17:03:36 +08:00

14 KiB
Raw Permalink Blame History

字母描红 — 预览、配置与模板引擎设计

配套文档：产品设计文档 | 技术架构设计文档
版本：v1.0
最后更新：2026-04-03

一、目标与范围

本文档说明「英语字母描红」在小程序内的预览与配置页如何设计，以及如何对齐 技术架构设计文档 第五章的模板引擎（tracing-writing + letter-tracing）。

覆盖四种练习形态：

  1. 单字母学习页：选定一个字母，含书写示意、阅读句（如 L is for Lion）、配图，下方四线三格描红行。
  2. 整页 26 字母：26 个字母各占一行（或等价满版排列），四线三格内描红。
  3. 上大小写下小写：上半区展示大写 A–Z，下半区展示小写 a–z。
  4. 两列 26 字母：一页内左列 A–M、右列 N–Z（或同构小写），每行含示范与描红格。

交付形态遵循 产品设计文档 §7.3：客户端动态生成，不预生成整页 PNG 上云存储。

二、四种子类型的模板引擎归类

从产品视角是四种题型；从引擎视角可收敛为同一排版模板 + 同一数据生成器，通过 generatorConfig.mode 区分。

用户可见类型 排版本质 模板 template 生成器 generator
单字母学习页 教学区 + 描红区（混合型纵向分区） tracing-writing letter-tracing
26 字母整页描红 纯描红满版（多行） tracing-writing letter-tracing
上大写 / 下小写 纯描红双区块（展示 + 轻描红） tracing-writing letter-tracing
两列 26 字母 纯描红双栏 tracing-writing letter-tracing

结论：一个 TracingWritingRenderer（扩展四线三格能力）+ 一个 LetterTracingGenerator，用 mode 参数驱动四种版面，无需四种独立页面类型（除非产品坚持拆入口卡片）。

三、Mode 定义与版面结构

3.1 single-letter（单字母学习页）

  • 上部（约 40%～45% 内容高）：教学区
    • 配图（与字母绑定的词汇插图，内置 26 组映射 + 资源 key / CDN URL）
    • 大写 + 小写展示
    • 阅读句：*X* is for *Word*
    • 书写顺序示意（可用简化箭头/步骤编号，首版可弱化）
  • 下部（约 50%）：描红区
    • 至少两行四线三格：一行大写、一行小写（或按配置多行）
    • 每行：示范格（实线/深色）+ 若干渐淡虚线格 + 可选空白格

3.2 full-alphabet（26 字母整页）

  • 26 行（大写或二选一为小写），每行对应一个字母。
  • 每行：四线三格横排多个单元格——首格示范，后续为渐淡描红或空白。
  • 行高由可用高度 / 26 自动换算，保证打印可读（需与 fontSize、DPI 导出策略一致）。

3.3 upper-lower-split（上大写、下小写）

  • 上区块：标题如「大写字母」+ 两行（或紧凑网格）排完 A–Z，每字母一格四线三格，偏展示（描红可弱：首格实线 + 空白）。
  • 分隔线。
  • 下区块：标题如「小写字母」+ 同理排完 a–z。

3.4 two-column（两列）

  • 左列 A–M（或 a–m），右列 N–Z（或 n–z）。
  • 每行结构与 full-alphabet 类似：示范 + 多格描红。
  • 中间留白或细分隔线，避免幼儿视觉混淆。

四、四线三格绘制约定

用于英文字母书写指导（区别于汉字田字格）：

  • 顶线：大写字母上沿参考。
  • 中虚线：小写无升部字母的上沿（x-height 概念）。
  • 基线：字母落笔主参考线。
  • 底线：降部（如 g、p、y）下沿参考。

大写主体落在顶线—基线之间；小写主体多在中虚线—基线之间，降部延伸至底线。渲染器需实现 drawFourLineGrid(cellRect)，并与 fontSize、基线对齐算法统一。

五、预览与配置页（产品 UI）

5.1 页面结构（与通用生成页一致）

对齐产品设计中的生成/预览页：A4 预览区（Canvas）+ 参数面板 + 底部操作（换一批 / 保存相册 / 分享等）。

预览/配置页面 UI 设计

所有4种类型共用一个通用 worksheet 页面（pages/worksheet/worksheet），通过 worksheetId 加载不同 JSON 配置。但字母描红也可以做成一个聚合入口页 + 通用 worksheet 页的组合，体验更好：

┌─────────────────────────────────────────┐

│ ← 返回 英语字母描红 ❤️ │

├─────────────────────────────────────────┤

│ │

│ ┌─────────────────────────────────┐ │

│ │ │ │

│ │ A4 打印效果预览区 │ │

│ │ (Canvas 实时渲染) │ │

│ │ │ │

│ └─────────────────────────────────┘ │

│ │

│ ⚙️ 参数设置 │

│ ┌─────────────────────────────────┐ │

│ │ │ │

│ │ 练习类型： │ │

│ │ ┌──────┐┌──────┐┌──────┐ │ │

│ │ │ 单字母 ││ 整页 ││大小写│ │ │ ← 核心切换

│ │ │ 学习页 ││ 描红 ││对照 │ │ │

│ │ └──────┘└──────┘└──────┘ │ │

│ │ ┌──────┐ │ │

│ │ │ 两列 │ │ │

│ │ │ 描红 │ │ │

│ │ └──────┘ │ │

│ │ │ │

│ │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ │

│ │ │ │

│ │ 大小写：[大写 ▼] │ │ ← mode 2/4 时显示

│ │ │ │

│ │ 选择字母：A [选中] B [选中]... │ │ ← mode 1 时显示

│ │ │ │

│ │ 每行描红格数：[5 ▼] │ │ ← mode 1/2/4 时显示

│ │ │ │

│ └─────────────────────────────────┘ │

│ │

│ ┌──────────┐ ┌──────────────┐ │

│ │ 🔄 换一批 │ │ 📥 保存到相册 │ │

│ └──────────┘ └──────────────┘ │

│ │

└─────────────────────────────────────────┘

5.2 参数项与 Mode 的显隐

配置项 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 不同。
  • 可选：单页内提供「练习类型」Segment，切换 mode 并合并默认参数后重绘（与多卡片二选一或并存）。

六、生成器设计：letter-tracing

6.1 配置（建议字段）

type LetterTracingMode =
    | 'single-letter'
    | 'full-alphabet'
    | 'upper-lower-split'
    | 'two-column';

interface LetterTracingGeneratorConfig {
    mode: LetterTracingMode;
    /** full-alphabet / two-column 使用 */
    letterCase: 'upper' | 'lower';
    /** single-letter 使用，如 'L' */
    selectedLetter?: string;
    /** 每行描红单元数量（示范 + 渐淡 + 空白计在同一行内） */
    repetitions: number;
    /** 渐淡策略 */
    fadePattern: 'gradient' | 'first-only';
}

6.2 输出数据结构（示意）

生成器产出与平台无关的数据，供 TracingWritingRenderer 消费：

  • 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 }>（或云端下发）。
  • 图片走内置分包资源或云存储 URL，由 产品设计文档 §7.3 中「云素材」规则约束：插图是设计资产，可 CDN；整页描红仍客户端拼版。

七、渲染器设计：tracing-writing 扩展

7.1 职责

  • 沿用现有 BaseTemplateRenderer 流程：背景、页眉、说明文案、内容区、页脚。
  • 根据 data.mode 分支调用 drawSingleLetterPage / drawFullAlphabetPage / drawUpperLowerSplitPage / drawTwoColumnPage。
  • 统一使用 A4 逻辑坐标（与技术文档 §7.1 Canvas 管线一致）。

7.2 与汉字描红的差异

维度 汉字练字（character-tracing） 字母描红（letter-tracing）
格子 田字格 四线三格
字形 SVG 笔画路径 优先 fillText + 字体轮廓
版面 多字多格排布 四种 mode 分区逻辑

7.3 参考现有实现

  • service/wordDrawService.ts：布局分区、渐淡格思路可对齐。
  • mathPages/shared/service/numberWriteDraw.ts：四线三格线型可参考。

八、WorksheetConfig 示例（四条）

以下可与 core/data/worksheets.ts 或云端 worksheets 集合对齐；id 供路由与统计使用。

1）单字母学习页

{
    "id": "letter-tracing-single",
    "title": "字母学习页",
    "category": "english",
    "subcategory": "letter-tracing",
    "template": "tracing-writing",
    "generator": "letter-tracing",
    "generatorConfig": {
        "mode": "single-letter",
        "selectedLetter": "A",
        "repetitions": 5,
        "fadePattern": "gradient"
    },
    "layoutConfig": {
        "showInstruction": true,
        "instructionText": "看一看，读一读，再描一描"
    }
}

2）26 字母整页

{
    "id": "letter-tracing-full",
    "title": "26 字母描红",
    "category": "english",
    "subcategory": "letter-tracing",
    "template": "tracing-writing",
    "generator": "letter-tracing",
    "generatorConfig": {
        "mode": "full-alphabet",
        "letterCase": "upper",
        "repetitions": 8,
        "fadePattern": "gradient"
    }
}

3）大小写对照

{
    "id": "letter-tracing-upper-lower",
    "title": "大小写字母对照",
    "category": "english",
    "subcategory": "letter-tracing",
    "template": "tracing-writing",
    "generator": "letter-tracing",
    "generatorConfig": {
        "mode": "upper-lower-split",
        "repetitions": 1,
        "fadePattern": "first-only"
    },
    "layoutConfig": {
        "columns": 13
    }
}

4）两列描红

{
    "id": "letter-tracing-case-pairing",
    "title": "字母描红（两列）",
    "category": "english",
    "subcategory": "letter-tracing",
    "template": "tracing-writing",
    "generator": "letter-tracing",
    "generatorConfig": {
        "mode": "two-column",
        "letterCase": "upper",
        "repetitions": 4,
        "fadePattern": "gradient"
    },
    "layoutConfig": {
        "columns": 2
    }
}

完整 userConfigurable 数组可在实现阶段按 §5.2 补全，并同步云库字段定义。

九、实现落地清单（工程侧）

项 说明
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，避免主包膨胀

十、修订记录

日期 版本 说明
2026-04-03 v1.0 初稿入库
Reference in New Issue View Git Blame Copy Permalink