HTML 模板设计器

export4j-designer 是可选的独立本地应用，用 HTML 界面编辑现有 XML 模板及资源 ZIP。它调用现有 Java 引擎完成数据绑定、分页、预览和导出，核心库不依赖设计器。应用不加入 Maven 库发布、BOM 或库 API 基线。

启动

从源码构建需要 JDK 21、Node.js 22 或更高版本及 npm。Gradle 按锁文件安装并打包前端，从仓库根目录运行：

.\gradlew.bat :export4j-designer:run

Linux／macOS 将 Wrapper 换为 ./gradlew。启动后访问终端显示的本地地址，默认 http://127.0.0.1:8784/。端口可通过 --args="--port=8785" 修改；--port=0 选择可用端口。

也可以先构建安装目录，再运行启动脚本：

.\gradlew.bat :export4j-designer:installDist :export4j-designer:distZip
.\export4j-designer\build\install\export4j-designer\bin\export4j-designer.bat

安装目录包含应用、已打包前端、运行依赖、显式样例字体及许可，不包含 JRE；运行分发包不需要 Node.js。生成和转换不调用打印服务、打印机驱动、Office 或浏览器排版；浏览器呈现编辑界面及 Java 引擎预览。

便捷编辑与精确排版

“独立图文栅格”先提供可视布局选择器：通栏、两等分、三等分、左宽右窄、左窄右宽。插入后选中首格，双击正文或在检查器中选择“编辑内部内容”开始编写。新格包含空段落，没有示例正文。各格独立排版，内容不会串流，行高随内容变化，整行一起分页；需要连续正文自动流经各栏时，使用“正文分栏”。

已有内容可直接转为并排布局：多选同一文档／分节下相邻的直属段落或表格，插入“独立图文栅格”并保留“将所选内容并排”勾选。原内容按阅读顺序搬入各格，保留文字、图片、表格和 ID，无须复制重填。多余内容依次并入末格，缺少内容的格留空；不符合条件的选区显示具体原因。单选只作为插入位置，不会隐式移动正文。

选中格子后，检查器统一提供内部内容编辑、添加和布局操作。布局区显示当前格宽度，提供拆分、与右格合并和添加行；“本行布局”打开同一可视选择器。当前行内显示相邻两格的分隔线，拖动可调整比例，聚焦后按左／右键也可逐轨调整；“更多”提供“更窄／更宽”按钮。拖动格边界外的柄到另一格可交换位置，也可点击“向前交换／向后交换”。拖动显示比例或目标反馈，松开才写回，Esc 取消。正常滚动到另一页时可继续交换同一栅格中的格子；源码、会话或预览几何失效时取消拖动，预览未同步或失败时不应用拖动结果。

检查器显示当前行比例图，点击比例图可选择对应格；布局调整集中在同一检查器。减少格数时，原有内容按顺序并入保留的末格，整次操作可撤销。行号、起始轨、跨轨数及间距收在“高级轨道设置”，普通创作无须填写。项级循环／条件／片段的布局操作显示只读原因，不跨作用域移动内容。保存 ZIP 后仍保留栅格、项和原始子节点；第 14 个样例展示跨部分列、偏移及正文分栏组合。语法与边界见栅格指南。

“正文分栏”组件支持 1～3 栏、pt 栏距、宽度比例和平衡，列内段落／表格可在画布直接编辑。双栏、三栏内置样例包含通栏表格和图片，再恢复同设置分栏。选中分栏的直属段落后，检查器的“更多操作”提供“插入通栏表格／图片”；正在编辑时，“光标处通栏表格／图片”按当前光标拆段，保留前后正文及行内格式，再恢复相同分栏设置。完整动态节点可作为块间边界，不能把循环／条件内部子节点拆出作用域。语法、保存和跨格式限制见正文分栏指南。

画布上方可随时切换，两种模式共用 XML、测试数据、资源及撤销记录，不会产生两份模板。

模式	用途	显示和刷新
便捷编辑（默认）	编写正文、选择文字和调整样式	浏览器即时呈现模板原文和变量标记；活动输入不逐键请求后台，完成编辑后校验并更新分页。字体位置及换行属于近似显示
精确排版	核对最终换行、分页及输出效果	使用 Java 引擎绑定测试数据并排版；文字草稿经短暂防抖更新预览，编辑器和光标保留

画布单击选择，双击段落、标题、列表项或行内单元格后原位输入；单个文字元素选中后也可按 Enter／F2。同页、同一正文区域内相邻的普通段落和标题使用连续文字编辑区；同一块模式单元格、栅格项或正文分栏中的相邻段落也可连续编辑。可跨段移动光标、选择文字，以及在段首按 Backspace 或段尾按 Delete 合并段落，不跨单元格或循环作用域拼接内容。Enter 拆段，标题拆出的新段落使用普通正文；Shift+Enter 插入换行，Ctrl+Enter 完成编辑。行内单元格、列表项和固定框单独编辑，行内单元格及固定框内 Enter 使用换行。表格格间导航和继续编辑见容器内部编辑。

选中文字后，在选区附近显示浮动格式工具条，提供粗体、下划线、删除线、颜色和字号；收起选区后隐藏。变量、图片及页码字段保持结构对象，跨段编辑保留未修改的段落属性与混合格式。编辑区的撤销处理本次文字输入，完成后工作台撤销可恢复已提交的修改。单段页眉／页脚也可双击正文编辑；复杂区域保留结构树和 XML 入口。

一个段落跨越多页时，编辑区显示“跨页段落 · 编辑完整原文”，修改作用于整个源段落；使用键盘定位需要编辑的文字，当前不按页内片段还原精确光标位置。

顶部“插入”按“文字”“布局与容器”“分页与引用”分组。选中组件后，框旁的“在前面插入”“在后面插入”打开画布菜单，按“文字”“布局与容器”“分页”分组。两处的“布局与容器”均提供表格、数据列表、数据表格、正文分栏和独立图文栅格；数据控件打开数组绑定对话框，栅格打开布局选择器。新段落或标题直接进入文字编辑，输入替换默认文案。“组件操作”提供创建副本、调整顺序和删除等命令；Esc 关闭菜单。画布菜单支持方向键、Home／End 和 Enter。

