mPDF调用中的参数设置
一、参数总览
options 数组的顶层参数如下：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
type | string | 是 | 水印类型，只能是 'text' 或 'image' |
根据 type 的不同，后续参数分两组：
文字水印（type = 'text'）
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
text | string | 无 | 水印文字内容，支持 \n 换行或 <br> 标签 |
alpha | float | 0.2 | 透明度，范围 0~1，值越小越淡 |
font | string | 'GB' | 字体名，中文建议用 'GB' 或 'sun-exta' |
angle | int | 45 | 旋转角度，单位度，如 0 水平、45 倾斜 |
图片水印（type = 'image'）
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
image | string | 无 | 图片路径，支持相对 public 目录或绝对路径 |
alpha | float | 0.3 | 透明度，范围 0~1 |
size | string/array | 'D' | 水印尺寸，见下方说明 |
position | array | [0, 0] | 水印位置 [x, y]，单位 mm |
二、完整调用示例
1. 文字水印（单行）
$options = [ 'type' => 'text', // 必填：指定文字水印 'text' => '机密文件', // 必填：水印文字 'alpha' => 0.2, // 可选：透明度，默认 0.2 'font' => 'GB', // 可选：字体，默认 'GB'（中文用） 'angle' => 45, // 可选：旋转角度，默认 45 度];
2. 文字水印（多行）
$options = [ 'type' => 'text', 'text' => "机密文件\n严禁外传", // 双引号中 \n 才会换行 // 或使用 HTML： // 'text' => '机密文件<br>严禁外传', 'alpha' => 0.2, 'font' => 'GB', 'angle' => 45,];
3. 文字水印（不旋转，水平居中）
$options = [ 'type' => 'text', 'text' => '内部资料', 'alpha' => 0.15, // 更淡 'font' => 'GB', 'angle' => 0, // 不旋转];
4. 图片水印（默认尺寸，左上角）
$options = [ 'type' => 'image', // 必填：指定图片水印 'image' => '/static/watermark.png', // 必填：相对 public 的路径 'alpha' => 0.3, // 可选：透明度，默认 0.3 'size' => 'D', // 可选：默认尺寸 'position' => [0, 0], // 可选：左上角];
5. 图片水印（铺满整页）
$options = [ 'type' => 'image', 'image' => '/static/watermark.png', 'alpha' => 0.2, 'size' => 'F', // F = Fill，铺满整页 'position' => [0, 0],];
6. 图片水印（自定义尺寸，页面居中）
$options = [ 'type' => 'image', 'image' => '/static/watermark.png', 'alpha' => 0.3, 'size' => [50, 50], // 宽 50mm，高 50mm 'position' => [-25, -25], // 负数表示向左、向上偏移，实现居中];
7. 图片水印（适应页面）
$options = [ 'type' => 'image', 'image' => '/static/watermark.png', 'alpha' => 0.3, 'size' => 'P', // P = Page，缩放到适应页面 'position' => [0, 0],];
三、参数详解
type
必填，只能是
'text'或'image'。决定使用哪一组参数，另一组参数会被忽略。
如果传了其他值，
PdfService会抛出ValidateException。
text
文字水印内容。
多行写法：
"第一行\n第二行"—— 双引号中的\n会换行；'第一行<br>第二行'—— HTML 标签也可以，mPDF 内部会解析。单引号中的
\n是字面量，不会换行，请务必用双引号。
alpha（文字和图片共用）
透明度，范围
0 ~ 1。0= 完全透明（看不见），1= 完全不透明。文字默认
0.2，图片默认0.3。建议文字水印用
0.1 ~ 0.3，图片水印用0.2 ~ 0.4，避免遮住正文。
font
仅文字水印使用。
mPDF 内置字体名，中文水印推荐：
'GB'：常用中文字体，兼容性好；'sun-exta'/'sun-extb'：支持扩展字符（含 SIP）；'dejavusans'：Unicode 通用字体，但中文可能显示方框。如果水印中文显示方框，先改
'GB'，不行再换'sun-exta'。
angle
仅文字水印使用，单位为度。
0= 水平，45= 逆时针倾斜 45°（默认），90= 垂直。需要 mPDF 7.0+ 才支持
watermarkAngle，你用的 8.2.7 完全支持。
image
仅图片水印使用。
支持两种路径：
相对
public目录：'/static/watermark.png'；绝对路径：
'/var/www/html/public/static/watermark.png'。建议用相对
public的写法，方便迁移。推荐 PNG 透明背景图，JPG 也可以但效果略差。
size
仅图片水印使用，控制水印尺寸：
'D'：Default，图片原始尺寸（默认值）；'P'：Page，缩放到适应整页；'F'：Fill，拉伸铺满整页；[width, height]：自定义尺寸，单位 mm，如[50, 50]。需要铺满整页做背景时用
'F'；需要精确控制大小时用数组。
position
仅图片水印使用，水印位置
[x, y]：单位 mm；
[0, 0]：左上角；负数表示向上、向左偏移，如
[-25, -25]；想要页面居中，可用负数偏移图片尺寸的一半。
注意：mPDF 的坐标原点在左上角，y 轴向下为正。
四、完整集成示例（PdfService 调用）
<?phpnamespace app\controller;use app\service\PdfService;use think\response\Json;class PdfController{
public function addWatermark(): Json
{
$pdfPath = 'storage/pdf/original.pdf';
// ===== 文字水印示例 =====
$textOptions = [
'type' => 'text',
'text' => "机密文件\n严禁外传",
'alpha' => 0.2,
'font' => 'GB',
'angle' => 45,
];
// ===== 图片水印示例 =====
$imageOptions = [
'type' => 'image',
'image' => '/static/watermark.png',
'alpha' => 0.3,
'size' => 'D',
'position' => [0, 0],
];
// 根据业务选择一种
$options = $textOptions; // 改成 $imageOptions 即切换为图片水印
try {
/** @var PdfService $service */
$service = app(PdfService::class);
$result = $service->addWatermark($pdfPath, $options);
return json([
'code' => 0,
'msg' => '水印添加成功',
'data' => ['url' => $result['url']],
]);
} catch (\Throwable $e) {
return json(['code' => 1, 'msg' => $e->getMessage()]);
}
}}五、对照速查表
| 场景 | type | 关键参数 |
|---|---|---|
| 单行中文水印 | text | text='机密文件', font='GB' |
| 两行中文水印 | text | text="机密\n外传" |
| 水平文字水印 | text | angle=0 |
| 极淡水印 | text / image | alpha=0.1 |
| 原始大小图片 | image | size='D' |
| 铺满整页图片 | image | size='F' |
| 自定义尺寸图片 | image | size=[50,50] |
| 图片居中 | image | position=[-25,-25]（配合 50×50 尺寸） |
六、注意事项
\n必须用双引号："a\nb"才换行，'a\nb'不换行。文字水印颜色固定：mPDF 内置文字水印只能黑色半透明，需要彩色请改用图片水印（用 GD 生成彩色 PNG）。
图片水印路径：推荐相对
public目录，如/static/watermark.png，PdfService会自动补全为绝对路径。图片水印尺寸单位是 mm：
[50, 50]表示 50mm × 50mm，不是像素。position支持负数：负数表示向左、向上偏移，常用于居中。两种水印不会同时生效：
type决定使用哪一组参数，另一组被忽略，符合你“二选一”的需求。
按上面这份说明配置 options 即可覆盖绝大多数水印场景。如果某个具体效果（比如多行行距、彩色水印）需要更精细控制，再走“GD 生成 PNG + 图片水印”的方案。
