app.defaults - UserDefaults API

读写 macOS 应用偏好设置（UserDefaults/defaults 命令的原生替代）。

权限: 需在 manifest 中声明 defaults（L1 standard）

方法

app.defaults.read(domain, key)

读取指定域的偏好设置值。

参数:

• domain (string) - 偏好设置域（应用 Bundle ID 或特殊域名）
• key (string) - 键名

返回值: any|nil, error - 值或 nil（不存在），支持 string/number/boolean/table

-- 读取 Finder 设置
local showHidden = app.defaults.read("com.apple.finder", "AppleShowAllFiles")
app.log.info("显示隐藏文件: " .. tostring(showHidden))

-- 读取 Dock 设置
local dockSize = app.defaults.read("com.apple.dock", "tilesize")
app.log.info("Dock 图标大小: " .. tostring(dockSize))

-- 读取全局设置
local darkMode = app.defaults.read("NSGlobalDomain", "AppleInterfaceStyle")
app.log.info("外观: " .. (darkMode or "Light"))

app.defaults.write(domain, key, value)

写入偏好设置值。设置 nil 等同于删除。

参数:

• domain (string) - 偏好设置域
• key (string) - 键名
• value (any) - 值（string/number/boolean/table/nil）

返回值: boolean, error

-- 显示 Finder 隐藏文件
app.defaults.write("com.apple.finder", "AppleShowAllFiles", true)

-- 设置自定义偏好
app.defaults.write("com.example.myapp", "lastOpenPath", "/Users/test")

app.defaults.delete(domain, key)

删除指定键。

参数:

• domain (string) - 偏好设置域
• key (string) - 键名

返回值: boolean, error

app.defaults.delete("com.apple.finder", "AppleShowAllFiles")

app.defaults.readAll(domain)

读取指定域的所有偏好设置。

参数:

• domain (string) - 偏好设置域

返回值: table, error - 所有键值对

local all = app.defaults.readAll("com.apple.finder")
if all then
    for key, value in pairs(all) do
        app.log.info(key .. " = " .. tostring(value))
    end
end

常用域名

任何应用的 Bundle ID 都可以作为域名读取其偏好设置。

类型转换

示例

切换 Finder 隐藏文件显示

function MyPlugin:handleToggleHidden(context)
    local current = app.defaults.read("com.apple.finder", "AppleShowAllFiles")
    local newValue = not current

    app.defaults.write("com.apple.finder", "AppleShowAllFiles", newValue)

    -- 重启 Finder 生效
    app.shell.execute("killall Finder")

    app.notification.show(
        "Finder 设置",
        newValue and "已显示隐藏文件" or "已隐藏隐藏文件"
    )
end

读取截图设置

function MyPlugin:handleScreenshotInfo(context)
    local domain = "com.apple.screencapture"

    local location = app.defaults.read(domain, "location") or "~/Desktop"
    local fileType = app.defaults.read(domain, "type") or "png"
    local shadow = app.defaults.read(domain, "disable-shadow")

    local info = string.format(
        "保存位置: %s\n格式: %s\n窗口阴影: %s",
        location, fileType, shadow and "关闭" or "开启"
    )

    app.dialog.alert({title = "截图设置", message = info})
end

备份和恢复应用偏好

function MyPlugin:handleBackupDefaults(context)
    local domain = "com.example.myapp"
    local all = app.defaults.readAll(domain)

    if not all then
        app.dialog.alert({title = "错误", message = "无法读取偏好设置"})
        return
    end

    -- 导出为 JSON
    local json = app.json.stringify(all, true)
    local savePath = app.dialog.saveFile({
        title = "导出偏好设置",
        nameFieldValue = domain .. ".json"
    })

    if savePath then
        app.file.write(savePath, json)
        app.notification.show("导出完成", app.path.basename(savePath))
    end
end

与 app.settings 的区别

注意事项

1. 权限：修改系统应用的偏好设置可能需要重启该应用才能生效
2. 沙箱限制：部分系统域在沙箱中可能无法写入
3. 区分场景：存储插件自身配置请使用 app.settings，app.defaults 用于读写其他应用的偏好
4. 数据格式：Data 类型自动转为 base64 字符串，Date 类型转为 Unix 时间戳