测量

测量用于在 PDF 页面上量取距离、周长和面积。结果按比例换算后显示，并可以写成测量注释。

完整 UI（UIExtension）的测量工具已内置在工具栏中，包括距离、周长、多边形面积和圆形面积。使用这些按钮时，不需要额外注册工具。需要在创建前统一设置比例、标签、吸附，或在代码里切换测量工具时，使用下面的接口。

测量注释从 11.1.0 起通过 PDFViewer.getCreateMeasurementService() 配置。该服务只影响之后新建的测量，不回写页面上已有的测量注释。

测量工具

工具	状态名	结果
距离	createDistance	两点之间的距离
周长	createPerimeter	折线长度
多边形面积	createArea	多边形围成的面积
圆形面积	createCircleArea	圆形面积

状态名也可以写成 PDFViewCtrl.constants.STATE_HANDLER_NAMES 上的 STATE_HANDLER_CREATE_DISTANCE、STATE_HANDLER_CREATE_PERIMETER、STATE_HANDLER_CREATE_AREA、STATE_HANDLER_CREATE_CIRCLE_AREA。

在 PDFViewer 上切换工具：

pdfViewer.getStateHandlerManager().switchTo(
    PDFViewCtrl.constants.STATE_HANDLER_NAMES.STATE_HANDLER_CREATE_DISTANCE
);

在 PDFUI 上切换工具：

const stateHandlerManager = await pdfui.getStateHandlerManager();
stateHandlerManager.switchTo(
    PDFViewCtrl.constants.STATE_HANDLER_NAMES.STATE_HANDLER_CREATE_DISTANCE
);

距离在第二次点击后结束。周长和多边形面积需要多次点击，在右键菜单中选择完成或取消。

创建前设置比例、标签和标记

getCreateMeasurementService() 返回的设置会用在随后创建的测量上。比例表示页面上的一段长度对应实际长度，例如页面上 1 厘米对应实际 1 英尺。

const service = pdfViewer.getCreateMeasurementService();

await service.setScaleRatio({
    userSpaceScaleValue: 1,
    userSpaceUnit: PDF.annots.constant.Annot_Unit_Type.cm,
    realScaleValue: 1,
    realUnit: PDF.annots.constant.Annot_Unit_Type.ft
});

await service.setLabel('墙长');
await service.setMarkupEnabled(true);

setMarkupEnabled(false) 时，工具只在页面上留下测量标记，不创建测量注释。

Annot_Unit_Type 的取值包括 inch、ft、yd、mi、pt、pica、mm、cm、m、km 和 custom。

结果面板和吸附

结果面板显示当前距离、周长或面积。吸附让端点贴到路径的端点、中点、交点或最近点。

const service = pdfViewer.getCreateMeasurementService();

await service.setShowResultInfomation(true);
service.setSnapModes([
    PDFViewCtrl.constants.SNAP_MODE.EndPoint,
    PDFViewCtrl.constants.SNAP_MODE.IntersectionPoint
]);

setSnapModes([]) 会关闭吸附。可选值还有 MidPoint 和 NearestPoint。方法名 setShowResultInfomation 按接口原样拼写。

按某个测量工具单独设置吸附时，使用 PDFViewer.setSnapMode(stateHandlerName, modes)。PDFViewer.getSnapMode(stateHandlerName) 读取该工具当前的吸附设置；未设置时返回空数组。

更新页面上已有测量的比例

PDFPage.setMeasureScaleRatio() 从 8.4.0 起提供。它按页面更新已经存在的测量注释，并要求文档有组装或修改权限。比例字符串的格式是 "1 inch = 1 ft"。

const page = await pdfDoc.getPageByIndex(0);

await page.setMeasureScaleRatio(true, 'inch', '1 inch = 1 ft', 2);

第一个参数为 true 时，比例保存在当前页。这个接口不代替 CreateMeasurementService.setScaleRatio()：前者改已有注释，后者决定接下来新建的测量用哪套比例。

自定义测量工具

如果要做矩形面积这类内置工具没有的测量，可以自行实现 StateHandler。示例见 自定义面积测量工具。