图片
ling.image 在 lingtools 里处理图片:缩放、裁剪、旋转、加边框圆角水印,转格式、按目标大小压缩,以及拼长图、合成 GIF 和 PDF。不需要单独的权限,路径按文件权限的规则判断。
单图处理
ling.image(input) 开始一条链,链式添加步骤,最后用 toFile 或 toBuffer 执行:
ts
const result = await window.ling
.image('/Users/me/photo.heic.jpg')
.resize({ width: 1600 })
.round({ radius: 24 })
.toFile('/Users/me/Desktop/photo.webp', { format: 'webp', quality: 80 })
// { path, format: 'webp', width: 1600, height: 1200, size: 183402, quality: 80 }输入(ImageInput):绝对路径、Uint8Array / ArrayBuffer,或 data:image/…;base64, 的 Data URL。支持 PNG、JPEG、WebP、AVIF、GIF、BMP、TIFF、ICO(按内容判断格式);动图只取第一帧。
链是不可变的:每一步返回新对象,同一个前缀可以分叉复用,每次 toFile / toBuffer 都会完整执行一遍。
步骤
| 步骤 | 说明 |
|---|---|
resize({ width?, height?, fit?, enlarge? }) | 缩放。只给一边时等比;两边都给时 fit 为 'fill' 拉伸(默认)、'contain' 完整放入、'cover' 铺满后裁掉多余。enlarge: false 不放大 |
crop({ aspect: [16, 9], gravity? }) | 按比例取最大区域,gravity 为对齐方位(默认居中) |
crop({ x, y, width, height, origin? }) | 按矩形截取,origin 为坐标起点(默认左上角) |
rotate(angle, { background? }) | 顺时针旋转;90° 的倍数无损,其他角度扩大画布并用 background 填充 |
flip('horizontal' | 'vertical' | 'both') | 翻转 |
border({ width, color, opacity? }) | 向外加边框 |
round({ radius }) | 圆角,四角之外透明 |
overlay(image, { gravity?, width?, tile?, angle?, opacity?, margin? }) | 叠加图片水印;tile: true 平铺 |
flatten(color) | 把透明区域铺上颜色 |
长度可以写像素数字,也可以写 '50%' 这样的百分比。方位(gravity)取值:top-left、top、top-right、left、center、right、bottom-left、bottom、bottom-right。颜色写 #RRGGBB、#RRGGBBAA 或 'transparent'。
输出
| 方法 | 说明 |
|---|---|
toFile(path, options?) | 写入文件,上级目录须已存在。目标已存在时默认报错(data.code 为 EEXIST),exists: 'overwrite' 覆盖。先写临时文件再改名,失败不会留下半个文件 |
toBuffer(options?) | 返回 { data: Uint8Array, format, width, height, size },上限 128 MiB |
输出选项:
| 选项 | 说明 |
|---|---|
format | png、jpeg(jpg)、webp、avif、tiff、bmp、gif、ico;省略时与输入相同 |
quality | 1–100。jpeg / webp / avif 默认 80(webp 为 100 时无损);png 默认无损,给出时量化为调色板 |
maxBytes | 按目标大小压缩(jpeg / webp / avif):找不超过目标的最高质量;达不到时结果的 reached 为 false |
icoSizes | ICO 包含的尺寸,默认 [16, 32, 48, 256] |
signal | AbortSignal,取消时以 aborted 失败 |
输出为不支持透明的格式(jpeg、bmp)时,没有 flatten 会自动铺白色。
文字水印
ts
const watermark = await window.ling.image.textToImage('© lingtools', {
fontSize: 28,
color: '#FFFFFFCC',
scale: 2,
})
await window.ling
.image(input)
.overlay(watermark, { gravity: 'bottom-right', margin: 24, opacity: 0.8 })
.toFile(output)textToImage(text, { fontSize?, color?, fontFamily?, fontWeight?, padding?, scale? }) 在页面里把一行文字画成 PNG 字节。Node 后端里没有画布,不能调用。
读取信息
ts
const info = await window.ling.image.metadata(path)
// { format: 'jpeg', width: 4032, height: 3024, size: 2841203, frames: 1, … }只读文件头,速度很快。宽高已按 EXIF 方向摆正。
多图合成
| 方法 | 说明 |
|---|---|
image.merge(inputs, { direction, size, background?, padding?, gap? }) | 拼成一张长图(最多 500 张)。direction 为 'vertical' / 'horizontal';size 为画布宽度(竖拼)或高度(横拼)。返回的链还能继续处理 |
image.gif(frames, { width?, height?, delay?, background?, loop? }) | 合成 GIF(最多 500 帧,每边不超过 4096)。delay 为每帧毫秒数(默认 1000),可以是数组;loop: 0 无限循环 |
image.pdf(inputs, { pageSize?, orientation?, margin? }) | 合成 PDF,每张图一页(最多 500 张)。pageSize:A3 A4(默认)A5 Letter Legal fit(与图同大)或 { width, height }(单位 pt) |
ts
await window.ling.image
.merge(screenshots, { direction: 'vertical', size: 1080, gap: 16, padding: { x: 24, y: 24 } })
.toFile(`${dir}/long.png`)
await window.ling.image
.pdf(scans, { pageSize: 'A4', margin: 36 })
.toFile(`${dir}/scans.pdf`, {
onProgress: (done, total) => (progress.value = done / total),
})gif 和 pdf 支持 onProgress(done, total) 进度回调。