空白处拖动框选，Ctrl／Shift 支持多选，无须切换选择／文字工具。选中组件后可直接拖动拖柄，或在正文中按住约 350 毫秒后拖动；提前松开或在触发前移动超过 6 px 会取消待触发的拖动。拖动中显示移动预览，自动占位组件同时显示插入线与占位框，固定组件靠近其他对象或页面的对齐位置时显示吸附线。按 Esc 或收到指针取消会放弃本次操作，结果仅在松开时写回 XML。拖动始终遵循组件自身的排版属性，不自动转换为固定位置。

插入、排序、位置和尺寸等修改先在画布与属性中显示，再由 Java 引擎异步校准精确版式；等待校准时可继续选择、文字编辑、撤销，以及用“上移／下移”等按文档结构执行的命令调整顺序。依赖画布几何的拖动、缩放、旋转和固定组件方向键移动，须等到“版式已同步”后操作；操作中源码、测试数据、资源或预览失效时取消本次操作，正常滚动到另一页不会取消。校验失败会保留修改并显示原因，修正后可重试。导出模板前同步当前合法源码，测试导出按实际数据和所选策略检查并生成文件。

工具条将版式状态分为“正在校准版式”“版式校验失败”“版式待更新”和“版式已同步”。只有预览成功，且结果对应当前模板源码、测试数据及资源，才显示已同步；预览失败时保留上次有效画布并显示失败原因。过期请求或旧文档会话的结果不会把当前草稿标记为成功。

添加或替换资源前会保存活动文字草稿；资源写入期间暂时停止正文输入，完成后继续编辑，避免资源响应覆盖同时输入的文字。普通版式校准不锁定文字编辑。

便捷编辑中，换行或放大文字使编辑区增高时，同页后续正文临时向下让位，页脚位置保持固定。这是浏览器的即时编辑反馈；完成编辑后由 Java 重新计算真实换行、分页和后续内容位置。

“位置与尺寸”中的“排版方式”是组件属性：

排版方式	拖动及键盘操作	正文处理
自动占位（默认）	拖动显示前／后插入线并调整源码顺序；也可用“上移组件／下移组件”或 Alt+↑／↓	保留正文占位，前后内容自动补齐；普通方向键不会转成固定位置
固定位置	自由拖动；选框整条边缘及角点缩放；检查器输入 pt 坐标／尺寸，方向键移动 1 pt，Shift+方向键移动 10 pt	“正文相遇时”选择遮盖正文或上下避让；旋转控件位于选框右侧

顶层段落、图片段落和表格可显式切换为固定位置，以纸张左上角定位。动态表格、列表、循环和条件容器按整体排序，保留绑定、条件和模板结构；单元格仍可双击编辑，不能把某个已展开数据项误当成独立源组件。多选同级自动占位组件时作为有序块排序，多选固定组件时整体平移。将固定组件恢复为自动占位时，按其当前页面及纵向位置放回邻近正文组件。

固定组件的“遮盖正文”不预留正文空间，允许重叠，由图层顺序决定显示先后；“上下避让”保留对象上方的正文，遇到对象时移至其下方继续排版。避让覆盖正文全宽，不提供对象左右的环绕排版。该属性写入模板的 body-flow，Java 引擎预览及 PDF／SVG／PNG 输出使用同一排版结果。

未旋转的固定表格仍可单击选择整表、双击编辑单元格，合并单元格使用实际排版几何定位。旋转后的表格使用属性或节点 XML 编辑内容，画布不叠加未经旋转的单元格编辑框。

固定框宽度可固定或填满右侧剩余空间，高度可固定、随内容增高或填满下方剩余空间；内容超过可用页面会报错。物理页 0 表示每页，正数指定文档物理页；缺少目标页时在声明节内补足，仍受页数预算限制。包含生成目录页的文档暂不接受显式物理页选择或上下避让。详见图层 API和架构决定。

画布获得焦点时可粘贴剪贴板 PNG／JPEG，图片字节加入模板资源并随 ZIP 保存。图片保留当前容器及数据作用域；向已有固定框内粘贴时加入该框内容。所有位置均由 Java 引擎测量新图片段落的实际可用宽高，再等比缩放，已有小图的命中宽度不会限制新图。测量计入页眉页脚预留、脚注、正文避让区域、段落间距及“与下段同页”链；固定页区、栅格项及不可拆分的表格行还保留已有和后续内容所需高度。表格同时计入内边距及重复表头，嵌套单元格可利用较高邻格留下的内部空间。无可用行空间时，在提交图片资源前拒绝。资源与图片段落一次提交，撤销／重做同时恢复二者；任一候选验证失败时，不留下新资源或部分源码。不支持的结构位置、禁止块内容的表头格，以及含条件样式的行内格转换会明确拒绝，不将图片移到文档末尾，也不丢弃样式规则。

固定框及旋转在 PDF／SVG／PNG 中保留。测试 DOCX 等格式时，无法映射的定位和角度仍按所选损失策略拒绝、警告或忽略；便捷编辑不会改变各格式的真实能力。

双模式、画布直接编辑及独立输出证据见阶段一百一十三。

容器内部编辑

插入表格、数据列表、数据表格或正文分栏后，设计器进入首个可编辑内容：表格进入单元格，数据列表进入项目模板，正文分栏进入内部段落。再次选择容器时，双击或按 Enter／F2 可进入内部内容；双击具体文字或单元格则编辑该处，不必在结构树中逐层寻找。

检查器统一显示当前节点的属性、正文、直属子内容及容器操作。点击子内容逐层进入，用检查器顶部面包屑返回任意祖先；需要原位输入时使用“编辑内部内容”。表格按当前单元格定位，栅格按独立项定位，正文分栏按内部内容定位。双击进入表格或栅格后，单击同一容器内其他格可继续编辑；单击外部或完成编辑后退出。原位编辑保留容器结构，内部修改不会变成外部正文。

在表格原位编辑区中使用 Tab／Shift+Tab 切换到下一格／上一格，按源表头和正文行的真实单元格顺序导航，合并格只访问实际锚格，数据表格不重复遍历展开的每条记录。选中变量标记后仍可切格；没有输入的导航保持原源码。到首末边界时提交并退出，不隐式添加行，也不增加数据记录。块模式单元格中的相邻段落可以连续选择、拆分和合并；行内单元格的 Enter 保持换行，需要多个段落时通过“添加内容 → 文字段落”显式转换。中文输入法组合输入期间不拦截 Tab。

