记乎编辑器表格导入功能使用说明

表格导入适合把已经整理好的词表、题库、问答、完形填空或带图片音频的学习材料快速转换成记乎卡片。导入前请先确认当前牌组已经有合适的卡片模板，表格首行是列名，之后每一行对应一张卡片。

一、入口和基本流程

1. 打开记乎编辑器，进入目标牌组。
2. 点击卡片列表区域的“导入表格”。
3. 选择 .xlsx 或 .csv 文件，也可以点击“粘贴表格导入”直接从剪贴板读取表格文本。
4. 如果 .xlsx 中有多个工作表，先选择要导入的工作表。每次导入只处理一个工作表。
5. 选择要使用的卡片模板，并配置表格列和模板字段的对应关系。
6. 按需配置导入目录、资源目录和重复卡片处理策略。
7. 查看导入预检结果，确认可导入、会替换、会跳过、需修复的数量。
8. 点击“开始导入”。导入完成后，如有失败行，可以导出失败报告并按报告修正表格。

二、支持的文件和数据来源

三、表格格式要求

• 第一行必须是标题行，例如：问题、答案、音频、一级目录。
• 标题列不能为空，也不要重复。重复列名会在预检中报错。
• 每一行数据对应一张卡片。完全空白的尾行会被忽略。
• 模板的标题字段和必填字段必须有内容，否则该行会失败。
• 字段名、字段别名、字段备注与表格列名相同或接近时，编辑器会尝试自动匹配；仍建议在导入配置页人工确认一次。

四、字段对应和目录导入

选择模板后，导入配置页会列出模板字段。你可以把每个模板字段对应到某个表格列，也可以选择“<无>”让该字段为空。

目录有两种处理方式：

• 导入至现有目录：所有卡片导入到同一个已存在目录。
• 智能对应/生成目录：使用表格里的 一级目录、二级目录 等列自动查找或创建目录。

如果下载示例 CSV，会看到 一级目录、二级目录 两列。无需目录时可以留空或不映射。

五、重复卡片处理策略

编辑器会根据卡片标题判断是否已经存在同名卡片。导入前可以选择：

• 仍然导入：即使标题相同，也创建一张新卡片。
• 跳过导入：标题已存在的行不导入。
• 替换已存在卡牌：标题已存在时，用表格内容更新原卡片。

六、图片、音频、视频和文件资源

导入配置页中的“资源文件”用于处理表格里引用的本地文件或网络资源。资源可以出现在专门的图片、音频、视频、文件字段里，也可以内联写在普通问题、答案、释义等文本字段中。

资源路径支持三种写法：

• 相对路径：audio/hello.mp3 或 hello.mp3。需要先选择资源目录，编辑器会从该目录查找文件。
• 绝对路径：/Users/me/media/hello.mp3，编辑器会直接读取该文件。
• 网络 URL：https://example.com/hello.mp3，导入时会下载并保存为牌组资源。

选择资源目录后，本地相对路径会在预检阶段检查是否存在。网络 URL 不会在预检阶段下载，只在实际导入时处理。

七、普通字段内插入图片或音频

普通文本字段或 HTML 字段可以内联插入资源。推荐使用简易格式：

请听音频 (hello.mp3) 并回答问题。
观察图片 (cat.png)，写出它的英文名称。

导入时，编辑器会根据文件扩展名或 MIME 类型自动识别资源类型，并转换为记乎内部标记：

(hello.mp3)  →  [audio:导入后的资源名.mp3]
(cat.png)    →  [image:导入后的资源名.png]
(intro.mp4)  →  [video:导入后的资源名.mp4]

你也可以直接使用明确的内联标记：

[image:cat.png]
[audio:hello.mp3]
[video:intro.mp4]

如果没有选择资源目录，(hello.mp3) 这类相对路径会被保留为普通文本，不会尝试导入资源。选择资源目录后才会按资源处理。

