模板通用规则、题型与样式适配

模板、字段和卡牌怎样配合

模板不是一张可以直接学习的卡牌，而是一组可复用的内容和显示规则。字段决定每张卡牌保存什么数据；正面模板、背面模板和 CSS 决定这些数据怎样显示；模板类型决定是否存在挖空、反向卡、选择题或判断题等专用行为；模板选项还可以保存测验和连连看配置。

新建卡牌时会关联一个模板，之后卡牌只保存自己的字段值和少量状态。修改模板代码或 CSS 后，所有使用该模板的卡牌都会按新规则重新显示，但原有字段值不会自动迁移、补齐或转换。

字段配置决定制卡和显示能力

当前“字段管理”不提供字段数据类型切换，只维护字段名、顺序、备注、编辑权限、朗读、语言、必填和标题设置。导入模板配置后，应在制卡表单中检查每个字段的实际编辑方式；完整操作和字段变更影响见字段管理说明。

认识正面、背面、CSS 和反向样式

背面中的“正面内容”引用会先使用正面模板，再填充字段。这样可以复用题干结构；如果只想保留一部分问题信息，应在背面重新引用对应字段，不必复制整段正面代码。

字段、卡牌和运行设置怎样引用

正面和背面模板都可以使用“插入引用”。优先让编辑器生成引用，再在引用外编写 HTML 结构；这样可以避免字段名、@ 前缀和花括号写错。

字段还会携带语言和朗读状态等运行属性。普通模板应通过字段引用和字段配置使用这些能力，不要在模板中写死所有朗读按钮或语言。模板中的脚本、危险地址和不安全 CSS 会被过滤，不能依赖任意 JavaScript、外部脚本或页面全局对象。

格式化、条件和重复内容语法

格式化字段

多个格式化器可以从左到右组合，例如 {{@答案 | trim | fallback:'未填写'}}。未知格式化器会在保存校验中报错。

条件和列表

• _if="@解析"：条件不成立时不生成这个元素。
• _visible-if="config.darkMode"：保留元素但隐藏显示。
• _class-if="@重点:highlight"：条件成立时增加指定类名。
• _for="item in @列表"：为数组中的每项重复生成元素，并可引用 item 和 index。
• _tips：把元素标记为提示文字，用户关闭“显示提示文字”时自动隐藏。

条件支持 ! 取反，以及 ==、!=、>、>=、<、<= 比较。例如 _if="@等级 >= 3" 只在数值达到条件时显示。字段值为空、false、0、no 或 off 时按不成立处理。

让模板尊重用户的显示设置

学习设置会把用户选择传入卡牌运行环境，包括 7 档字体大小、默认中文/系统/衬线/无衬线/等宽字体、顶部/居中/底部布局、提示文字显示、背面挖空项显示以及仅显示背面。模板如果写死样式，可能让这些设置看似失效。

图片、视频、表格和代码块还应设置合理的最大宽度并允许内部滚动。不要依赖固定桌面宽度；同一个模板可能在桌面窄窗口、移动设备和不同字号下显示。

完整支持深色模式

应用进入深色模式时，卡牌表面会增加 dark 类，并把 config.darkMode 设为真。运行环境会提供基础深色文字、分隔线、代码高亮和背景，但模板自己的背景、边框、阴影和图片仍需要检查。

1. 先继承正文颜色。卡片根节点使用 color: inherit，不要给所有文字固定深色。
2. 为有色表面写深色覆盖。浅灰卡片、标签、边框和阴影必须提供 .dark 规则。
3. 检查富文本内联颜色。字段允许“字体颜色”后，用户可能保存只适合浅色背景的颜色。
4. 检查媒体和公式。透明图片、带白底截图、SVG、代码块和公式在深色背景上可能失去边界。
5. 分别预览正背面。正反模板还要分别检查正向和反向样式。

普通颜色差异优先用 CSS，例如 .dark .panel；只有元素结构在深色模式下确实不同，才使用 _if="config.darkMode"。结构重复会增加朗读、无障碍和维护成本。

把通用规则组合成一个基础卡模板

下面的实例只演示所有模板都能复用的字段引用、条件显示、提示文字、响应式尺寸和深色样式。先建立“问题”“提示”“答案”和“解析”四个字段，将“问题”和“答案”设为必填，并把“问题”设为标题。

正面模板

<article class="qa-card">
  <p class="qa-card__kind">{{catalog}}</p>
  <h1>{{@问题 | trim}}</h1>
  <p class="qa-card__tip" _if="@提示" _tips>
    {{@提示 | trim}}
  </p>
</article>

背面模板