检查器的“添加内容”打开“在容器内添加”对话框，可向当前单元格、栅格项或正文分栏加入文字段落、图片或表格。原有内容保留；向行内单元格加入块内容时，原文字及行内对象先保留为第一个段落，再追加新内容。含 style-if 条件样式的行内格须先明确移除条件规则才能转换，设计器会说明原因，不自动丢弃规则。原有正文分栏和栅格的嵌套限制继续适用。

普通表格在检查器的“行列与合并”中按当前格提供上／下插行、左／右插列、删除当前行列及“选格与合并／拆分”；不再重复提供另一套结构操作面板。操作支持统一撤销／重做。增加列同步更新表头和正文，至少保留一行正文和一列；删除正文行不会删除表头。含合并格的表格也可安全增删行列：插入位置穿过合并范围时扩展跨度，删除覆盖行列时缩减跨度；删除纵向合并的首行时，将仍需保留的锚格及内容移到下一行。真正被删除的节点若被外部引用，须先调整引用。顶部与画布的“插入表格”使用同一个默认结构，均包含真正的表头和正文行。

选中表格或单元格后，画布按 Java 引擎给出的单元格外框显示相邻列分隔线，不用文字命中框猜测内边距。拖动时显示两列的 pt 宽度，松开才应用；分隔线获得焦点后，左／右键调整 1 pt，Shift+左／右键调整 10 pt，Esc 取消拖动。展开检查器中当前列的 pt 数值，可直接输入精确列宽。调整作用于当前列与相邻列，保存为显式固定 pt 宽度；其他列的声明保留。预览尚未同步、旋转表格、同页多实例或缺少足够单元格边界而无法确定几何时，不提供拖柄及精确输入，仍可在属性／XML 中配置列声明。

选中单元格、栅格项或正文分栏中的直属段落／表格后，可用“复制当前段落／内部表格”和“删除当前段落／内部表格”明确操作内部内容，外层容器保留。正在输入时须先完成文字编辑，再执行这两个命令。正文分栏和栅格项至少保留一个内容块；表格单元格可清空块内容。删除被外部引用的内容会明确拒绝。

在画布正文编辑区粘贴含 HTML 表格的剪贴板数据时，优先使用剪贴板中的纯文本；仅有 HTML 时，按源行列转换为 Tab／换行分隔的文字，并保留格内段落换行。该操作写入当前正文，不自动新建表格，也不将二维数据分发到多个目标单元格。

数据表格 rows 只保存一个正文行模板。进入某个已展开记录的单元格后，修改的是对应模板，所有记录都会使用新内容；可以调整模板列，记录数量和顺序仍由数组决定。数据列表 list 同样只保存一个项目模板，可编辑正文、变量及格式；新增实际项目应修改数组，不向唯一项目模板旁追加副本。

绑定数组为空时，模板结构及内部内容选择仍可用。没有可显示的画布对象时，编辑入口展开检查器并聚焦正文编辑器，可直接修改模板，不会为了显示内容向数组加入假数据。随后加载真实测试数据再检查排版。操作与限制见容器编辑交互验收、编辑流程补齐验收及后续编辑流程验收。

模板逻辑与检查器

检查器顶部的面包屑显示“文档 → 容器 → 子结构 → 当前节点”。从文档或任意容器的内容列表点击直属子项，即在同一检查器查看、编辑；点击面包屑返回上级。条件、循环、列表、表格与栅格使用这条相同路径，文档结构树保留全局概览。没有独立逻辑侧栏，也不在画布工具条重复列出内部层级。

画布只显示当前数据的排版结果；未命中的条件分支、空数组中的模板仍在检查器内容列表中可见。条件检查器直接显示字段路径、比较方式、比较值和当前测试值；可手写路径，或展开字段搜索选择变量。支持等于、不等于、大小比较、文本包含及布尔判断；数字按十进制精确比较，不执行代码。已有根数据的测试值修改后自动预览，无须点击更新按钮；连续输入保留焦点和光标，输入法组合结束后预览。

点击“添加条件分支”，依次配置 status = 1、status = 2、status = 3；最后的“其他情况 / other”为兜底。各分支可以使用不同字段和比较方式，从上到下判断，仅显示第一个命中分支。后续分支可独立删除，保留后续条件及 other，支持撤销；首分支须保留，可直接修改其条件和内容。分支中的“添加下级条件”可继续嵌套，仍在同一检查器通过面包屑导航。

多分支保存为原有 else 内嵌 if 的条件链；复杂 else 中的其他内容保持原结构，不会为显示成平铺列表而搬移。新增分支最多 16 个，同时受整个文档既有 32 层 XML 深度和结构预算约束，超限拒绝且保留原内容。语法与数据类型见比较条件。

“满足条件”和“其他情况”分别预览直属正文，点击正文就在同一检查器编辑；点击分支标题可进入完整内容列表，缺少另一分支时可添加。每个分支最多预览 40 项，其余进入分支查看。分支和数据循环的“在此添加内容”可追加段落、图片或表格；顶部“插入 → 模板逻辑”创建条件或循环，取消保持原模板及数据。

检查器显示当前节点的正文或数据路径，结构容器的直属子内容保持展开，段落中的行内结构默认折叠。题注、交叉引用前缀和注释使用纯正文编辑。循环路径／别名、片段引用／前缀、列表标记、固定框尺寸模式与正文避让、目录／书签和已声明样式等提供对应属性。纯结构节点不显示不适用的位置与尺寸。未提供专用控件的结构仍可通过已有属性和“节点 XML”编辑；这不等于所有 XML 语法都已有可视化编辑器。

表格的行列与合并、栅格的本行布局、内部内容的复制／删除及通栏插入均归入检查器。选择或切换容器不会改变画布工具条高度。窄窗口使用临时检查器，同一面板内下钻和返回；Esc 关闭临时面板并返回打开它的控件。

选择复用片段后，点击“编辑片段内容”打开该资源的 XML。应用前会编译并排版完整候选模板；失败时保留输入和原资源，有效修改同步影响所有引用，支持一次撤销。取消不改资源；编辑期间资源已变化时需重新打开，避免覆盖更新。片段内容目前使用 XML 编辑器。

