Skip to content

k.utils.image ​

图片格式、尺寸与水印

概述 ​

k.utils.image 在脚本中处理图片字节或站点 FileInfo。

changeFormat() ​

将图片字节转为新扩展名对应格式。

参数类型必填说明
binarynumber[]是原始图片字节,可来自 k.file.readBinary() 或上传文件
newExtensionstring是目标格式扩展名,如 .webp、.png、.jpg

返回: number[],转换后的图片字节。

ts
const jpg = k.file.readBinary("media/source.jpg")
const webp = k.utils.image.changeFormat(jpg, ".webp")

k.file.writeBinary("media/source.webp", webp)
return k.file.get("media/source.webp")

resize() ​

重载说明
resize(file, height, width, saveAs?)调整站点文件
resize(bytes, height, width)调整字节数组
参数类型必填说明
fileFileInfo是站点文件对象,通常来自 k.file.get()
bytesnumber[]是图片字节数组
heightnumber是目标高度。字节数组重载中传 0 时会按宽度等比计算
widthnumber是目标宽度。字节数组重载中传 0 时会按高度等比计算
saveAsstring否站点文件保存路径;不传时覆盖原文件

返回:

重载返回
resize(file, height, width, saveAs?)FileInfo,调整后的站点文件
resize(bytes, height, width)number[],调整后的图片字节

处理站点文件时,先通过 k.file.get() 取得 FileInfo:

ts
const original = k.file.get("media/product.jpg")
const resized = k.utils.image.resize(original, 600, 800, "media/product-800.jpg")

return {
    url: resized.url,
    size: resized.size
}

处理上传文件或接口返回的字节时,使用字节数组重载:

ts
const file = k.request.files[0]
const thumbnail = k.utils.image.resize(file.bytes, 240, 240)
k.file.writeBinary(`media/thumbs/${file.fileName}`, thumbnail)

changeDpi() ​

修改 DPI 并保存为站点文件。

参数类型必填说明
fileUploadFile | FileInfo是上传文件或站点文件对象
targetDpinumber是目标 DPI;小于 72 时按 72 处理
saveAsstringUploadFile 必填,FileInfo 可选保存路径。FileInfo 重载不传时覆盖原文件

返回: FileInfo,保存后的站点文件。

ts
const source = k.file.get("media/print-cover.jpg")
const output = k.utils.image.changeDpi(source, 300, "media/print-cover-300dpi.jpg")

return {
    path: output.fullName,
    size: output.size
}

addWatermark() ​

为图片字节添加水印;WatermarkOptions 含 align、justify、opacity、offsetX/Y、repeat。

参数类型必填说明
binarynumber[]是原图字节
watermarknumber[]是水印图字节
optionWatermarkOptions是水印位置、透明度与重复方式

返回: number[],加水印后的图片字节。

WatermarkOptions ​

属性类型说明
alignstring垂直位置:top、center、bottom
justifystring水平位置:left、center、right
opacitynumber透明度,通常为 0 到 1
offsetXnumber水平方向偏移比例,例如 0.04 表示 4%
offsetYnumber垂直方向偏移比例
repeatboolean是否平铺水印
ts
const image = k.file.readBinary("media/product.jpg")
const watermark = k.file.readBinary("media/watermark.png")

const output = k.utils.image.addWatermark(image, watermark, {
    align: "bottom",
    justify: "right",
    offsetX: 0.04,
    offsetY: 0.04,
    opacity: 0.8,
    repeat: false
})

k.file.writeBinary("media/product-watermarked.jpg", output)

getSize() / getFrameCount() / getGifFrameCount() / convertToTwoFramesGif() ​

读取尺寸、帧数或转换 GIF。

方法参数返回说明
getSize(image)number[]{ width, height }读取图片尺寸
getFrameCount(image)number[]number读取 GIF / WebP 帧数
getGifFrameCount(image)number[]number旧帧数方法;以 getFrameCount() 为主
convertToTwoFramesGif(image)number[]number[]转为两帧 GIF 字节
ts
const image = k.file.readBinary("media/banner.jpg")
const size = k.utils.image.getSize(image)

return {
    width: size.width,
    height: size.height
}

getFrameCount() 支持 GIF / WebP 帧数读取;convertToTwoFramesGif() 可把动图收敛为两帧 GIF。

ts
const animation = k.file.readBinary("media/loading.webp")
const frameCount = k.utils.image.getFrameCount(animation)

if (frameCount > 2) {
    const gif = k.utils.image.convertToTwoFramesGif(animation)
    k.file.writeBinary("media/loading-preview.gif", gif)
}

相关文档 ​