{{front}}
<article class="qa-card qa-card--answer">
  <section class="qa-card__answer">{{@答案}}</section>
  <section class="qa-card__explain" _if="@解析">
    {{@解析}}
  </section>
</article>

CSS 样式

.qa-card {
  width: min(100%, 42rem);
  margin: 0 auto;
  color: inherit;
  font-family: inherit;
  line-height: 1.7;
  overflow-wrap: anywhere;
}
.qa-card h1 { font-size: 1.35em; line-height: 1.4; }
.qa-card__tip { margin-top: 1em; opacity: .78; }
.qa-card__answer { margin-top: 1.25em; font-size: 1.08em; }
.qa-card__explain {
  margin-top: 1em;
  padding: 1em;
  border: 1px solid #e4e7ec;
  border-radius: .75em;
  background: #f8fafc;
}
.dark .qa-card__explain {
  border-color: #343740;
  background: #202228;
}

这个实例不固定正文颜色和字体，只为说明区域提供必要的浅色与深色差异；宽度使用弹性限制，字号和间距使用相对单位。保存前还应把示例字段值替换为空值、长文本、媒体和公式分别预览。

选择正确的模板类型

前面的字段、引用语法、正背面结构、用户显示设置和深色模式是所有模板共用的基础。完成这些通用设计后，再根据学习行为选择模板类型；类型决定专用交互，但不会替代通用字段和样式规则。

当前可以直接新建的模板

模板类型会固定专用行为，模板编辑页只显示当前类型，不提供类型切换。不要把类型当作外观主题；选错类型时，应重新建立正确类型并处理卡牌字段映射。

牌组中的题库题型模板

选择题和判断题也是当前支持的模板类型，但“新建模板”窗口不直接创建它们。当牌组中存在这两类模板时，制卡表单会提供选项答案或正确/错误的专用编辑方式，模板管理仍可编辑其字段、正背面和 CSS。具体固定字段与专用语法见下一节。

题库模板怎样组织数据

题库模板是卡牌自身就带有作答结构的模板，和普通模板上配置的独立“测验设置”不是同一件事。选择题模板直接读取当前卡牌的题干、选项和正确答案；普通基础卡的测验则根据“问题字段”和“答案字段”临时生成题目。

选择题模板

答案含一个字母时按单选显示，含多个字母时按多选显示。选择题模板还提供以下专用引用：

判断题模板

判断题至少需要题干和答案字段。表格导入可以识别“正确/错误”“对/错”“true/false”和“1/0”等常见写法，并规范为“正确”或“错误”；直接制卡时仍建议始终使用统一中文值。

判断题背面同样可以使用 {{yourChoices}} 显示用户作答，并使用 {{answer}} 显示正确答案。

创建前先设计内容结构

1. 写出学习目标。明确用户在正面看到什么、需要回忆什么、背面怎样核对。
2. 选择模板类型。根据前面的类型差异决定使用基础卡、完形填空、正反模板或牌组中已有的题库模板。
3. 列出最小字段。例如“单词、音标、释义、例句、音频”，不要为极少数卡牌增加大量长期为空的字段。
4. 确定标题字段。选择稳定、简短且能区分卡牌的字段。
5. 标记必填字段。只把缺失后无法制卡的核心内容设为必填。
6. 准备测试数据。至少准备普通、空值、长文本、媒体、公式和特殊符号样本。

新建并保存模板

1. 进入“模板管理”。先检查是否已有可复用模板。
2. 选择“新建模板”。输入能说明用途的模板名称。
3. 选择模板类型。当前可以选择“基础卡”“完形填空”或“正反模板”；创建后不能在编辑页切换类型。
4. 打开“字段管理”。新增、命名、排序并配置字段。
5. 编辑正面和背面。使用“插入引用”生成字段引用，减少手写错误。
6. 编写 CSS。优先使用继承、相对尺寸和响应式布局。
7. 处理专用配置。正反模板还要编辑“反向卡牌样式”；需要额外练习时配置测验或连连看。
8. 逐项预览。检查正面、背面、布局、提示文字和深色模式。
9. 保存模板。“字段管理”“测验设置”和“连连看设置”中的保存只更新当前模板草稿，最后仍要保存整个模板。

安全编辑已有模板

1. 记录模板类型和卡牌数量。确认影响范围。
2. 导出配置备查。高风险调整前保留当前模板配置。
3. 检查全部引用。覆盖正面、背面、CSS、反向样式、测验和连连看。
4. 在同一次编辑中完成字段和代码修改。字段改名后，先更新所有代码引用，再保存整个模板。
5. 重新检查活动配置。编辑器会整理可识别的测验和连连看字段引用，但失效配置可能被移除，仍需人工核对。
6. 用真实卡牌验证。模板预览使用示例字段值，不能覆盖空字段、长文本、富文本和真实附件。

