uni-answer-sheet 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # 更新记录
 
+## 2.3.0
+
+- 新增“页面布局 → 使用反面”配置，对应 `CardDocument.duplex` 和 `initialization.layout.duplex`，默认关闭；旧文档未设置时保持单面。
+- 开启后先排满正面所有栏，再续到同一张纸的反面；最多正反两面，不生成空白反面，也不增加第二张纸。
+- 关闭反面保留完整内容，未排入的部分仍可通过完整内容窗口编辑；超出当前允许容量时阻止保存和坐标导出。
+- 支持反面直接编辑、预览、保存回显与识别坐标。`recognitionData.pages` 的 `pageNumber: 1` 为正面，`2` 为反面，坐标分别以所在面的左上角为原点。
+- 文档版本和插件协议保持不变，继续配合 `uni-editor@0.2.1`。双面 PDF 导出需要使用同步支持该配置的独立 PDF 服务。
+
+## 2.2.0
+
+- 所有版式固定一张纸，只在纸内换栏。超过容量的内容保留在草稿中，纸面和题块列表显示提示，可打开完整内容窗口继续编辑。
+- 超限时 `save()` / `validate()` 返回 `CONTENT_OVERFLOW`，`getRecognitionData()` 拒绝导出不完整坐标。删减后自动回排，全部容纳后恢复保存。
+- 支持载入原先多纸面的草稿，保留题目和富文本；须调整到一张纸内再保存。
+- 公共挂载 API、文档版本与富文本插件协议保持兼容，继续配合宿主显式安装的 `uni-editor@0.2.1` 使用。
+
 ## 2.1.0
 
 - 新增 `getRecognitionData()`，`save()` 成功数据新增 `recognitionData`；等待字体、图片及分页稳定后测量。

package/README.md

@@ -4,12 +4,12 @@
 
 `2.0.0` 使用全新的 DOM 插件 API，与原 `1.x` Vue 组件版接口不兼容。升级时请按本文重新挂载和注册富文本插件，旧版数据需转换为本文说明的文档格式。
 
-`2.1.0` 新增纸面全局坐标导出、识别标记、作业卡卷头和作答区域支持，沿用 `2.0.0` 的挂载及插件 API。详见 [更新记录](./CHANGELOG.md)。
+从 `2.3.0` 起可配置使用反面：所有版式仍限制为一张纸，默认只使用正面；设置 `duplex: true` 可在正面排满后使用同一张纸的反面。超出容量的内容保留在完整编辑窗口，保存及坐标导出会校验容量。挂载 API、文档版本和插件协议保持兼容。详见 [更新记录](./CHANGELOG.md)。
 
 ## 安装与依赖
 
 ```sh
-npm install uni-answer-sheet@^2.1.0
+npm install uni-answer-sheet@^2.3.0
 # 富文本由业务方单独安装，不会随制卡包自动安装。
 npm install uni-editor@^0.2.1
 ```
@@ -19,7 +19,7 @@ npm install uni-editor@^0.2.1
 本地验证未发布的版本时，从仓库根目录分别安装构建生成的 `.tgz` 文件：
 
 ```sh
-npm install ./artifacts/uni-answer-sheet-2.1.0.tgz ./artifacts/uni-editor-0.2.1.tgz
+npm install ./artifacts/uni-answer-sheet-2.3.0.tgz ./artifacts/uni-editor-0.2.1.tgz
 ```
 
 ## 原生 JavaScript / TypeScript