属性和正文草稿实时预览，切换节点、保存或导出时提交有效修改。新增入口与片段失败保护的验收见模板逻辑与检查器验收。

变量与数组绑定

检查器的“正文变量”直接列出已用引用、路径输入、测试值及字段搜索。先把光标放到插入位置，或选择要替换的文字，再选择字段或手写路径，点击“插入到正文”。点击已用变量可修改路径，再点击“更新变量引用”；只更新选中的一处引用，保留周围格式、链接及行内对象。最多列出 200 处引用，其余仍可在正文编辑。画布原位编辑区的“插入变量”沿用变量选择器。模板中的变量在预览和测试导出时读取测试数据，不会被已绑定的结果覆盖。

已有根数据的文字、数字和布尔测试值可以在检查器直接编辑，输入即更新数据草稿并自动预览；多行文字使用多行输入框，数字保留 JSON 原始数值精度。尚未输入完整的数字保留在输入框并提示原因，预览使用最后一个有效值。导航、导出或撤销时，数据与正文／条件草稿一起提交，连续输入可一起撤销；未编辑的字符串保留原有转义与换行 token。循环别名按每条记录取值，面板说明其数据来源；修改具体记录或添加缺失字段仍使用测试数据面板，不批量改写循环记录。

选择器只显示字段路径、类型和可用作用域，不展示字段值。可以选择已有字段，也可手写 ASCII 点路径，如 patient.name。手写时不填写 ${} 或表达式。字段枚举结合当前节点外层的 list、rows 和 each 别名；同名别名以内层声明为准。数据表格的表头使用容器外部作用域，不能引用本表当前行的别名。

插入“列表项”“数据列表”“表格”或“数据表格”时，先根据是否需要按数组重复选择类型：

类型	源节点	内容与数据的关系
列表项／编号	bullet／numbered	一个静态列表项，正文可含变量；不会因数组长度自动增加项目
数据列表	list	按数组逐项生成列表项，内部模板定义每项正文
表格	table	行与单元格由模板明确声明；单元格可含变量，行数不由数组自动扩展
数据表格	rows	按数组逐项生成模板行；表头单独使用外部数据

从“布局与容器”插入数据列表或数据表格后，对话框要求填写数组路径、迭代变量和重复内容字段。例如，数组路径为 products、迭代变量为 item、重复内容字段为 item.name 时，每项正文使用 ${item.name}；数据表格的默认迭代变量为 record。创建后可继续编辑模板正文，并在容器属性中调整 items 和 as；数组路径下方可展开“选择数组字段”直接搜索、选择外层作用域中的数组。

数组为空时仍可手写字段路径，如 record.code；空数组不会生成重复正文或数据行。无法推断记录类型时，对话框提示填写实际字段路径，或先加载一条真实测试记录。对象数组使用 record.code 等字段；仅当数组成员为文字、数字或布尔值时，才直接使用 record。没有可用数组时，对话框可提供示例数组；确认使用提示的路径后，模板和示例 JSON 一起写入，可一起撤销。新增字段保留已有 JSON 原文及数值 token，大整数、长小数和指数不会经过浏览器浮点数重新序列化。取消对话框不新增模板节点或示例数据。

测试数据与模板分别保存。“文件 → 另存测试数据 JSON”下载配套数据；重开模板 XML／ZIP 后，通过“文件 → 加载测试数据 JSON”载入另一份数据，再核对预览或测试导出。模板保留变量、数组路径、别名及样式，JSON 不写入模板 ZIP。相关操作与边界见变量和数组绑定交互验收。

查看检查结果

“诊断”面板先显示本次预览或导出检查的结论，再逐项说明原因、影响和建议。备用字体属于外观提醒：文字仍保留，但字形、宽度和换行可能变化；字符级记录按类型合并，记录数不等于错误数。缺字替换会单独提示，应补充字体并核对文字。涉及位置可展开，点击元素定位到设计画布，报告保持展开。

测试导出时，报告说明哪些内容会被简化或移除；选择“忽略警告”也不会消除这些变化。点击下载会自动检查并按策略继续或拒绝，报告不会改写原模板或测试数据。未知提示明确要求核对，不自动视为安全。“技术明细”和“下载技术报告”保留原始信息，用于进一步排查。

编辑、保存与重开

1. 侧边工具栏提供文档结构、项目资源、测试数据及诊断；点击后在紧邻工具栏的完整侧栏中显示内容。中间主编辑区提供画布和 XML，右侧检查器编辑元素属性。顶部“文件”菜单提供“新建 → 空白文档／从样例”、打开、“导出模板”和“测试导出”；顶部工具栏统一提供撤销／重做、插入、页面设置和专注模式。可打开自己的 .xml 或普通模板 .zip。
2. 在结构树或画布选择节点。段落、标题、列表项和行内单元格的“正文内容”可直接输入并设置粗体、颜色、字号及装饰；图片、链接和字段保持独立对象。ID 位于属性首位，完整结构仍可在“节点 XML”中编辑。
3. 从插入菜单选择文字、布局容器或分页与引用元素。在画布纸张或结构树空白处右键，也可按所在位置插入；正文流中的实际位置由排版决定。数据列表和数据表格使用数组绑定对话框，具体区别及字段填写见变量与数组绑定。组件和资源可拖到画布的前／后插入线；结构树用于同容器排序，也可上移／下移。循环／条件展开的内容映射回源模板，排序时选择其结构容器；数组内数据的先后在绑定 JSON 中调整，不将某个展开项误当作独立源节点。
4. “XML”编辑完整源码，“测试数据”编辑独立 JSON。属性、XML 和 JSON 输入后短暂防抖，自动调用 Java 引擎编译、绑定并真实分页，无须点击应用；画布正文按所选编辑模式刷新。非法草稿在状态栏和诊断面板显示原因，画布保留上一次有效预览；修正后自动恢复。源代码的变量、条件和循环不会被已绑定正文替换。
5. 通过“导出模板”下载完整 ZIP 或仅 XML；测试数据通过“文件 → 另存测试数据 JSON”单独下载。重开 ZIP 后，通过“文件 → 加载测试数据 JSON”加载配套数据，再预览或测试导出。数据不写入模板 ZIP，单份模板可继续绑定不同数据。

