注释

为查看器添加注释支持

Doconut 中的注释有两种工作方式:用户在浏览器小部件中绘制它们,服务器按页面保存,或者你的代码构建注释并将其加载到打开的会话中。无论哪种方式,它们都会在页面上渲染,并且可以嵌入到 PDF 或 PNG 导出中。

注释支持受 Annotation 许可证功能的限制(在有效的临时许可证下会自动授予)。

启用注释 UI

注释是 Viewer 模块,而不是独立的工具栏。页面必须包含 Viewer 资源、Viewer 工具栏、Viewer 挂载点,以及已初始化的 objViewer;随后会挂载注释功能区并附加到同一实例上。

将注释文件与 Viewer 文件一起输出。它们受许可证限制,仅在功能被授予时才会出现相应标签。在 MVC 5 中,在控制器中构建标签(视图没有 @inject):

csharp
public class ViewerController : Controller
{
    public ActionResult Index()
    {
        var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
        ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
        {
            IncludeViewerCss     = true,
            IncludeAnnotationCss = true    // jquery-ui.min.css + annotationBar.css
        });
        ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
        {
            IncludeJQuery            = true,
            IncludeViewerScripts     = true,
            IncludeAnnotationScripts = true,  // jquery-ui, raphael.js, annotation.js
            IncludeAnnotationBar     = true   // 嵌入式注释功能区
        });
        ViewBag.IsAnnotationEnabled = viewer.IsAnnotationEnabled;
        return View();
    }
}

在标记中保留完整的 Viewer 组合:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- 查看器控件,包括打开 Annotation 的按钮 -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

注释文件在 annBarMount 中生成功能区;你不需要复制其按钮或对话框。首先初始化 docViewer,然后仅在服务器确认已授权注释时才创建功能区:

html
@Html.Raw(ViewBag.ViewerCss)
@Html.Raw(ViewBag.ViewerScripts)
<script>
    var annBar = null;
    var currentToken = '';

    var objViewer = $('#div_ctlDoc').docViewer({
        BasePath: '/',
        ResPath:  'doconut-res/images',
        onAnnLoaded:    function () { if (annBar) annBar.handleAnnLoaded(); },
        onAnnSaved:     function () { if (annBar) annBar.handleAnnSaved(); },
        onAnnSaveError: function () { if (annBar) annBar.handleAnnSaveError(); },
        onAnnClosed:    function () { if (annBar) annBar.handleAnnClosed(); },
        onError:        function (message) { console.error('Viewer error:', message); }
    });

    @if ((bool)ViewBag.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: function () { return { token: currentToken }; },
        onLayout: function () { requestAnimationFrame(function () { objViewer.Refit(); }); }
    });
    annBar.attach(objViewer);
        </text>
    }
</script>

如果没有此功能,ReferenceScripts 会省略功能区的脚本,从而使服务器端的 if 能够防止未受保护的 doconutAnnotationBar(...) 调用破坏页面。在 Web Forms 中,使用 <% if (IsAnnotationEnabled) { %> … <% } %> 编写相同的保护。

从功能区保存会将数据发布到 DocImage.axd(AnnSave),它会将数据按页面存储在文档会话中。加载(AnnLoad)在带有注释的页面渲染时会自动发生。

使用 annBar.open() 和 annBar.close() 从你自己的工具栏打开和关闭功能区。它的公共 API:

方法用途
attach(objViewer)将功能区连接到已初始化的查看器;仅需一次
open() / close()进入或退出注释编辑
reset()将功能区恢复到关闭的、非编辑状态
isOpen() / annotating()读取功能区状态 / 查看器的注释编辑状态
reopenEditable()重新加载当前页面的注释为可编辑对象
updateActionState()在主机更改后刷新保存和删除控件
headerSlot()用于主机拥有控件的可选标题插槽

onStatus、onToast、onLayout、onEditStart 和 onEditEnd 是可选的主机回调。endpoints 对象还可以提供 exportPdf、exportPng、imageUpload 和 imageList;未配置端点的控件将保持隐藏。

两种回调方式,双向连接

注释代码使用两种回调样式,当以另一种方式连接时,它们都会悄然失效:

  • onAnnLoaded, onAnnSaved, onAnnSaveError, onAnnClosed 是 docViewer({...}) 的 选项,就像每个查看器回调一样。
  • Created, Changed, Deleted, and Properties 是 通过名称查找的全局函数:事件名前缀为查看器 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):

csharp
// POST /Annotations/LoadSample?token=...
[HttpPost]
public ActionResult LoadSample(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<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));

    // 加载到会话中 - 查看器获取它们,渲染器将其烧录进去
    // image/PDF 导出。
    viewer.LoadAnnotationData(token, manager);
    return new HttpStatusCodeResult(200);
}

注释类型

所有类型位于 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)编码的注释数据——小部件消费的封装
GetAnnotationXml()XML 形式

Viewer 镜像针对会话的加载和读取操作:LoadAnnotationData(token, manager) 或 LoadAnnotationData(token, encodedData)、LoadAnnotationXML(token, xml) 和 GetAnnotationXML(token)。

导出并嵌入注释

csharp
// 所有页面的 PDF,批注已渲染在上
public async Task<ActionResult> ExportPdf(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100, ct: Response.ClientDisconnectedToken);
    return File(pdf, "application/pdf", "export.pdf");
}

// 或每页 PNG 的 ZIP
public async Task<ActionResult> ExportPngZip(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100, ct: Response.ClientDisconnectedToken);
    return File(zip, "application/zip", "annotations-png.zip");
}

导出使用与屏幕渲染相同的燃烧器,并采用相同的许可证和自定义水印决策。

内部网络主机上的图像批注导出为“图像已阻止”

查看器和导出从不同位置获取 ImageAnnotation 的图像:

场景谁下载图像在内部网络或开发主机上
浏览器中的查看器用户的浏览器图像显示
ExportAnnotationsToPdfAsync / …PngZipAsync服务器一个红色的 “图像已阻止” 占位符

当服务器获取图像并将其嵌入时,它会拒绝指向私有网络的地址:环回 (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 和错误信息。

持久化工作流

  1. 打开文档并获取其令牌。
  2. 将先前存储的 XML 或编码数据加载到该令牌中。
  3. 让小部件读取并编辑会话批注。
  4. 当应用决定持久化时,使用 GetAnnotationXML(token) 获取 XML。
  5. 需要平面交付物时导出 PDF 或 PNG。
  6. 关闭文档会话。

不要将查看器令牌用作永久的批注标识符——它随会话结束而失效,且应用程序池的回收会终止单台服务器上的所有会话。请将批注数据存储在您自己的文档和版本标识符下。

安全性与渲染说明

  • 批注请求使用与页面请求相同的会话和令牌安全机制。
  • 验证并控制任何用户提供的图像 URL。
  • 大型手绘负载和高分辨率导出会增加内存使用;请使用真实文档和缩放值进行测试。

故障排除

症状检查
批注功能区缺失Annotation 功能以及四个批注 CSS/脚本标志
保存时报告错误令牌或会话过期,以及小部件的 BasePath
ctlDoc_Created(或其他事件函数)从未运行函数名:viewer id + _ + event,作为全局函数
C# 批注未显示页码从 1 开始,且数据已加载到活动令牌中
图像批注在屏幕上显示但在导出中缺失图像的主机具有私有或环回地址——见上文
重新打开的文档没有批注在查看器会话之外持久化 XML 或数据,然后加载到新的令牌中

此页面对您有帮助吗?