工具
工具负责创建和操作批注、表单字段、测量和内容的鼠标/触摸交互。本指南介绍工具系统及激活、查看和注册工具的 API。
工具注册表
工具由工具名字符串和 data-element 字符串（激活它的工具栏按钮）标识。两者均集中定义在 packages/webview/src/constants/toolNames.js：
ToolNames—— 每个工具名的UPPER_SNAKE → camelCase映射（视图、批注、表单、测量、内容编辑、签名、安全）。DataElementToToolName—— 从DataElements.*_BUTTON到ToolNames.*的反向映射。map——{ [toolName]: { tool, toolName? } }查找表，供 document store 的setToolState将 UI 工具键转为core.setTool(tool, toolName)参数。register(tool)—— 向map添加自定义工具（registerTool使用的扩展钩子）。
UI API
UI.setActiveTool(dataElement)
按 data-element 激活工具。
/**
* @method UI.setActiveTool
* @param {string} dataElement 要激活工具的 dataElement。
*/
UI.setActiveTool('annotationHighlightButton');内部：若 dataElement 为假或被禁用，调用 useDocument.setToolState()（清空）。否则从 constants/toolNames 查找 map[dataElement]；未找到则警告并返回；否则调用 useDocument.setToolState(tool.toolName || tool.tool)。
UI.getActiveTool()
获取当前活动工具对象。
/**
* @method UI.getActiveTool
*/
const tool = UI.getActiveTool();返回 document store 的 getActiveTool getter。
UI.getTool(tool)
按键获取工具配置对象。
/**
* @method UI.getTool
* @param {string} tool
* @returns {object}
*/
const cfg = UI.getTool('highlight'); // => { color, ... }返回 document store 工具条目的浅拷贝 { ...store[tool] }（持有工具样式预设：color、opacity、stroke 等）。
UI.getToolColor(tool)
获取工具颜色。
/**
* @method UI.getToolColor
* @param {string} tool
* @returns {string} color
*/
UI.getToolColor('square'); // => '#FF0000'返回 store[tool].color。
UI.registerTool(tool, options)
注册自定义批注工具。
/**
* @method UI.registerTool
* @param {Object} tool 要注册的工具实例。
* @param {Object} options 注册选项。
* @returns {boolean} 工具是否已注册。
*/
const ok = UI.registerTool(myTool, { /* … */ });将工具名注册到本地 register 表（constants/toolNames）并委托给 core.registerTool(tool, options)（core 桥接层）。桥接层探测 documentViewer.toolRegistry.register，回退到 documentViewer.registerTool，若都不存在则返回 false。
工具样式预设
每个工具在 document store（packages/webview/src/stores/modules/document.js）中有样式预设：
| 工具 | 默认样式 |
|---|---|
highlight | color: '#FFEC66' |
underline / squiggly / strikeout | color: '#FF0000' |
square / arc / polygon / polyline / circle / arrow / line | color、opacity: '0.8'、stroke: '1pt' |
ink | color、opacity、stroke: '2pt' |
freetext | color: '#000000' |
text | color: '#FF0000' |
redaction | color: '#000000' |
remove | color: '#FF0000' |
表单字段（textfield/checkbox/radiobutton/listbox/combobox/pushbutton） | color、borderColor |
setActiveToolColor(color) 写入 this[activeTool].color 并通过 core.setTool(activeTool) 推送到引擎。setToolState(tool) 在工具已激活时切换关闭，否则调用 core.setTool(mapTool.tool, mapTool.toolName)。
工具分类
| 类别 | 工具 |
|---|---|
| 视图 | Pan、CropPage、SelectText |
| 批注 | Text、Ink、Eraser、Highlight、Underline、Strikeout、Squiggly、Circle、Arc、Square、Polygon、Cloudy、Polyline、Arrow、Line、Freetext、Callout、Stamp、Signature、Image、Link |
| 表单 | Textfield、Checkbox、Radiobutton、Listbox、Combobox、Pushbutton |
| 测量 | Line、Polyline、Curve、Arc、Circle、Rectangle、Polygon（测量变体） |
| 内容编辑 | AddText、AddImage |
| 签名 | SignatureFields、AddDigitalSign、AddElectronicSign |
| 安全 | Redaction、Remove |
相关引擎桥接函数
core 桥接层暴露（见 Core 桥接层）：setTool、switchTool、setToolMode、getToolMode、getToolStyles、setToolStyles、registerTool、setDefaultSelect、setEraseMode、getEraseMode。
示例
激活高亮工具并设置颜色
UI.setActiveTool('annotationHighlightButton');
// document store 现在驱动引擎；要更改颜色请使用样式面板
// 或直接通过 Core 推送：
instance.Core.setTool('Highlight', 'highlight');注册自定义工具
UI.registerTool(
{ toolName: 'myTool', /* 工具实现 */ },
{ buttonName: 'myToolButton', icon: 'MyIcon' }
);