app.image - 图片处理 API

图片信息获取、格式转换、调整大小等操作。

基础信息

app.image.size(path)

获取图片尺寸（像素）。

参数:

• path (string) - 图片文件路径

返回值: table|nil - {width, height} 或 nil

local size = app.image.size("/path/to/image.jpg")
if size then
    app.log.info("尺寸: " .. size.width .. "x" .. size.height)
end

app.image.format(path)

获取图片格式。

参数:

• path (string) - 图片文件路径

返回值: string|nil - 格式名称（jpeg, png, gif, tiff, bmp, webp, heic）

local format = app.image.format("/path/to/image.jpg")  -- "jpeg"

转换操作

app.image.convert(srcPath, destPath, format?)

转换图片格式。

参数:

• srcPath (string) - 源图片路径
• destPath (string) - 目标路径
• format (string, 可选) - 目标格式（不指定则根据目标文件扩展名判断）

返回值: boolean - 是否成功

-- 根据扩展名自动判断格式
app.image.convert("/path/to/image.jpg", "/path/to/image.png")

-- 显式指定格式
app.image.convert("/path/to/image.png", "/path/to/output.jpg", "jpeg")

app.image.resize(srcPath, destPath, width, height)

调整图片大小。

参数:

• srcPath (string) - 源图片路径
• destPath (string) - 目标路径
• width (number) - 目标宽度
• height (number) - 目标高度

返回值: boolean - 是否成功

app.image.resize("/path/to/image.jpg", "/path/to/thumb.jpg", 200, 150)

app.image.scale(srcPath, destPath, factor)

按比例缩放图片。

参数:

• srcPath (string) - 源图片路径
• destPath (string) - 目标路径
• factor (number) - 缩放因子（如 0.5 表示缩小一半，2.0 表示放大一倍）

返回值: boolean - 是否成功

-- 缩小到 50%
app.image.scale("/path/to/image.jpg", "/path/to/half.jpg", 0.5)

-- 放大 2 倍
app.image.scale("/path/to/image.jpg", "/path/to/double.jpg", 2.0)

其他操作

app.image.rotate(srcPath, destPath, degrees)

旋转图片。

参数:

• srcPath (string) - 源图片路径
• destPath (string) - 目标路径
• degrees (number) - 旋转角度（顺时针）

返回值: boolean - 是否成功

app.image.rotate("/path/to/image.jpg", "/path/to/rotated.jpg", 90)

app.image.crop(srcPath, destPath, x, y, width, height)

裁剪图片。

参数:

• srcPath (string) - 源图片路径
• destPath (string) - 目标路径
• x (number) - 起始 X 坐标
• y (number) - 起始 Y 坐标
• width (number) - 裁剪宽度
• height (number) - 裁剪高度

返回值: boolean - 是否成功

app.image.crop("/path/to/image.jpg", "/path/to/cropped.jpg",
    100, 100, 500, 300)

app.image.exif(path)

获取图片的 EXIF 及元数据信息。

参数:

• path (string) - 图片文件路径

返回值: table, error - 包含以下字段:

• pixelWidth (number) - 像素宽度
• pixelHeight (number) - 像素高度
• dpiWidth (number) - DPI 宽度
• dpiHeight (number) - DPI 高度
• colorModel (string) - 颜色模型
• depth (number) - 位深度
• orientation (number) - 方向
• exif (table) - EXIF 子字典
• tiff (table) - TIFF 子字典
• gps (table) - GPS 子字典

local info, err = app.image.exif("/path/to/photo.jpg")
if info then
    app.log.info("尺寸: " .. info.pixelWidth .. "x" .. info.pixelHeight)
    if info.exif then
        app.log.info("EXIF 数据: " .. app.json.stringify(info.exif))
    end
end

app.image.thumbnail(srcPath, destPath, maxSize)

生成缩略图，保持原始宽高比。

参数:

• srcPath (string) - 源图片路径
• destPath (string) - 目标路径
• maxSize (number) - 最大边长（像素）

返回值: boolean, error

local ok, err = app.image.thumbnail("/path/to/photo.jpg", "/path/to/thumb.jpg", 200)

app.image.watermark(srcPath, destPath, text, options?)

添加文字水印。

参数:

• srcPath (string) - 源图片路径
• destPath (string) - 目标路径
• text (string) - 水印文字
• options (table, 可选):
  • fontSize (number) - 字体大小（默认 24）
  • opacity (number) - 透明度 0-1（默认 0.5）
  • position (string) - 位置: "topLeft", "topRight", "bottomLeft", "bottomRight"（默认）, "center"
  • color (string) - 颜色: "white"（默认）, "black", "red", "blue", "green", "gray"

返回值: boolean, error

local ok, err = app.image.watermark(
    "/path/to/photo.jpg",
    "/path/to/watermarked.jpg",
    "© 2024 My Company",
    {fontSize = 36, opacity = 0.3, position = "bottomRight", color = "white"}
)

app.image.flip(srcPath, destPath, direction)

翻转图片。

参数:

• srcPath (string) - 源图片路径
• destPath (string) - 目标路径
• direction (string) - 翻转方向: "horizontal" 或 "vertical"

返回值: boolean, error

app.image.flip("/path/to/image.jpg", "/path/to/flipped.jpg", "horizontal")

app.image.grayscale(srcPath, destPath)

将图片转为灰度。

参数:

• srcPath (string) - 源图片路径
• destPath (string) - 目标路径

返回值: boolean, error

app.image.grayscale("/path/to/image.jpg", "/path/to/gray.jpg")

app.image.composite(basePath, overlayPath, destPath, options?)

将一张图片叠加到另一张上。

参数:

• basePath (string) - 底图路径
• overlayPath (string) - 叠加图路径
• destPath (string) - 目标路径
• options (table, 可选):
  • x (number) - 叠加 X 坐标（默认 0）
  • y (number) - 叠加 Y 坐标（默认 0）
  • opacity (number) - 叠加透明度 0-1（默认 1.0）

返回值: boolean, error

app.image.composite(
    "/path/to/background.jpg",
    "/path/to/logo.png",
    "/path/to/result.jpg",
    {x = 50, y = 50, opacity = 0.8}
)

示例

批量生成缩略图

function MyPlugin:handleThumbnails(context)
    local result = app.dialog.form({
        title = "生成缩略图",
        fields = {
            {type = "number", id = "width", label = "宽度", default = 200},
            {type = "number", id = "height", label = "高度", default = 200}
        }
    })

    if not result then return end

    local thumbDir = app.path.join(context.currentDirectory, "thumbnails")
    app.file.mkdir(thumbDir)

    local count = 0
    for _, file in ipairs(context.selectedFiles) do
        local size = app.image.size(file)
        if size then
            local thumbPath = app.path.join(thumbDir, app.path.basename(file))

            if app.image.resize(file, thumbPath, result.width, result.height) then
                count = count + 1
            end
        end
    end

    app.notification.show("完成", "生成了 " .. count .. " 张缩略图")
    app.finder.reveal(thumbDir)
end

批量转换格式

function MyPlugin:handleConvertToPNG(context)
    local count = 0
    for _, file in ipairs(context.selectedFiles) do
        local format = app.image.format(file)
        if format and format ~= "png" then
            local destPath = app.path.removeExtension(file) .. ".png"

            if app.image.convert(file, destPath) then
                count = count + 1
            end
        end
    end

    app.notification.show("完成", "转换了 " .. count .. " 张图片为 PNG")
end