预览不能代替真实学习验证

先用模板编辑页检查结构

模板编辑页可以切换正面/背面、深色模式、顶部/居中/底部布局和提示文字，适合快速发现语法、溢出和配色问题。预览数据主要来自字段名或字段默认值，不代表真实卡牌内容。

• 正面是否泄露答案，背面是否保留必要上下文。
• 可选字段为空时，条件区块是否正确消失。
• 长标题、长解析、表格和代码是否溢出。
• 深色模式下的文字、链接、边框和状态是否清晰。
• 三个垂直布局下是否仍保持自然阅读顺序。

保存后再用真实卡牌检查行为

模板预览没有提供学习设置中的全部字体档位和字体族，也不能完整代替反向卡牌、答题状态、附件加载和正式学习流程。保存后至少抽查：

• 完形填空：包含一个和多个挖空项的卡牌。
• 正反模板：正向和反向卡牌各检查正面、背面。
• 选择题：单选、多选、缺失选项、用户作答和解析。
• 判断题：正确和错误两种答案及用户作答。
• 媒体和公式：正常加载、加载失败、窄窗口和深色模式。
• 用户设置：最小/最大字号、至少两种字体、提示开关、背面挖空项和仅显示背面。

普通模板的测验和连连看

普通基础卡、完形填空或正反模板可以额外配置测验生成规则：选择题、填空题和朗读题分别指定问题字段和答案字段。连连看则设置一组不同的关联字段。它们不会改变模板类型，也不会把普通卡牌转换成题库卡牌。

两类活动应分别配置和排错：查看测验设置说明和连连看设置说明。

导入和导出模板配置

“导出”把当前草稿中的字段、正背面、CSS 和选项配置保存为 .tpl-config.json，适合备查或在同类型模板间复用；它不包含关联卡牌和附件文件。“导入”只更新当前模板草稿，不会立即写入数据库。

• JSON 配置的模板类型必须与当前模板一致。
• 纯文本 .txt 只适用于基础卡：文件内容会作为正面模板，并建立一个“正文”字段。
• 导入前记录当前字段、反向样式和活动配置；导入会替换当前草稿中的对应配置。
• 导入后检查字段引用、题库固定字段、深色样式和资源引用。
• 配置文件可能包含复杂模板代码，只导入可信来源的文件。
• 完成导入后仍需保存整个模板，并用真实卡牌验证。

已有卡牌、复制和删除限制

模板配置导入导出不等于复制全部卡牌。模板存在关联卡牌时也不能直接删除；需要先决定卡牌应保留、迁移还是删除。

完成后的检查

• 模板类型与学习行为一致，题库模板的固定字段和值符合规则。
• 字段名唯一稳定，标题、必填、权限、TTS 和语言设置正确。
• 正面、背面、CSS 和反向样式没有失效引用。
• 条件、格式化器和列表语法能够通过保存校验。
• 模板继承用户字号和字体，并适配三种垂直布局与提示开关。
• 浅色和深色模式下的文字、背景、边框、媒体和状态均可读。
• 至少用普通、空值、长文本、媒体、公式和特殊符号卡牌抽查。
• 保存后在卡牌管理和实际学习中再次验证。

常见问题

为什么题库模板和“测验设置”看起来重复？

题库模板把题干、选项和正确答案直接保存在卡牌中；“测验设置”是从普通卡牌的两个字段临时生成练习。两者的数据规则和适用场景不同。

为什么保存时提示模板引用了未知字段？

正面、背面、反向样式或活动配置仍引用已改名或删除的字段。使用“插入引用”重新选择字段，并检查所有方向。

为什么用户调整字号或字体后模板没有变化？

模板可能在根节点或所有子元素上写死了字号、字体，甚至使用 !important。改为继承和相对单位，再测试 7 档字号。

为什么深色模式下出现白色区块或文字看不清？

模板的自定义背景和边框没有深色覆盖，或字段富文本保存了固定颜色。为自定义表面添加 .dark 规则，并检查字段样式权限和真实内容。

为什么显示“卡片模板语法错误”？

模板使用了不支持的表达式、方法或脚本语句。优先改用字段引用、格式化器和声明式条件；不要依赖任意 JavaScript。

为什么预览正常，实际学习仍异常？

预览样例没有覆盖真实卡牌的空字段、长文本、媒体或用户显示设置。用出现异常的真实卡牌结构重新测试正面、背面和深色模式。