📋 目录
一、工具类功能
用 JDK 自带的 Graphics2D 给图片打文字水印或叠加 Logo,按九宫格定位并留出边距,订单截图盖章、商品图防盗、凭证标注这类「服务端出图」的场合直接可用。
二、所需环境
JDK 17或以上
三、方法与调用示例(按需调用)
🔢 方法序号:1
🎯 方法用途:
- 用最省事的一档给图片打文字水印,固定落在右下角,SansSerif 24 号黑色、透明度 0.5、不旋转、与边留 10 像素
- 订单截图、凭证图盖「仅供审计」这类标记时用,要改位置、字号或角度就走全参入口
🧩 方法定义:public static void addTextWatermark(Path srcFile, Path destFile, String watermarkText)
🗣️ 入参解释:public static void addTextWatermark(源图片, 输出图片, 水印文字)
📤 返回值解释:void,成品图按 destFile 的后缀写到磁盘上,方法本身不返回信息
💡 边界口径:
- 内部直接委托全参入口,九个可选项全部按默认值填,默认边距就是 10 像素
- 输出格式只认 jpg、jpeg、png、gif,后缀认不出来直接抛异常,不产出「后缀写 png、内容是 JPEG」的文件
- destFile 缺的父目录会自动创建,源图不存在或路径是个目录都抛异常
- 水印文字按换行拆行绘制,CRLF、CR、LF 都认;整串只剩换行符按空白处理并抛异常
- JPEG 没有透明通道,源图的透明区域按白底合成,PNG 与 GIF 保留 alpha 通道
🧪 方法示例:
addTextWatermark(photo, defaultOut, "FOR AUDIT ONLY")输出路径上两层不存在的目录被自动建好,文件存在性拿到true- 同一份产物的水印像素包围盒拿到
(193,206)~(389,222) - 检查它的右缘是否停在「画布宽 - 默认间距 10」且整块落在下半幅,拿到
true - 读回产物宽高与原图比对,尺寸拿到
400x240 - 把全透明源图写成 jpg,角落颜色拿到
R255/G255/B255,透明区按白底合成 - 这份 jpg 色彩模型的 hasAlpha 拿到
false - 同一张全透明源图写成 png,未叠加处的 alpha 通道值拿到
0 - 这份 png 的 hasAlpha 拿到
true,透明通道留住了 - 输出后缀给
bad.bmp时抛无法从输出文件后缀识别图片格式,支持的后缀为 jpg/jpeg/png/gif,当前为: bad.bmp - 水印文字只有一个换行符时抛
水印文字不能为null或空白
🔢 方法序号:2
🎯 方法用途:
- 文字水印的全参入口:九宫格位置、字体名、字号、颜色、透明度、旋转角度、边距全部可指定
- 需要把水印挪到左上角、放大字号、压淡颜色或者斜着铺在图上时用这一版
🧩 方法定义:public static void addTextWatermark(Path srcFile, Path destFile, String watermarkText, Position position, String fontName, int fontSize, Color color, float opacity, double angle, int margin)
🗣️ 入参解释:public static void addTextWatermark(源图片, 输出图片, 水印文字, 九宫格位置, 字体名, 字号, 文字颜色, 透明度, 旋转角度, 边距)
📤 返回值解释:void,成品图按 destFile 的后缀写到磁盘上
💡 边界口径:
- 字号必须大于 0,透明度必须在 0.0~1.0,边距不可为负,旋转角度必须是有限值
- position、文字颜色不可为 null,字体名与水印文字不可为 null 或空白
- 多行文字逐行绘制,行高取字体的行高,旋转时绕首行起点整体转,多行排版不会散开
- 角度正值在画面上顺时针倾斜,旋转后的外接矩形变大,而位置算的是旋转前的矩形,仍收敛在画布内
- 字体缺失不报错,中文只会渲染成方框,只能靠像素检查发现
- 位置描述的是水印外接矩形,文字会按字体度量把基线换算进矩形内,同一路径下与图片水印视觉对齐
🧪 方法示例:
addTextWatermark(photo, blue, "APPROVED", ImageWatermarkUtils.Position.TOP_LEFT, Font.SANS_SERIF, 48, new Color(0, 0, 255), 1.0f, 0, MARGIN)的水印像素包围盒拿到(9,23)~(274,59)- 这份不透明纯蓝产物的最浓像素颜色拿到
R0/G0/B255 - 同样的参数只把透明度降到 0.3,最浓像素被白底稀释成
R178/G178/B255 - 单行文字的墨迹带数拿到
1 - 文字里放一个换行后,墨迹带数拿到
2 - 按同一入口画一串中文,非白像素拿到
2520,至于显示成正文还是方框取决于服务端装了哪些字体 - 水平放置时
ABCDEFGH的包围盒拿到(9,22)~(229,50) - 同一份文字转 30 度后包围盒拿到
(0,26)~(193,155),高度比水平时多出101像素 - 30 度时右半像素平均行号
115.6大于左半的63.1,视觉上就是顺时针下斜 - 字号给 0 时抛
字号必须大于0,当前为0
🔢 方法序号:3
🎯 方法用途:
- 把 Logo 图按九宫格位置叠到源图上,不旋转,可指定透明度和边距
- 商品图批量贴品牌角标、给导出图加固定位置标记时用
🧩 方法定义:public static void addImageWatermark(Path srcFile, Path logoFile, Path destFile, Position position, float opacity, int margin)
🗣️ 入参解释:public static void addImageWatermark(源图片, 水印图片, 输出图片, 九宫格位置, 透明度, 边距)
📤 返回值解释:void,叠加结果按 destFile 的后缀写到磁盘上
💡 边界口径:
- 只是把七参入口的旋转角度固定为 0,其余校验与七参版一致
- Logo 按自身原始尺寸贴上去,本类不做缩放;比画布大时超出部分被裁掉,水印仍从 (0,0) 铺满画布而不是消失
- 边距比画布还大时坐标被收敛回边界内,结果照样贴边可见
- 源图与 Logo 都要求存在且是普通文件,能存在但 ImageIO 解析不了抛
IllegalStateException,消息里区分「源图片」与「水印图片」 - 源图与 Logo 都会先复制成 ARGB 画布,索引色、灰度图不会限制绘制
🧪 方法示例:
- 九个位置各跑一遍,
TOP_LEFT的外接矩形拿到(10,10)~(69,39) BOTTOM_RIGHT的外接矩形拿到(330,200)~(389,229)- 九个位置与手算的九宫格矩形逐一比对,完全一致的有
9个 - 边距给 0 时左上角贴边,包围盒拿到
(0,0)~(59,29) - 边距给 500,比 400x240 的画布还大,坐标被收敛回来,包围盒仍是
(0,0)~(59,29) - 800x600 的大 Logo 压到 400x240 的图上,水印覆盖盒拿到
(0,0)~(399,239) - position 传 null 抛
position 不能为null - 透明度给 1.5 抛
透明度必须在0.0~1.0之间,当前为1.5 - 边距给 -1 抛
边距不能为负数,当前为-1 - destFile 只给到盘根抛
destFile 必须是文件名路径,不能是根目录,消息末尾带上这个路径 - Logo 换成一个纯文本文件时抛
IllegalStateException,消息是「无法解析水印图片(格式不支持或文件损坏)」再补上文件路径
🔢 方法序号:4
🎯 方法用途:
- 在六参入口上多给一个旋转角度,Logo 绕自身中心转指定角度后再摆到九宫格位置
- 需要斜铺样张标记、或者让角标倾斜出现时用
🧩 方法定义:public static void addImageWatermark(Path srcFile, Path logoFile, Path destFile, Position position, float opacity, double angle, int margin)
🗣️ 入参解释:public static void addImageWatermark(源图片, 水印图片, 输出图片, 九宫格位置, 透明度, 旋转角度, 边距)
📤 返回值解释:void,叠加结果按 destFile 的后缀写到磁盘上
💡 边界口径:
- 旋转中心是水印外接矩形的中心点,position 与 margin 定的仍是旋转前的矩形,转角后像素向四周扩出去
- 角度必须是有限值,
Double.NaN与Infinity都抛异常 - 透明度 0.0 时一个水印像素都落不下,但文件仍正常写出
- 淡化效果既可以压 opacity,也可以用自带 alpha 的 Logo,两条路叠加结果一致
- 绘制开着抗锯齿与双线性插值,旋转边缘不会出锯齿
🧪 方法示例:
- 60x30 的 Logo 放
Position.CENTER不旋转,包围盒拿到(170,105)~(229,134) - 同样设置绕中心转 45 度,包围盒拿到
(168,88)~(231,151) - 45 度时右半像素平均行号
127.0大于左半的111.2,即画面顺时针 - 不透明 Logo 配 opacity 0.5,中心像素拿到
R255/G127/B127 - 换成自带半透明的 Logo、opacity 给 1.0,中心像素同样是
R255/G127/B127 - opacity 给 0.0 时统计到的水印像素数拿到
0 - 角度给
Double.NaN抛旋转角度必须是有限值,当前为NaN
四、工具类源码(可直接复制)
📦 源码文件