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

2025-06-03 05:49:01作者：管翌锬

什么是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);