Skip to content

图片 ​

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

输出选项:

选项说明
formatpng、jpeg(jpg)、webp、avif、tiff、bmp、gif、ico;省略时与输入相同
quality1–100。jpeg / webp / avif 默认 80(webp 为 100 时无损);png 默认无损,给出时量化为调色板
maxBytes按目标大小压缩(jpeg / webp / avif):找不超过目标的最高质量;达不到时结果的 reached 为 false
icoSizesICO 包含的尺寸,默认 [16, 32, 48, 256]
signalAbortSignal,取消时以 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) 进度回调。