app.xattr - 扩展属性与 Finder 标签 API

文件扩展属性（xattr）和 Finder 标签/注释操作。

扩展属性

app.xattr.get(path, name)

获取扩展属性值。

参数:

• path (string) - 文件路径
• name (string) - 属性名

返回值: string, error - 属性值（UTF-8 或 Base64 编码），失败时返回 nil, error

local value, err = app.xattr.get("/path/to/file", "com.example.custom")

app.xattr.set(path, name, value)

设置扩展属性。

参数:

• path (string) - 文件路径
• name (string) - 属性名
• value (string) - 属性值

返回值: boolean, error

local ok, err = app.xattr.set("/path/to/file", "com.example.custom", "my value")

app.xattr.list(path)

列出所有扩展属性名称。

参数:

• path (string) - 文件路径

返回值: array<string>, error

local names, err = app.xattr.list("/path/to/file")
for _, name in ipairs(names) do
    app.log.info("xattr: " .. name)
end

app.xattr.remove(path, name)

删除扩展属性。

参数:

• path (string) - 文件路径
• name (string) - 属性名

返回值: boolean, error

local ok, err = app.xattr.remove("/path/to/file", "com.example.custom")

Finder 标签

app.xattr.getTags(path)

获取文件的 Finder 标签列表。

参数:

• path (string) - 文件路径

返回值: array<string>, error - 标签名数组，失败时返回 nil, error

local tags = app.xattr.getTags("/path/to/file")
-- {"重要", "工作"}

app.xattr.setTags(path, tags)

设置文件的 Finder 标签（完全替换）。

参数:

• path (string) - 文件路径
• tags (array) - 标签名数组

返回值: boolean, error

app.xattr.setTags("/path/to/file", {"重要", "工作"})

app.xattr.addTag(path, tag)

添加单个 Finder 标签（不重复）。

参数:

• path (string) - 文件路径
• tag (string) - 标签名

返回值: boolean, error

app.xattr.addTag("/path/to/file", "重要")

app.xattr.removeTag(path, tag)

移除单个 Finder 标签。

参数:

• path (string) - 文件路径
• tag (string) - 标签名

返回值: boolean, error

app.xattr.removeTag("/path/to/file", "重要")

Finder 注释

app.xattr.getComment(path)

获取 Finder 注释。

参数:

• path (string) - 文件路径

返回值: string, error - 注释内容，失败时返回 nil, error

local comment = app.xattr.getComment("/path/to/file")

app.xattr.setComment(path, comment)

设置 Finder 注释。

参数:

• path (string) - 文件路径
• comment (string) - 注释内容

返回值: boolean, error

app.xattr.setComment("/path/to/file", "这是一个重要文件")

示例

批量添加标签

function MyPlugin:handleTagFiles(context)
    local result = app.dialog.input("输入标签名")
    if not result then return end

    local count = 0
    for _, file in ipairs(context.selectedFiles) do
        local ok = app.xattr.addTag(file, result)
        if ok then count = count + 1 end
    end

    app.notification.show("完成", "为 " .. count .. " 个文件添加了标签: " .. result)
end

查看文件元信息

function MyPlugin:handleShowInfo(context)
    local file = context.selectedFiles[1]
    local tags = app.xattr.getTags(file)
    local comment = app.xattr.getComment(file) or ""
    local attrs = app.xattr.list(file) or {}

    local info = "标签: " .. table.concat(tags, ", ") .. "\n"
    info = info .. "注释: " .. comment .. "\n"
    info = info .. "扩展属性数: " .. #attrs

    app.dialog.alert("文件信息", info)
end