MPDF项目中的HTML注释标签详解：annotation标签使用指南

什么是PDF注释

在PDF文档中，注释(Annotation)是一种常见的交互元素，类似于网页中的工具提示(Tooltip)。当读者将鼠标悬停在注释标记上时，会显示一个包含附加信息的弹出文本框。MPDF库通过<annotation>标签提供了在PDF中添加注释的功能。

annotation标签基础语法

<annotation content="注释内容" 
           pos-x="水平位置" 
           pos-y="垂直位置" 
           icon="图标类型" 
           author="作者" 
           subject="主题" 
           opacity="透明度" 
           color="颜色" 
           popup="弹出设置" 
           file="嵌入文件路径"/>

参数详解

1. content参数（必需）

定义注释弹出框中显示的文本内容。需要注意：

• 内容中不能包含特殊字符：<, >, &, '或"
• 应当使用HTML实体编码替代特殊字符
• 推荐使用htmlspecialchars('内容', ENT_QUOTES)函数处理

2. 位置参数

pos-x：注释标记左下角的水平位置（毫米），留空或0表示使用当前书写位置

pos-y：注释标记左下角的垂直位置（毫米），留空或0表示使用当前书写位置

注意：当注释用于文本中时，标记会提升到当前行高上方显示

3. 外观参数

icon：设置注释标记的图标样式，可选值（区分大小写）：

• Note（默认）
• Comment
• Help
• Insert
• Key
• NewParagraph
• Paragraph

color：设置注释标记的背景颜色，支持所有MPDF识别的CSS颜色格式：

• 十六进制：#RRGGBB或#RGB
• RGB函数：rgb(255,255,255)
• 颜色名称：如yellow、blue等

opacity：设置注释标记的透明度（0-1之间），留空时使用annotOpacity配置值

4. 元数据参数

author：设置注释作者名称，显示在弹出框顶部

subject：设置注释主题，显示在注释属性中

5. 高级功能参数

popup：控制PDF打开时是否自动显示弹出框：

• 留空或0：不自动显示
• 任意非空值：自动显示
• 可指定位置和尺寸："30 30"（X Y位置）或"30 30 80 50"（X Y 宽度 高度）

file：嵌入文件到PDF中（需配置allowAnnotationFiles为true）

使用示例

基础示例

$html = '这是关于小提琴的段落<annotation content="小提琴是一种弦乐器" />，我对此了解不多。';
$mpdf->WriteHTML($html);

高级配置示例

// 设置注释标记显示在右边距10mm处
$mpdf->annotMargin = 10;

// 设置注释标记完全不透明
$mpdf->annotOpacity = 1;

$html = '这是关于小提琴的段落<annotation content="小提琴是一种弦乐器" 
        icon="Help" color="lightblue" author="音乐专家"/>';
$mpdf->WriteHTML($html);

安全注意事项

1. 文件嵌入功能默认禁用，必须显式设置allowAnnotationFiles为true才能使用
2. 启用文件嵌入时，必须严格控制文件路径，防止系统文件泄露
3. 注释内容中的特殊字符必须正确处理，避免XSS风险

版本变更历史

• 2.2版本：首次添加注释功能
• 2.4版本：注释变为不可移动或删除
• 4.3版本：新增popup参数
• 5.1版本：新增file参数
• 7.0版本：file参数需要显式配置才能使用

最佳实践建议

1. 对于简单的注释，可以直接使用<annotation>标签
2. 需要批量处理时，考虑使用title2annots配置将HTML元素的title属性自动转为注释
3. 注释标记位置建议使用默认值，让MPDF自动处理布局
4. 需要突出显示时，可以调整颜色和透明度，但要注意可读性
5. 嵌入文件功能应谨慎使用，确保文件路径安全

通过合理使用注释功能，可以大大增强PDF文档的交互性和信息丰富度，为用户提供更好的阅读体验。