注释
为查看器添加注释支持
Doconut 中的注释以两种方式工作:用户在浏览器小部件中绘制它们,服务器按页面持久化,或者你的代码以编程方式构建注释并加载到打开的会话中。无论哪种方式,它们都会在页面上渲染,并且可以嵌入到 PDF/PNG 导出中。
注释支持受 Annotation 许可功能的限制(在有效的临时许可证下会自动授予)。
启用注释 UI
注释是 Viewer 的一个模块,而不是独立的工具栏。完整页面必须包含 Viewer 资源、Viewer 工具栏、Viewer 挂载点以及已初始化的 objViewer;随后会挂载注释功能区(Ribbon)并附加到同一实例上。
将注释捆绑包与 Viewer 捆绑包一起输出——它们受许可证限制,因此只有在具备该功能时标签才会出现:
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeViewerCss = true,
IncludeAnnotationCss = true // jquery-ui.min.css + annotationBar.css
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeViewerScripts = true,
IncludeAnnotationScripts = true, // jquery-ui, raphael.js, annotation.js
IncludeAnnotationBar = true // 嵌入的注释功能区
}))在标记中保持完整的 Viewer 组合可见:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- 查看器控件,包括打开 Annotation 的按钮 -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>注释捆绑包在 annBarMount 内生成功能区(Ribbon)DOM;你无需复制其按钮或对话框标记。首先初始化 docViewer,然后仅在服务器确认已获得注释许可证时创建功能区。
<script>
let annBar = null;
let currentToken = '';
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: 'doconut',
ResPath: 'doconut-res/images',
onAnnLoaded: () => annBar?.handleAnnLoaded(),
onAnnSaved: () => annBar?.handleAnnSaved(),
onAnnSaveError: () => annBar?.handleAnnSaveError(),
onAnnClosed: () => annBar?.handleAnnClosed(),
onError: (message) => console.error('Viewer error:', message)
});
@if (Viewer.IsAnnotationEnabled)
{
<text>
annBar = $('#annBarMount').doconutAnnotationBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token: currentToken }),
onStatus: (message) => console.log(message),
onToast: (message, type) => console.log(type, message),
onLayout: () => requestAnimationFrame(() => objViewer.Refit())
});
annBar.attach(objViewer);
</text>
}
</script>如果没有此功能,ReferenceScripts 会省略功能区的脚本,因此服务器端的 if 能够防止未受保护的 doconutAnnotationBar(...) 调用破坏页面。
从功能区保存时会通过中间件 (AnnSave) 发送数据,该中间件将其存储在每页的文档会话中。加载 (AnnLoad) 会在包含注释的页面渲染时自动进行。四个 onAnn* 回调确保功能区与 Viewer 生命周期保持同步。
可以从任何宿主拥有的 Viewer 工具栏打开或关闭它:
annBar.open();
annBar.close();公共功能区 API 如下:
| Method | Purpose |
|---|---|
attach(objViewer) | 将功能区连接到已初始化的 Viewer;仅需一次 |
open() / close() | 进入或退出注释编辑 |
reset() | 将功能区恢复到关闭的、非编辑状态 |
isOpen() / annotating() | 读取功能区状态 / Viewer 的注释编辑状态 |
reopenEditable() | 将当前页面的注释重新加载为可编辑对象 |
updateActionState() | 在宿主更改后刷新保存/删除控件的可用性 |
headerSlot() | 获取用于宿主控件的可选页眉扩展槽 |
onStatus、onToast、onLayout、onEditStart 和 onEditEnd 是可选的宿主回调。endpoints 对象还可以提供 exportPdf、exportPng、imageUpload 和 imageList;未配置端点的控件将保持隐藏。有关组合的 Viewer、Search 和 Annotation 启动顺序,请参阅 快速入门。
注释捆绑包添加了浏览器创作工具,但数据仍归属于由令牌标识的服务器端文档会话。重新打开源文件会创建新会话;如果注释需要在会话生命周期结束后仍然存在,请在你的应用中持久化 XML 或编码的注释封装。
两种回调方式,双向连接
注释代码使用两种回调样式,当以另一种方式连接时,每种都会静默失败:
onAnnLoaded,onAnnSaved,onAnnSaveError,onAnnClosed是 选项,属于docViewer({...}),就像每个查看器回调一样。Created,Changed,Deleted, andProperties是 通过名称查找的全局函数:事件名前加上查看器 ID。对于#div_ctlDoc中的查看器,ID 为ctlDoc,因此函数为ctlDoc_Created、ctlDoc_Changed、ctlDoc_Deleted和ctlDoc_Properties。拼写错误或重命名的函数根本不会被调用。
SaveAnnotations() 不会返回是否已保存:结果通过 onAnnSaved 或 onAnnSaveError 传递。读取其返回值的代码永远不会清除其“未保存更改”标志。
在 C# 中构建注释
获取绑定到打开会话的管理器,添加注释并加载它们(使用 using Doconut.Annotations; 指定类型,使用 using System.Drawing; 处理 Rectangle/Color):
app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
// 绑定到打开会话的页面尺寸
var manager = viewer.GetAnnotationManager(token);
var pageCount = viewer.GetPageCount(token);
// 每页一个印章
for (int page = 1; page <= pageCount; page++)
{
manager.Add(new StampAnnotation(page, new Rectangle(30, 20, 240, 90),
$"PAGE {page}", 28, 4, Color.Maroon)
{
Opacity = 60,
Rotate = -8
});
}
manager.Add(new NoteAnnotation(1, new Rectangle(420, 150, 220, 120),
"Loaded from C# code.", Color.FromArgb(255, 255, 255, 170), 14));
// 加载到会话中 — 小部件通过 AnnLoad 获取它们,并且
// renderer 将它们烧录到 image/PDF 导出中。
viewer.LoadAnnotationData(token, manager);
return Results.Ok();
});注释类型
所有类型位于 Doconut.Annotations,并继承自 BaseAnnotation(页码 + 边界 Rectangle):
| 类型 | 备注 |
|---|---|
StampAnnotation | 带有字体大小、边框、颜色的文本印章;支持 Opacity、Rotate |
NoteAnnotation | 带文本、背景颜色、字体大小、TitleColor 的便利贴 |
RectangleAnnotation | 边框 + 填充颜色,Title/ShowTitle |
CircleAnnotation | 边框 + 填充,ShowBorder |
EllipseAnnotation | 边框 + 填充,ShowBorder |
TriangleAnnotation | 边框颜色,BackColor,ShowBorder |
LineAnnotation | 具有宽度和颜色的直线 |
ArrowAnnotation | 带箭头的线;可设置的 Direction(类型 ArrowDirection,罗盘点,默认 E) |
FreehandAnnotation | 从编码的 FreehandData 点生成的自由笔画 |
ImageAnnotation | 来自 URL 的图像。相对 URL 在添加注释时相对于请求主机解析;服务器仅在烧录时获取图像——请参见下方的导出说明 |
AnnotationManager API
| 成员 | 用途 |
|---|---|
Add(BaseAnnotation) | 将注释加入队列 |
GetAnnotations() / GetAnnotations(int page) | 检查管理器持有的内容 |
ClearAnnotations() / ClearAnnotations(int page) | 移除全部 / 按页 |
GetAnnotationData() / GetAnnotationData(int page) | 编码的注释数据字符串 — Base64 传输封装(小部件使用的内容) |
GetAnnotationXml() | XML 形式 |
Viewer 镜像针对会话的加载/读取操作:LoadAnnotationData(token, manager) 或 LoadAnnotationData(token, encodedData)(来自 GetAnnotationData() 的 Base64 传输封装),LoadAnnotationXML(token, xml),GetAnnotationXML(token)。
导出并嵌入注释
// 所有页面的 PDF,带有渲染在其上的注释
app.MapGet("/api/annotations/export-pdf", async (string token, Viewer viewer) =>
{
byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100);
return Results.File(pdf, "application/pdf", "export.pdf");
});
// 或每页 PNG 的 ZIP
app.MapGet("/api/annotations/export-png-zip", async (string token, Viewer viewer) =>
{
byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100);
return Results.File(zip, "application/zip", "annotations-png.zip");
});导出使用与屏幕渲染相同的烧录器,因此用户看到的内容就是文件中包含的内容——图像注释除外,详见下文。
在内网主机上导出图像注释显示为 "Image blocked"
查看器和导出功能从不同位置获取 ImageAnnotation 的图像:
| 界面 | 谁下载图像 | 在内网或开发主机上 |
|---|---|---|
| 浏览器中的查看器 | 用户的浏览器 | 图像显示 |
ExportAnnotationsToPdfAsync / …PngZipAsync | 服务器 | 一个红色的 “Image blocked” 占位符 |
当服务器获取图像以嵌入时,它会拒绝指向私有网络的地址:环回 (localhost, 127.0.0.1)、0.0.0.0、链路本地 (169.254.x.x)、私有地址段 10.x、172.16–31.x 和 192.168.x、运营商级 NAT (100.64.0.0/10),以及 IPv6 链路本地和唯一本地地址。这可以防止服务器被用于通过精心构造的图像 URL 访问内部系统,且没有关闭此功能的开关。
相对图像 URL 会相对于当前请求的主机进行解析,因此在 localhost、在内网服务器上,或在任何通过私有地址访问的站点上,图像会在查看器中显示,而导出则会包含占位符。这是防护机制在起作用,而不是渲染失败。如果导出必须包含图像,请从具有公共地址的主机提供图像并使用绝对 URL。无法解析的主机名也会以同样方式被拒绝;任何其他下载失败都会在图像应在的位置以红色显示 URL 和错误信息。
持久化工作流
- 打开文档并获取其令牌。
- 将先前存储的 XML 或编码数据加载到该令牌中。
- 让小部件读取并编辑会话注释。
- 在应用决定持久化时使用
GetAnnotationXML(token)检索 XML。 - 当需要平面交付物时导出 PDF/PNG。
- 关闭文档会话。
不要将不透明的查看器令牌用作永久的注释标识符。请将持久化的注释数据与您自己的文档和版本标识符关联。
安全性和渲染说明
- 注释请求使用与页面请求相同的会话/令牌安全机制。
- 验证并控制任何用户提供的图像 URL,以避免服务器端请求伪造。
- 导出遵循与屏幕页面渲染相同的许可证/自定义水印决策。
- 大型手绘负载和高分辨率导出会增加内存使用;请测试真实文档和缩放值。
故障排除
| 症状 | 检查 |
|---|---|
| 注释功能区缺失 | Annotation 能力以及四个注释 CSS/脚本标志 |
| 保存回调报告错误 | 令牌/会话过期以及中间件 BasePath |
ctlDoc_Created(或其他事件函数)从未运行 | 函数名:viewer id + _ + event,作为全局函数 |
| C# 注释未出现 | 页面编号从 1 开始,且数据已加载到活动令牌中 |
| 图像注释在屏幕上显示但在导出中缺失 | 图像的主机使用私有或环回地址——见上文 |
| 重新打开的文档没有注释 | 在查看器会话之外持久化 XML/数据,然后加载到新的令牌中 |
此页面对您有帮助吗?