“导出模板”是设计成果的交付入口，默认选择完整 ZIP，保留原始 XML、字体、图片、可复用片段及许可，可在设计器中继续编辑或交给库 API 绑定数据。选择“仅模板 XML”只下载源码，变量、循环、条件和样式仍保留；引用的字体、图片和片段须另行提供。下载使用当前合法草稿，不把预览中已绑定的内容写回模板，也不要求测试数据包含全部绑定值。仅下载 XML 不将未保存的资源标记为已保存。

“测试导出”使用当前测试数据生成 PDF、DOCX、HTML、Markdown、SVG 或 PNG，用于检查绑定结果、排版和格式兼容性。生成的文件是本次测试结果；保存和复用设计应使用“导出模板”。

打开 XML／ZIP 或新建文档后，旧画布及命中区域立即清空，再自动预览新模板。旧会话中尚未返回的预览不会覆盖新文档。打开模板后若尚未加载配套数据，缺值或布局错误会显示在诊断中，不继续显示上一份模板的内容。

实时预览不修改历史或工作区版本。切换结构节点、保存、导出及执行结构操作时，合法草稿作为一次修改进入工作台撤销历史；已提交文字、插入、排序、属性和坐标修改可按实际操作顺序撤销／重做。活动文字编辑器中的 Ctrl+Z 处理当前文字会话，完成后使用工作台撤销。无效草稿不会覆盖已保存状态，新修改清空重做分支。Windows 换行在文本框中的显示规范化不会单独产生历史记录。纯文字面板不会把含子元素的混合内容拍平成正文。

工作台本地源码／数据历史最多保留 100 步，服务端项目及资源快照最多保留 8 步。资源导入后继续编辑文字，仍可按实际顺序撤销到资源操作，并重做恢复；跨资源恢复先验证完整候选，失败时不推进历史或替换工作区。较早资源超出服务端保留范围时，工具条明确显示撤销边界，本地历史也不再承诺恢复该资源。活动文字会话、工作台历史和下载到磁盘的文件各自独立。

保存包沿用 XmlTemplateBundle，没有新增文件类型。结构修改可能规范化 XML 的引号、属性次序及换行，保留内容语义、注释和模板表达式；没有修改源码时不会为了预览重新序列化它。结构应用检查 XML 和编译错误；数据缺值、引用解析及布局失败在预览／导出时报告，草稿可继续修正。

每个进程只有一个工作区；不同标签共享它。版本检查拒绝旧标签的覆盖请求，收到工作区变化提示后需重新加载。文件标签中的修改状态只反映当前服务会话，不保证浏览器已将文件保存到磁盘。关闭服务会清空内存工作区，不会自动恢复草稿；继续编辑前应下载模板和配套数据，已下载文件不受影响。

新建文档

“文件 → 新建”提供两个入口：

• 空白文档：一张 A4 页面、42 pt 页边距和空绑定数据；只保留内置字体与许可，不带样例文字或图片。可以从插入菜单或画布右键开始编写。
• 从样例：打开样例选择窗口，每项显示名称与用途。选择后创建独立模板与配套虚构数据；取消选择保持现有工作区。替换未保存内容前会要求确认。

内置巡检报告、密集静态表单、分页长表、目录与交叉引用、药品不良反应报告表，以及服务合同、个人简历、用户手册、报价单、会议纪要和项目周报，共十一套样例。后六套为多页业务文档，涵盖条款与验收矩阵、带照片的双栏履历、安装运维手册、分组长报价、讨论决策台账和预算风险周报，可编辑复杂表格、富文本与条件样式。合同每页页眉包含示例公司 Logo、版本与编号；照片与 Logo 可在资源面板替换，完整模板 ZIP 保留图片及来源许可。源模板、测试数据及无界面生成命令见常用文档模板。新建操作也可通过 Ctrl+K 查找。新文档清空上一份文档的撤销历史，模板 ZIP 与数据 JSON 仍分别保存。

药品不良反应报告表采用 A4 纵向密集网格、分区标题、18 列用药表、多级合并表头和动态页码。默认虚构数据自然排为三页：患者及怀疑用药、续接注释与反应及报告信息、备注。模板不含分页符，通过显式字号、窄列换行、行距与填写区内边距形成版式；修改文字长度或增加记录会正常重排，较短数据可缩为两页。内置字体、单元格顶部对齐与表头底色可能使外观与其他字体或表单不同，不承诺像素一致。

模板和绑定数据分别位于 export4j-designer/src/main/resources/designer/samples/adverse-reaction.xml 与 adverse-reaction.json，属于项目自编样例并采用 Apache-2.0。患者、疾病、怀疑用药、检验、反应经过及报告信息可在“测试数据”中修改；疾病及用药使用 rows，可为空的检验记录使用 each。合并用药空表可通过编辑 XML 或表格工具补充记录。所有数据均为虚构，不含真实病例、联系方式或用户原始文件；该样例用于版式与数据绑定演示，不作为监管申报格式或医学判定依据。勾选记号属于静态正文，保持可编辑模板，不生成交互式 PDF 字段。

工作区导航

界面采用 IDE 式工作台布局：顶部“文件／编辑／视图”菜单管理文档、撤销与布局。结构、资源、测试数据和诊断使用垂直工具标签，面板紧邻标签占用完整侧栏高度；默认位于左侧，面板标题旁的停靠按钮可将工具栏与面板一起移动到右侧。主编辑区显示模板文件标签、未保存标记及设计／XML 切换；标签下的元素路径可点击返回祖先节点。结构树优先显示稳定 ID，源文字与类型作为补充，完整标签可悬浮查看。

侧边面板与属性检查器可拖动分隔条调整宽度；分隔条支持方向键、Shift 加快及 Home／End 边界调整。点击当前工具标签或标题旁的收起按钮隐藏侧栏，工具标签保持可见；点击其他工具标签直接切换内容。工具标签支持上／下键切换及 Home／End。Ctrl+B 切换侧边面板，正文富文本中的 Ctrl+B 保留加粗行为。专注模式隐藏内容侧栏，仍可通过工具标签重新展开；“视图 → 恢复默认布局”恢复左侧文档结构与右侧属性检查器。浏览器仅保存停靠方向、活动工具、面板显隐和宽度，不在布局偏好中保存文档内容。

