app.settings - 插件设置 API

持久化存储插件配置。每个插件有独立的 settings.json 文件。

方法

app.settings.get(key, default?)

获取设置值。

参数:

• key (string) - 设置键名
• default (any, 可选) - 默认值

返回值: 存储的值或默认值

local quality = app.settings.get("quality", 90)
local format = app.settings.get("format", "PNG")
local enabled = app.settings.get("autoBackup", true)

app.settings.set(key, value)

保存设置值。

参数:

• key (string) - 设置键名
• value (any) - 要保存的值（支持 string, number, boolean, table）

返回值: boolean, error - 是否成功，失败时返回 false, error

app.settings.set("quality", 90)
app.settings.set("format", "PNG")
app.settings.set("autoBackup", true)
app.settings.set("recentPaths", {"/Users/test/Desktop", "/Users/test/Downloads"})

app.settings.remove(key)

删除设置项。

参数:

• key (string) - 设置键名

返回值: boolean, error - 是否成功，失败时返回 false, error

app.settings.remove("tempData")

app.settings.has(key)

检查设置项是否存在。

参数:

• key (string) - 设置键名

返回值: boolean, error - 失败时返回 false, error

if app.settings.has("apiKey") then
    -- 使用已配置的 API Key
else
    -- 提示用户配置
end

app.settings.clear()

清除插件的所有设置。

返回值: boolean, error - 是否成功，失败时返回 false, error

app.settings.clear()

app.settings.getAll()

获取所有设置。

返回值: table, error - 所有设置的键值对，失败时返回 nil, error

local all = app.settings.getAll()
if all then
    for key, value in pairs(all) do
        app.log.info(key .. " = " .. tostring(value))
    end
end

存储位置

设置存储在插件目录中的 settings.json 文件：

~/Library/Group Containers/group.net.ymlab.iRightMenu.pro/
  └── Plugins/
      └── {plugin_id}/
          └── settings.json

支持的值类型

示例

记住上次设置

function MyPlugin:showSettingsDialog()
    -- 加载上次的设置
    local lastSettings = {
        quality = app.settings.get("lastQuality", 90),
        format = app.settings.get("lastFormat", "PNG"),
        outputDir = app.settings.get("lastOutputDir", app.path.desktop())
    }

    -- 显示设置对话框
    local result = app.dialog.form({
        title = "导出设置",
        fields = {
            {type = "number", id = "quality", label = "质量", default = lastSettings.quality},
            {type = "select", id = "format", label = "格式",
             options = {"PNG", "JPEG", "WebP"}, default = lastSettings.format},
            {type = "text", id = "outputDir", label = "输出目录", default = lastSettings.outputDir}
        }
    })

    if result then
        -- 保存本次设置供下次使用
        app.settings.set("lastQuality", result.quality)
        app.settings.set("lastFormat", result.format)
        app.settings.set("lastOutputDir", result.outputDir)

        return result
    end

    return nil
end

使用设置配置插件行为

function MyPlugin:handleCompress(context)
    -- 读取用户配置的设置
    local quality = app.settings.get("quality", 90)
    local format = app.settings.get("format", "PNG")
    local autoBackup = app.settings.get("autoBackup", true)

    for _, file in ipairs(context.selectedFiles) do
        if autoBackup then
            app.file.copy(file, file .. ".backup")
        end

        self:compressImage(file, {
            quality = quality,
            format = format
        })
    end
end

存储复杂数据

-- 存储最近使用的项目
function MyPlugin:addToRecent(path)
    local recent = app.settings.get("recentItems", {})

    -- 移除已存在的
    for i, item in ipairs(recent) do
        if item == path then
            table.remove(recent, i)
            break
        end
    end

    -- 添加到开头
    table.insert(recent, 1, path)

    -- 只保留最近 10 个
    while #recent > 10 do
        table.remove(recent)
    end

    app.settings.set("recentItems", recent)
end

function MyPlugin:getRecent()
    return app.settings.get("recentItems", {})
end

重置设置

function MyPlugin:handleResetSettings(context)
    local confirm = app.dialog.alert({
        title = "重置设置",
        message = "确定要重置所有设置为默认值吗？",
        buttons = {"取消", "重置"}
    })

    if confirm == "重置" then
        app.settings.clear()
        app.notification.show("完成", "设置已重置")
    end
end