【EMR 编辑器 · 常见问题】
安装 · 授权 · 字体导出 · 打印 · 数据 · 性能 · 20 个高频问题
【一、安装与接入】
Q1：装 @emr/editor 时报「找不到 @emr/core」？
两个包必须成对安装：npm install ./emr-core-x.y.z.tgz ./emr-editor-x.y.z.tgz。组件包依赖内核包，单独装组件包一定报错。
Q2：Vue 工程为什么被迫安装 react？会不会污染项目？
@emr/vue 内部用 React 渲染内置 UI（工具栏 / 打印对话框等只需维护一份）。react / react-dom 只是内部引擎，业务代码零 React，打包进 vendor 与 Vue 应用互不干扰。详见《Vue 3 集成详解》第一节。
Q3：编辑器显示空白 / 高度为 0？
容器没有确定高度——新手问题第一名。给容器 height（100vh / 固定像素 / flex 布局），flex 子项记得加 minHeight: 0；纯 HTML 容器还要 position: relative。
Q4：能在 Node.js 服务端渲染文档吗？
不能直接 import 包（产物为浏览器 ESM，依赖 Canvas / DOM）。服务端生成文档用两种替代：① 程序拼 JSON（结构见《文档 JSON 格式说明》）；② 无头浏览器（Puppeteer）里跑静默流水线导出 PDF。
Q5：支持 IE 吗？嵌入 iframe 行吗？
不支持 IE（需 Chrome / Edge / Firefox ≥ 90 的 Canvas 与 ES2020）。iframe 嵌入完全没问题——编辑器不依赖顶层 window，跨 iframe 通信用 postMessage 转发命令即可。
【二、授权】
Q6：不购买授权能用吗？
能。2 页以内文档永久免费、功能完整（编辑 / 导出 PDF / 打印），无横幅无弹窗。超过 2 页才受限（仅渲染前 2 页、导出打印拦截并提示激活）。未激活时纸张外空白背景平铺「暂未授权」水印（不影响正文 / 打印 / 导出），可用 license.bgWatermark: false 关闭。
Q7：激活后提示「授权与当前部署地址不匹配」？
key 绑定了部署地址白名单，当前页面地址（协议 + 域名/IP + 端口完全一致）必须在白名单内——换端口、换 IP、http 改 https、加路径都算不同地址。测试 + 生产多个环境请申请时一并提交；确实变更了部署地址联系发行方重新签发。
Q8：换电脑 / 浏览器要重新激活吗？系统时间回拨了怎么办？
不用重新激活：key 写在代码或运行时传入，与设备无关（但绑定地址的 key 只在白名单地址有效）。本地时间水印防时钟回拨：系统时间早于已记录时间超 10 分钟判 invalid，校准时间 / NTP 后刷新页面即恢复；正常 NTP 微调不受影响。
【三、PDF 与字体】
Q9：为什么导出 PDF 必须提供字体文件？
屏幕显示用操作系统字体（宋体谁都有）；PDF 要在任何机器打开都一致，必须把字体文件嵌进 PDF。所以 options.fonts.regular 必填（TTF/OTF 的 URL 或二进制）；内置工具栏导出则配置 toolbar.pdfFonts。详见《PDF 导出详解》第一节。
Q10：正文正常，PDF 里 ℃、≥、× 等符号乱码缺失？
提供的字体文件缺这些码位的字形（常见于子集化 / 精简字体；浏览器屏显会自动兜底所以看不出来）。解决：换完整中文字体（完整宋体 / 微软雅黑 / Noto Sans SC），或配 fonts.fallback 兜底字体覆盖符号。
Q11：字体 URL 跨域报错 / 每次导出都要下载十几 MB？
CORS：字体放同域或给字体服务器加跨域头。性能：预加载字体并缓存字节（示例工程提供 IndexedDB 缓存方案），或首次导出后缓存 ArrayBuffer 复用传入。
【四、打印】
Q12：打印标记 / 留痕日志会被撤销（undo）掉吗？
不会。两者均为仅追加的持久化数据（条目冻结不可删改，随文档 JSON 保存）；undo / redo 只作用于正文内容。
Q13：静默打印怎么实现？
需要一个本地打印代理（HTTP 服务）：编辑器逐页下发 PNG 位图、代理按纸张整页出纸（GET /printers 枚举、POST /print 下发）。Windows 可运行代理示例见《静默打印对接》第四节；也可委托发行方部署。
Q14：静默打印报「无法连接代理 / 超时」？
代理未启动或地址错：确认 baseUrl 可达、GET /printers 返回 200；页数多调大 printTimeoutMs（默认 120s）。HTTPS 页面连 HTTP 代理会被混合内容策略拦截——代理也上 HTTPS（自签证书需装信任）或页面降 HTTP；跨域报错给代理加 CORS 头。
Q15：静默打印出来空白 / 缺字，或内容偏小留白大？
空白缺字：renderPrintPages 渲染时字体未就绪——先做字体缓存预热再打印。偏小留白：代理没按 paper.widthMm/heightMm 整页输出，或套了打印机默认边距——按协议页边距 0 整页绘制（对照代理示例修正）。
【五、数据与内容】
Q16：数据源 / 录入域改定义后，正文占位符会怎样？
改名 / 改 key 用 replaceDataSource（正文引用与数据值随 key 自动迁移）；删除后数据源占位符转普通文本，录入域保留 label 快照仍可显示 / 编辑 / 提取。详见《数据源与录入域详解》。
Q17：怎么知道哪些关键词被触发了？
api.keywordHits() 返回正文实际命中的关键词（去重），适合保存前校验：命中非空时弹确认，防止漏项归档。完整方案见《留痕与关键词详解》。
Q18：文档 JSON 能存外链图片吗？
能。insertImage(src) 及水印 / 背景图都支持任意 URL；注意导出 PDF 与打印时编辑器会 fetch 它（需 CORS 可达），离线场景建议 dataURL 内嵌。
Q19：想「打开病历 → 回填 → 导出归档」全自动完成，行吗？
行。全程无 UI 的静默流水线：setDoc → setDataValues / setEntryValues → exportPDF（或 renderPrintPages + 代理打印），零弹窗，编辑器可隐藏 / 离屏挂载。见《静默打印对接》第五节。
【六、性能与其他】
Q20：大文档（几百页）会卡吗？包体积为什么有点大？
不会明显卡：内置虚拟滚动（只画可见页 ± 缓冲页）与增量布局，900 页文档实测渲染约 800ms（i7-8700 真机）。批量编程修改建议合并为一次 setDoc / setConfig。体积：IIFE 包约 1.9MB（gzip 600–800KB），主要是内置 React 与 PDF 库，属正常水平；npm 接入可共享宿主依赖。
Q21：为什么预览（preview）模式还能编辑？
viewMode 只管「怎么画」（标记色等），不管「能不能改」；禁止编辑用 readonly。纯查看器组合：viewMode='preview' + readonly。
Q22：升级版本会破坏已有文档吗？
文档 JSON 结构向前兼容，旧文档直接加载。大版本变更（0.x → 1.x）可能有不兼容调整，升级前看下载页版本说明。
以上未覆盖的问题，欢迎通过下载页的联系方式反馈（请附控件版本号、浏览器、报错信息与复现步骤）。