XML 与 JSON 编辑器提供行号、高亮、当前行提示和底部行列位置；文本选区同时显示选中字符数。侧边工具切换及布局调整保留代码草稿与当前画布，文档内容继续由 Java 引擎处理。

结构树用中文类型名、图标和 ID 显示元素。表格与列设置默认折叠，点击箭头展开；搜索匹配类型、ID 和源文字，同时保留祖先路径。点击画布中的元素会展开对应祖先。树内使用上／下键移动焦点、左／右键折叠或展开，Enter 选择；“折叠全部”保留根文档入口。原有 Ctrl／Shift 多选、拖动排序及右键菜单继续有效。

属性检查器先显示 ID 和可直接编辑的正文，再按基本属性、数据与引用、文字样式、间距、分页及变换分组。复杂分组默认折叠；空值沿用继承，多选属性不一致时显示“多个值”。属性提示跟随名称，悬浮或键盘聚焦时可查看。未覆盖的属性仍可通过高级属性和节点 XML 编辑。修改属性后切到“XML”或打开“测试数据”面板，会先提交合法节点草稿；失败则保留当前编辑器和错误原因。

使用 Ctrl+K 搜索插入、导出模板、页面设置、编辑视图和测试导出等操作，方向键选择、Enter 执行、Esc 关闭。右上角“导出模板”或 Ctrl+S 打开模板导出窗口，可选择完整 ZIP 或仅 XML；“测试导出”用于检查生成效果。测试数据仍从文件菜单另存；专注模式隐藏侧栏，保留当前画布图片和滚动位置。

窗口宽度不超过 1100 px 时，侧边工具面板和检查器按需以覆盖层展开，默认将空间留给画布，同一时间只打开一侧。点击关闭、遮罩或按 Esc 可返回画布，键盘焦点回到打开面板的控件；打开期间 Tab 保持在面板内。窄屏临时开合不改写桌面布局偏好，扩大窗口后恢复原有面板显隐和宽度。窗口或面板使纸张显示宽度变化时，画布文字和编辑选框同步缩放。

诊断面板合并同类排版诊断。例如逐字备用字体记录汇为“已使用备用字体”，并保留可展开的原始报告；标签中的数字是诊断类别数，不再逐字计数。真正的草稿错误仍显示原因并保留上次有效画布。导出损失不与字体备用说明混为一类，完整处理报告继续可下载。工作区交互验收见阶段一百一十二。

侧边工具面板

结构、资源、测试数据和诊断复用一个侧边面板，设计画布与 XML 始终占据主编辑区。三个工具的内容不放在画布下方，窗口变窄时也保留侧边展开方式。项目资源提供图片、字体、可复用片段与许可；测试数据保留 JSON 编辑器；诊断显示检查结果、影响和建议。可通过“视图”菜单或命令搜索打开指定工具。

修改测试数据会自动更新画布；切换工具、收起面板、调整宽度或左右停靠保留草稿，不重新生成预览。诊断定位切回设计画布并选中对应元素，同时保持侧边报告及展开位置，便于对照。旧的 ?view=data、?view=diagnostics 链接会打开画布及对应侧边工具；当前链接用 view 表示主编辑区、panel 表示侧边工具，panel=none 收起面板。

连续画布、快捷键与右键菜单

实际引擎页面沿纵向连续排列，直接滚动即可查看所有页；页码选择和上一页／下一页只是滚动定位。显式分页符显示为可选择的辅助标记，自动分页／分节边界显示为虚线；辅助标记不写入导出文件。仅加载可见区域及邻近页的预览图片，远离视口后释放图片 URL，页面几何和命中区域仍保留。

连续的静态列表项在画布上可作为一个列表选择；动态列表的同源列表项按每页合并为一个外框，跨页不画跨越纸张的框。单击动态列表选中容器并编辑绑定属性，双击列表项编辑该项模板正文。结构树可逐项选择，Ctrl 点击追加／移除，Shift 点击选择同级范围；画布中的 Ctrl／Shift 点击也可扩展选择。多个同级节点可拖动或用方向命令作为一个有序块移动；批量属性面板只显示所选类型共有的具名属性，只写入实际修改的字段。ID 和正文逐项编辑，跨容器批量移动／删除会明确拒绝。

画布和结构树右键菜单提供编辑正文、前／后插入段落、复制、上移／下移及删除；多选时移动、删除作用于所选集合。元素获得焦点时，Delete／Backspace 删除所选元素，Ctrl+D 复制单个元素，Alt+↑／↓ 移动，Enter／F2 聚焦单个正文。点击空白处显示文档或分节属性时，Delete／Backspace 和 Ctrl+D 不修改内容；重新选中画布组件后恢复对应操作。Ctrl+Z 撤销、Ctrl+Shift+Z 或 Ctrl+Y 重做；输入框和正文编辑器中的删除、选区及撤销保留文字编辑行为，打开对话框时不触发元素快捷键。元素删除可通过撤销恢复；无效草稿会阻止提交。

独立、静态的单图片段落使用引擎给出的实际图片位置作为命中框。固定位置图片的画布缩放手柄同步调整图片宽高及段落行高；自动占位图片的尺寸可通过属性／行内片段设置，拖动仍只排序。混合图文、动态尺寸或复杂容器使用属性／行内片段。结构树拖动只调整文档流顺序；画布依组件排版属性排序或自由移动，显式转换为固定框时保留原有有效段落样式。

页面、页眉页脚和边距

点击页面空白处选中该页所属的 section，未分节时选中 document；点击页面外的画布空白处选中文档。检查器显示对应属性及“页面、页眉页脚与边距”入口，空白页同样适用。拖动空白处仍用于框选元素。也可从结构树选中 document 或 section，或使用顶部“页面与页区”选择范围。纸张提供 A4、LETTER、A3、A5、LEGAL 及自定义宽高；A3／A5／LEGAL 写入既有 XML 的显式尺寸，不新增纸张枚举。方向可选横向／纵向，统一及四边页边距分别设置，长度接受 pt／mm／cm／in。空值表示移除局部覆盖、使用继承或默认值，显式 0 与空值不同。属性说明收在各字段旁的 ⓘ 悬浮提示中。