@@ -191,8 +191,8 @@ interface ValidationIssue {
 - 少选得分、选做数量、断句评分、作文格数/行数等题型约束。
 - 富文本结构、空公式、图片地址和可见图片加载失败。
 - 题卡合一的题干、材料、选项内容，以及所选填涂位置的对应关系。普通答题卡不要求填写题干，也不要求提供正确答案。
-- 纸面标题、不可拆分内容的纵向溢出，以及未分片编辑区域的横向溢出。
-- 定位点及识别区域是否在纸面内、标记是否重叠、纸面编码是否超出 8 面、二维码 ID 和学科识别编码是否有效。
+- 纸面标题、单张纸容量、不可拆分内容的纵向溢出，以及未分片编辑区域的横向溢出。
+- 定位点及识别区域是否在纸面内、标记是否重叠、二维码 ID 和学科识别编码是否有效。
 
 无法在 8 秒内完成输入/上传或稳定测量时返回 `EDITOR_BUSY` / `LAYOUT_PENDING`；容器隐藏或未设置有效尺寸时返回 `LAYOUT_UNAVAILABLE`，不会跳过布局校验。校验是当前数据和实际渲染的完整性检查，不判断学科内容或答案是否正确。外部图片/字体稍后失效仍需业务方管理。
 
@@ -200,7 +200,17 @@ interface ValidationIssue {
 
 ## 定位标记与识别坐标
 
-新建后的纸面自动显示四角定位点，上方 26×13 px、下方 13×26 px。纸面编码使用参考项目的三方格映射，最多区分 **8 个物理纸面**，不按栏计数；超过时保存返回 `PAGE_CODE_LIMIT`，不会循环使用编码。学科标记沿用参考项目 15 个标准学科的四方格映射，仅显示在正面。二维码编码内容为 `creation.exampaperId` 本身。
+新建后的纸面自动显示四角定位点，上方 26×13 px、下方 13×26 px。所有版式固定 **1 张纸**，两栏和三栏先在同一面内换栏，启用反面后才续排到背面。学科标记沿用参考项目 15 个标准学科的四方格映射。二维码编码内容为 `creation.exampaperId` 本身。
+
+A3 双栏、三栏每面有 2、3 个栏页码，反面接着正面编号。`recognitionData.pages` 每项对应一面：单面为 1 项，实际使用反面时为 2 项，均属于同一张纸。
+
+### 单张纸容量
+
+“页面布局 → 使用反面”默认关闭，对应 `CardDocument.duplex?: boolean`；旧文档缺省时也按关闭处理。初始化可传 `initialization.layout.duplex: true`，开关随文档保存及回显。开启后正面所有栏排满才续到反面，不生成空白反面；关闭不会删除反面内容，未排入的部分转入完整内容窗口。
+
+内容超出当前允许的面数时不新增纸张。纸面仅显示能排下的部分，边界和题块列表显示“未排入纸张”提示；点击“查看完整内容”打开可拖拽窗口，查看、编辑完整草稿。窗口标出未排入的内容，修改后实时重排。单独答题卡的题干及合并填涂区使用不同打印投影时，提示整个受影响题块，避免标注错误的正文截断位置。
+
+`getDocument()` 和 `onChange` 始终保留完整草稿，包括未排入的内容。`save()` / `validate()` 返回带 `blockId` 的 `CONTENT_OVERFLOW`，不提供可保存数据；`getRecognitionData()` 抛出 `AnswerSheetDataError`。完整内容窗口不参与纸面坐标测量。所有内容排入纸张后恢复保存及 PDF 导出。旧版多纸面文档可作为草稿回显，但同样必须调整到一张纸内才能保存。
 
 ```ts
 await sheet.initialize({
@@ -223,11 +233,11 @@ if (saved.ok) {
 坐标结构：
 
 - `version: 2`、`unit: 'px'`、`dpi: 96`、`origin: 'topLeftPaper'`。这是坐标协议版本，题卡文档的 `version: 1` 不变。
-- `pages[]` 每项对应一个物理纸面，`pageNumber` 从 1 开始；A3 的两栏／三栏属于同一项。
+- `pages[]` 每项对应同一张纸的一面，`pageNumber: 1` 为正面，`2` 为反面（仅 `duplex: true` 且需要反面时存在）；A3 同一面的两栏／三栏属于同一项。
 - 每面包含 `pageSize`、`anchorOrigin`、`anchorSize`、`panelSize`、四个 `anchors` 和 `regions[]`。`anchorOrigin` 仅记录左上定位点在纸面上的位置，与 `anchors.topLeft.x/y` 一致；它不再充当坐标原点。
 - **所有区域、单元格及四个定位点都使用所在物理纸面左上角 `(0, 0)` 的全局坐标**，向右为 X 正方向、向下为 Y 正方向。`rect: { x, y, width, height }` 已包含纸面边距和栏位置，可直接使用，不需要累加定位点或父区域偏移。
 - 每张物理纸面独立从 `(0, 0)` 开始；不包含视口缩放、滚动、上一张纸的高度或纸张之间的展示间距。密封线条码、顶部二维码仍在纸张内，坐标无需使用负值。
-- 区域通过 `blockId`、`questionId`、`partId`、`answerId`、`optionId` 关联源数据；`role` 区分 `region`、`cell`、`line`。跨页／跨栏区域分开记录并保留相同题目 ID，选做共享区域另有 `questionIds`。
+- 区域通过 `blockId`、`questionId`、`partId`、`answerId`、`optionId` 关联源数据；`role` 区分 `region`、`cell`、`line`。跨栏区域分开记录并保留相同题目 ID，选做共享区域另有 `questionIds`。
 - `sectionType` 包括 `ClassId`、`StudentId`、`IgnoreFlag`、`MultiChoice`、`Checkbox`、`FrameOnly`、`ScoreBox`、`QuestionChoice`、`Blank`、`PageCode`、`SubjectCode`、`ExamQrCode`、`ReferencePoint`。填涂区域包含实际单元格坐标，不依赖等宽假设。
 
 读取单元格示例：
@@ -270,7 +280,7 @@ await sheet.initialize({
 
 “添加题块”弹窗的纸面区域入口，普通答题卡显示“禁止答题区”，题卡合一显示“空白答题区”。区域可编辑文字、拖动调整高度、复制、删除和调整顺序。源数据存为 `kind: 'area'`、`areaType: 'forbiden' | 'editArea'`、`answerHeight`、`document`，保留参考项目 `forbiden` 的拼写。
 
-默认禁答区高 100 px，空白答题区高 200 px。禁答区与参考项目一致，不能拆分，高度不超过一栏，剩余空间不足时整块换栏；空白答题区可连续跨栏／跨页。它们不属于题目，不进入 `sectionInfoList`，需用完整保存数据回显。切换题卡合一时，与参考项目一样删除不适用的纸面区域。仅含纸面区域的卡不能作为完整试卷保存。
+默认禁答区高 100 px，空白答题区高 200 px。禁答区与参考项目一致，不能拆分，高度不超过一栏，剩余空间不足时整块换栏；空白答题区可连续跨栏，超出单张纸的部分保留在草稿中。它们不属于题目，不进入 `sectionInfoList`，需用完整保存数据回显。切换题卡合一时，与参考项目一样删除不适用的纸面区域。仅含纸面区域的卡不能作为完整试卷保存。
 
 ## 回显已保存的题卡