app.progress - 进度对话框 API

显示和控制进度对话框。提供简单 API（按插件隔离）和高级 API（多实例）两种用法。

简单 API（推荐）

简单 API 每个插件只能同时显示一个进度对话框，适合大多数场景。

app.progress.show(title, config?)

显示进度对话框。如果当前插件已有进度对话框，会先关闭它。

参数:

• title (string) - 对话框标题
• config (table, 可选):
  • message (string) - 详细消息
  • indeterminate (boolean) - 是否为不确定进度（默认 true）
  • cancellable (boolean) - 是否可取消（默认 false）
  • onCancel (function) - 取消回调

返回值: boolean - 是否成功显示

-- 简单用法
app.progress.show("处理中")

-- 带配置
app.progress.show("正在处理", {
    message = "请稍候...",
    indeterminate = false,
    cancellable = true,
    onCancel = function()
        app.log.info("用户取消了操作")
    end
})

-- 也可以直接传 config 表
app.progress.show({
    title = "正在处理",
    message = "请稍候...",
    indeterminate = false
})

app.progress.update(value, message?)

更新进度值和消息。

参数:

• value (number) - 当前进度值（0-100）
• message (string, 可选) - 更新消息

for i = 1, 100 do
    app.progress.update(i, "处理第 " .. i .. " 项")
    -- 执行操作...
end

app.progress.setMessage(message)

仅更新消息文本，不改变进度值。

参数:

• message (string) - 新消息

app.progress.setMessage("正在执行步骤 2...")

app.progress.isCancelled()

检查用户是否已取消当前进度对话框。需要配合 cancellable = true 使用。

返回值: boolean - 是否已取消

app.progress.show("处理中", {
    indeterminate = false,
    cancellable = true
})

for i = 1, 100 do
    if app.progress.isCancelled() then
        break
    end
    app.progress.update(i, "步骤 " .. i)
end

app.progress.hide()

app.progress.hide()

关闭进度对话框。

app.progress.hide()

高级 API（多实例）

当需要同时显示多个进度对话框时，使用高级 API。

app.progress.create(config)

创建并显示新的进度对话框实例。

参数:

• config (table):
  • title (string, 必需) - 对话框标题
  • message (string) - 详细消息
  • indeterminate (boolean) - 是否为不确定进度（默认 true）
  • cancellable (boolean) - 是否可取消（默认 false）
  • onCancel (function) - 取消回调

返回值: progressHandle - 进度句柄对象

local progress = app.progress.create({
    title = "下载文件",
    message = "准备中...",
    indeterminate = false,
    cancellable = true,
    onCancel = function()
        app.log.info("下载已取消")
    end
})

progressHandle:update(value, message?)

更新进度句柄的进度值和消息。

参数:

• value (number) - 当前进度值（0-100）
• message (string, 可选) - 更新消息

progress:update(50, "已完成 50%")

progressHandle:setMessage(message)

更新进度句柄的消息文本。

参数:

• message (string) - 新消息

progress:setMessage("正在处理...")

progressHandle:isCancelled()

检查用户是否已取消该进度对话框。

返回值: boolean - 是否已取消

if progress:isCancelled() then
    progress:close()
    return
end

progressHandle:close()

关闭进度句柄对应的对话框。

progress:close()

完整示例

基本用法

function MyPlugin:handleBatchProcess(context)
    local files = context.selectedFiles
    local total = #files

    -- 显示可取消的进度对话框
    app.progress.show("批量处理", {
        message = "准备中...",
        indeterminate = false,
        cancellable = true
    })

    local processed = 0
    for i, file in ipairs(files) do
        -- 检查用户是否取消
        if app.progress.isCancelled() then
            break
        end

        -- 更新进度
        app.progress.update(i * 100 / total, "处理: " .. app.path.basename(file))

        -- 执行处理
        self:processFile(file)
        processed = processed + 1
    end

    app.progress.hide()
    app.notification.show("完成", "处理了 " .. processed .. " 个文件")
end

不确定进度模式

function MyPlugin:handleSearch(context)
    -- 不指定具体进度值，显示旋转指示器
    app.progress.show("搜索中", {
        message = "正在搜索文件...",
        indeterminate = true
    })

    -- 执行不确定时长的操作
    local results = self:searchFiles()

    app.progress.hide()
    app.notification.show("完成", "找到 " .. #results .. " 个文件")
end

多实例进度

function MyPlugin:handleParallelDownload(context)
    local urls = {"url1", "url2", "url3"}
    local progresses = {}

    -- 创建多个进度对话框
    for i, url in ipairs(urls) do
        progresses[i] = app.progress.create({
            title = "下载 " .. i,
            message = "准备中...",
            indeterminate = false
        })
    end

    -- 模拟并行下载（实际中需要使用 app.thread）
    for i = 1, 100 do
        for j, progress in ipairs(progresses) do
            progress:update(i, "下载中... " .. i .. "%")
        end
    end

    -- 关闭所有进度
    for _, progress in ipairs(progresses) do
        progress:close()
    end
end

带取消回调

注意：也可以用 app.progress.isCancelled() 轮询代替 onCancel 回调中设置标志变量的方式，参见”基本用法”示例。

function MyPlugin:handleCancellableTask(context)
    local cancelled = false

    app.progress.show("长时间操作", {
        message = "正在处理...",
        indeterminate = false,
        cancellable = true,
        onCancel = function()
            cancelled = true
            app.log.info("用户取消了操作")
        end
    })

    for i = 1, 100 do
        if cancelled then
            break
        end

        app.progress.update(i, "步骤 " .. i .. "/100")
        -- 模拟耗时操作
    end

    app.progress.hide()

    if cancelled then
        app.notification.show("已取消", "操作被用户取消")
    else
        app.notification.show("完成", "操作已完成")
    end
end