修改源码导致重新分页时，旧预览页面通过分节 ID、保留的唯一子节点 ID 或无歧义的原内容关联到对应分节；分节改名后同样适用。无法确认归属时先刷新预览，并提示在最新页面中重新选择；保留当前选择和修改，刷新失败时也不切换目标。查看文档属性时，从工具栏或 Shift+F10 菜单插入正文会使用当前页所属分节；页内“插入内容”按钮和空白处右键菜单使用目标页所属分节。源码、数据、资源或预览变化后，已打开的插入菜单失效；已选择但仍在等待或配置中的插入命令也会在写入前检查，请在最新页面重新选择位置。生成目录页不属于正文分节，在分节文档中须先选择正文页才能插入正文。

需要中途改变纸张、方向、页眉或页脚时，选中希望成为新节第一项的顶层正文，在右键菜单或“添加元素”中选择“新建分节”。普通正文会转换为分节；已有分节会从该正文拆成两节。新节从新页开始，选中新节设置 first-page-number 可重置显示页码，留空或 0 表示接续上一节。根设置是默认值，每节可独立覆盖纸张和页区；首页／偶数页变体也可按节设置。{pages} 仍表示整个文档的最终物理总页数，不随显示页码重置。分节以顶层正文为边界，不能在一个跨页段落或表格内部按自动页码切开；选中一节的首项时直接编辑该节设置。

页眉页脚分别配置高度、与正文间距和内容，支持默认、首页、偶数页变体。简单单段区域可直接填写文字，以 {page}／{pages} 插入宽度 24 pt 的最终页码／总页数字段；${page} 等模板变量保持原文。设置变动会自动排版预览，关闭面板时写入可撤销历史。画布中的页眉页脚可点选；单段区域双击后直接编辑正文，复杂区域可从结构树选择子节点或编辑高亮 XML。共享来源引用会定位到原声明。

每个变体是一整对页眉／页脚，新建变体未启用的一边为空；不会自动补默认对。节中删除局部声明恢复根继承，清空继承区域须用 height="0" 的空区域。切换设置范围或变体会保留当前有效草稿；非法 XML 须修正后才能切换。页区超高、页边距耗尽正文及非法尺寸明确失败，不裁切、缩小或更换单位。详见纸张、页区和变体。

页面四边页边距、段前后外间距和表格内边距分别设置；没有把它们混为 CSS margin／padding，也不提供装订镜像页边距。页面设置中的“无页边距”将正文四边边距设为 0。页眉／页脚另有距纸张顶／底、左、右三个输入，显式 0 可贴边；留空沿用对应正文页边距。页区位置参与正文空间预留，越出纸张或挤尽正文空间会报错。

页面横竖方向通过分节设置。段落、标题、列表项、题注、图片和表格可设置 rotation，单位为顺时针度数，范围 -180 至 180；预览与 PDF／SVG／PNG 使用同一图形变换。旋转在原有排版框内等比缩放，不改变换行、分页和元素位置；狭长段落或表格转至接近直角时可能明显缩小，可增加行高或调整表格尺寸后检查预览。跨页表格按每页片段分别旋转。DOCX／HTML／Markdown 保留内容但无法保留角度，默认拒绝；选择 WARN／IGNORE 与 DEGRADE 时会在损失报告中列出每个旋转元素。

表格、富文本与复杂属性

属性面板按所选节点提供具名输入、数字、颜色选择和枚举控件，并显示单位、继承方式及限制说明。段落包括字号、行高、对齐、角色／颜色、首行／后续缩进、段前后间距、断行、段落保持、换页和孤行控制；表格包括四边内边距、前后外间距、边框和跨页拆行。选择列可切换固定／比例／有界自动列宽，界面清除其他方式的互斥属性；选择单元格可配置跨列／跨行与文字格式。合并格仍须满足完整网格校验。未知或未提供专用控件的属性保留在“高级 XML 属性”和节点源码中，不静默删除。

“紧凑网格”“宽松网格”“无边框”预设选中后立即生效，覆盖当前表格的内边距、边框及直接单元格字号／行高；嵌套表格保持独立。预设不改合并、内容、列宽或拆行设置。样式范围可选整表、表头、正文行、指定列或选中格，分别调整字号、行高、对齐、字体角色、文字颜色和断行。修改实时预览，切换元素或保存时写入撤销历史。当前表格模型没有任意单元格背景、逐边线型／颜色或垂直对齐控件。

“单元格布局 / 合并”显示包含现有跨度的网格。单击选择一格，Ctrl 多选，Shift 从锚点选择矩形；关闭面板后可对选中格调整样式。合并要求完整矩形且不跨表头／正文，内容按行列顺序保留在左上格，普通行内内容用换行分隔，富文本、链接、图片和字段保留。拆分恢复物理网格，原内容留在左上格，其余为空；两种操作均可撤销。合并后的段落对齐和行高沿用左上格。动态 rows 的正文只允许横向合并，不跨数据记录。带条件规则的格须先显式移除规则才能合并，避免改变规则作用范围；拆分则把规则留在左上格。

“条件样式”按当前样式范围新增、编辑或删除规则。数据路径为 record.score 等词法路径，判断支持布尔真／假、等于／不等于、数值比较和包含文字；不执行脚本。命中后按声明顺序覆盖指定的文字属性，其他属性保持原值。可设置角色、颜色、字号、行高、对齐、下划线和删除线；每格最多 64 条。条件随绑定数据重新计算，最终格式进入 PDF、DOCX 等输出；模板 ZIP 保留原规则，导出文件只包含本次绑定结果。正文编辑不会删除规则。规则目前适用于行内单元格，块格、背景、边线等不在范围内；缺值和类型错误会明确报错。完整 XML 语法见模板指南，交互及三种实际输出证据见阶段一百一十一。

“正文内容”直接编辑所选段落、标题、列表项、链接或行内单元格；选中文字后设置粗体、颜色、字号、下划线或删除线。它将格式映射为既有 XML 行内声明，图片、字段及其他结构对象保留为不可拆分的标记。粘贴按纯文字处理，不执行或导入任意浏览器 HTML。

“高级行内片段”继续提供片段顺序、链接、图片资源及尺寸、基线偏移和四类页码／编号字段的精确编辑；块格先选择其中的段落。正文、属性和节点 XML 草稿实时预览，切换节点时提交有效修改。固定行高须容纳最大字号和图像，字段须有足够宽度。图片、字段、表达式和未修改声明保持原有 XML 结构，不通过纯文字拍平。