八、完形填空导入

完形填空支持正式标记：

This is [hide:important].

为了便于在表格中输入，也支持导入用简易标记：

This is __important__.

导入时会自动转换为：

This is [hide:important].

使用完形填空模板时，每行至少需要一个 [hide:内容] 或 __内容__ 标记，否则预检会提示“需要使用填空项”。

九、选择题和判断题导入

选择题推荐使用标准列：问题、A、B、C、D、答案、解析。答案支持单选或多选，例如 A、AC、A,C、A、C。预检会检查至少有两个选项，并确认答案中的选项真实存在。

问题,A,B,C,D,答案,解析
哪些是元音字母?,A,E,B,C,"A,B",多选题示例

如果不想把每个选项拆成单独列，也可以使用简易 选项 列，每个选项单独一行：

问题,选项,答案
"2 + 2 = ?","A. 3
B. 4
C. 5",B

选项 列支持 A. 内容、A、内容、A: 内容、A) 内容 等常见写法。选项内容和问题字段一样，也可以写入 (cat.png)、(hello.mp3) 这类简易内联资源。

判断题使用 问题、答案、解析。答案可以填写 正确、错误，也可以使用 对/错、是/否、true/false、yes/no、1/0、√/×，导入时会统一保存为 正确 或 错误。

问题,答案,解析
太阳从东方升起,对,基础常识
水的化学式是 CO2,false,水的化学式是 H2O

十、示例 CSV

点击“下载示例 CSV”后，编辑器会根据你选择的模板生成一份示例表格。主字段中会包含内联图片、音频和完形填空的示例。你可以直接在示例文件基础上替换内容。

问题,答案,一级目录,二级目录
示例问题 (example-image.png) (example-audio.mp3) __示例填空__,示例答案,英语,听力

选择题模板的示例会包含选项和答案，例如：

question,A,B,answer,explain,一级目录,二级目录
示例选择题题干 (example-image.png) (example-audio.mp3),示例选项A,示例选项B,A,示例解析,示例一级目录,示例二级目录

判断题模板的示例会给出规范答案：

question,answer,explain,一级目录,二级目录
示例判断题题干 (example-image.png) (example-audio.mp3),正确,示例解析,示例一级目录,示例二级目录

如果示例中包含资源文件名，请把真实图片、音频等文件放到同一个资源目录中，并在导入配置页选择该目录。

十一、导入预检和失败报告

导入预检会在开始前检查表格结构、字段映射、必填字段、本地资源路径和重复标题。预检指标含义如下：

• 总行数：表格中准备处理的数据行数，不含标题行。
• 可导入：当前配置下可以创建或更新的行数。
• 会替换：重复策略为“替换已存在卡牌”时，将更新已有卡片的行数。
• 会跳过：重复策略为“跳过导入”时，不会导入的重复行数。
• 需修复：缺少必填字段、资源文件不存在、标题列异常等需要修正的行数。

导入完成后，如果有失败行，可以点击“导出失败报告”。失败报告会包含行号、错误原因和原始表格数据，便于修正后再次导入。

十二、常见问题

为什么看不到资源目录配置？
选择模板后，只要模板包含普通文本/HTML 字段或资源字段，就会显示资源目录配置。请先选择模板。

为什么相对路径没有被导入？
相对路径需要配置资源目录。未配置资源目录时，简易格式会保留为普通文本，避免误导入。

为什么 URL 预检通过但导入时失败？
URL 不会在预检阶段下载。实际导入时可能因为网络、权限、文件不存在或服务器返回错误导致失败，可在失败报告中查看原因。

字段内容里本来就有括号怎么办？
只有能识别为图片、音频或视频资源的 (...) 才会转换。普通括号文本会保持原样。

应该用 xlsx 还是 csv？
数据量不大且需要保留多个工作表时使用 .xlsx；希望跨工具稳定编辑、便于版本管理时使用 .csv。