app.dock - Dock 角标/弹跳 API

控制应用 Dock 图标的角标和弹跳提醒。

权限: L1（standard）— 需要在插件 manifest 中声明 app.dock 权限。

方法

app.dock.setBadge(text)

设置 Dock 角标文字。

参数:

• text (string|number) - 角标文字（数字或文字，空字符串清除角标）

返回值: boolean, error

app.dock.setBadge("5")       -- 显示数字角标
app.dock.setBadge("新")      -- 显示文字角标
app.dock.setBadge("")         -- 清除角标
app.dock.setBadge(42)         -- 数字自动转为字符串

app.dock.getBadge()

获取当前 Dock 角标文字。

返回值: string - 当前角标文字，无角标时返回空字符串

local badge = app.dock.getBadge()
app.log.info("当前角标: " .. badge)

app.dock.removeBadge()

清除 Dock 角标。等价于 setBadge("")。

返回值: boolean, error

app.dock.removeBadge()

app.dock.bounce(type?)

弹跳 Dock 图标以引起用户注意。

参数:

• type (string, 可选) - 弹跳类型:
  • "informational" (默认) - 弹跳一次
  • "critical" - 持续弹跳直到用户切换到应用

返回值: number, error - 请求 ID（用于 cancelBounce()）

-- 温和弹跳（一次）
local id = app.dock.bounce()

-- 持续弹跳
local id = app.dock.bounce("critical")

-- 稍后停止弹跳
app.dock.cancelBounce(id)

app.dock.cancelBounce(id)

停止 Dock 弹跳。

参数:

• id (number) - bounce() 返回的请求 ID

返回值: boolean, error

local id = app.dock.bounce("critical")
-- ... 某些操作后 ...
app.dock.cancelBounce(id)

说明

• 无需清理，不占用持久资源
• "critical" 弹跳会持续到用户激活应用或调用 cancelBounce()

示例

文件处理完成后通知

function MyPlugin:handleProcess(context)
    local files = context.selectedFiles
    app.dock.setBadge(tostring(#files))

    for i, file in ipairs(files) do
        -- 处理文件...
        app.dock.setBadge(tostring(#files - i))
    end

    app.dock.removeBadge()
    app.dock.bounce()
    app.notification.show("完成", "已处理 " .. #files .. " 个文件")
end