XML／JSON 格式化与高亮

完整模板、绑定 JSON、节点 XML 和页区 XML 都提供同步滚动的行号与语法高亮。对应“格式化”按钮或编辑区 Ctrl+Shift+F 格式化草稿，Tab 插入两个空格；格式化结果实时预览，提交时进入工作区和撤销历史。

XML 只缩进明确的结构容器，段落／行内单元格的混合内容、模板表达式及有意义空白保持原文；不使用通用自动缩进改动富文本。序列化可能规范化声明、引号和属性顺序。JSON 通过服务端有界解析器格式化，保持大数精度，不接受重复键、null 或非法输入。高亮只是编辑辅助，最终合法性仍以编译及绑定检查为准。相关浏览器和独立输出证据见阶段一百零九及阶段一百一十。

资源与字体

项目资源位于侧边“资源”标签中，可添加／替换 PNG、JPEG 图片和离线 XML 片段。图片显示缩略图、名称及像素尺寸，点击或拖到画布插入；插入图片时通过缩略图选择资源。元素属性中显示所引用图片的预览及正文片段声明的字体角色资源，图片节点可用下拉选择资源并锁定宽高比。中文回退按最终绑定文字实际发生，不代表无条件嵌入 PDF。动态图片引用在绑定前显示说明，以真实预览为准。未被修改的图片、片段、字体和许可随 ZIP 保留。

设计器显式约定 Regular.ttf 为正文，Chinese.ttf 为可选中文回退，Bold.ttf 为可选 bold 角色。替换字体时同时选择许可文本；缺少正文角色或缺字会报错，不自动扫描系统字体。打开其他字体命名的 ZIP 时先导入对应角色；原资源仍保留。更多字体集合、原生塑形配置使用库 API，不由此应用推断。

内置字体包括仓库已有的 Liberation Sans、ZCOOL XiaoWei 和霞鹜文楷 TC；六套常用文档使用文楷作为中文字体，其余样例保留原字体配置。来源和 OFL 许可见字体记录。页面中的字体回退诊断表示使用显式备用字体，不等于文字丢失；真正的缺字替换仍走引擎诊断和导出策略。

测试导出与损失

选择	下载内容	语义与限制
PDF	单份 .pdf	使用真实布局，保留当前支持的导航／引用
DOCX	单份 .docx	语义映射，不保证与 PDF 同分页；独立题注、引用及便携导航等按实际报告降级／丢弃
HTML	自包含 .html	语义流式输出，不保留纸张几何和便携导航
MARKDOWN	.md	CommonMark/GFM 内容；样式、几何、元数据及引用等逐项报损
SVG	普通 .svg.zip	每页一个 SVG；静态页丢弃交互对象并报告
PNG	普通 .png.zip	每页一个 96 DPI PNG；静态页丢弃交互对象并报告

DOCX 表格保留独立列宽和合并关系，相邻表格使用各自的列网格。Word 编辑和排版可能改变换行及分页，密集表格仍应核对最终显示。

默认动作是 ERROR：遇到损失拒绝导出。WARN 允许所选降级并发出警告；IGNORE 隐藏警告但仍保留实际损失。非法输入、超限、取消和执行失败始终失败。

动作与处理方式独立。按格式推荐时，流式版面使用 DEGRADE，无法映射的导航／元数据／注释等使用相应 DISCARD；实际功能、原因、处理和影响逐项列入预检。也可选择统一 DEGRADE 或 DISCARD，目标不支持该处理时拒绝，不擅自换成另一种处理。

点击“下载文件”会自动检查并实际编码，成功后直接下载同一份结果，无须另行确认。ERROR 在首个拒绝项停止，不触发下载；WARN 继续下载并显示警告；IGNORE 继续下载、保留损失明细但不发警告。每次下载重新使用当前模板、测试数据和导出配置，失败不会下载旧结果。

导出窗口直接显示可视化报告：损失数、警告数、问题分类，以及每类的影响、处理方式和建议。涉及元素可点击定位到画布；表格位置显示源行列，技术详情可折叠查看。拒绝报告只列出已检测到的首个问题，不代表所有问题已检查完成。报告也保留在诊断面板，并可单独下载 JSON；“文件已交给浏览器下载”不表示浏览器已将文件写入磁盘。

预算与使用范围

• 设计器输入文件最多 16 MiB；模板 ZIP 的编码／展开总量各 16 MiB、256 条目、文本 1,000,000 UTF-16 单元、图片共 8,000,000 像素。引擎原有资源和编译预算继续生效。
• JSON 为一个对象，可包含对象、数组、字符串、布尔值和有界数字；最多 32 层、50,000 个值、1,000,000 UTF-16 单元。不接受 null、重复键或表达式代码。
• 单次引擎操作采用 60 秒协作式超时，输出预算 32 MiB；可点击“取消操作”。预览最多 80 页，大批量任务使用库的流式入口。这些是逻辑预算，不是进程内存或即时抢占保证。
• 服务只监听 IPv4 回环地址，校验 Host、Origin 和每次启动的会话令牌，不外联、执行模板代码或提供任意文件路径访问。它用于本地单工作区；部署为多人服务需要独立的身份、权限和运行隔离设计。
• 自由坐标使用有界语义框，其他内容继续按语义流排版。该应用编辑现有 XML 模板，不提供任意 PDF／Word 文件的通用图形编辑，也不宣称所有浏览器及移动端兼容。

五套完整样例

.\gradlew.bat :export4j-designer:scenarios
python scripts/verify_designer.py

Python 使用固定验证依赖，另需 Poppler。默认生成目录 export4j-designer/build/scenarios 必须未存在；重复运行使用新的 -PdesignerOutputDirectory=build/<new-directory>，验证器对应指定 --source。

每套样例保存原始 XML／ZIP、编辑后的 ZIP、配套 JSON、预览和六种实际输出，report.json 记录耗时、输出大小、观察堆用量及损失数。报告含冷启动和缓存影响，观察堆不等于峰值、RSS 或容量保证。11 项失败控制覆盖解析、绑定、预算、取消、损失拒绝及旧目标保护。

首四套样例的独立解析、11 页 PDF 双引擎与 SVG／PNG 渲染、浏览器编辑／保存／重开／导出证据见阶段一百零八。