app.wakelock - 防休眠 API

阻止系统休眠，使用 IOKit 电源断言。

方法

app.wakelock.preventSleep(opts?)

创建防休眠断言。

参数:

• opts (table, 可选):
  • type (string) - 断言类型:
    • "idle" (默认) - 阻止空闲休眠
    • "display" - 阻止显示器休眠
    • "system" - 阻止系统休眠
  • reason (string) - 原因说明（默认 “Plugin requested sleep prevention”）
  • duration (number) - 持续时间（秒），到期自动释放

返回值: string, error - 断言 ID

-- 阻止空闲休眠（无时间限制）
local id, err = app.wakelock.preventSleep()

-- 阻止显示器休眠 30 分钟
local id = app.wakelock.preventSleep({
    type = "display",
    reason = "长时间任务进行中",
    duration = 1800
})

-- 阻止系统休眠 1 小时
local id = app.wakelock.preventSleep({
    type = "system",
    duration = 3600
})

app.wakelock.release(id)

释放指定断言。

参数:

• id (string) - 断言 ID

返回值: boolean, error

local ok, err = app.wakelock.release(id)

app.wakelock.releaseAll()

释放当前插件的所有断言。

返回值: boolean

app.wakelock.releaseAll()

app.wakelock.list()

列出当前插件的活跃断言。

返回值: array<table> - 每项包含:

• id (string) - 断言 ID
• type (string) - 类型
• reason (string) - 原因
• createdAt (string) - 创建时间（ISO 8601）

local assertions = app.wakelock.list()
for _, a in ipairs(assertions) do
    app.log.info(a.id .. ": " .. a.type .. " - " .. a.reason)
end

说明

• 断言在插件卸载时自动释放
• 指定 duration 后会自动释放，无需手动调用 release()
• "idle" 类型最常用：防止用户无操作时系统自动休眠
• "display" 类型同时阻止显示器关闭

示例

长时间任务防休眠

function MyPlugin:handleLongTask(context)
    -- 开始任务前阻止休眠
    local cafId = app.wakelock.preventSleep({
        type = "idle",
        reason = "Processing files"
    })

    app.progress.show("处理中", {message = "正在处理..."})

    -- 执行长时间任务
    for i, file in ipairs(context.selectedFiles) do
        app.progress.update(i / #context.selectedFiles * 100)
        -- ... 处理文件 ...
    end

    app.progress.hide()

    -- 任务完成后释放
    if cafId then
        app.wakelock.release(cafId)
    end

    app.notification.show("完成", "处理了 " .. #context.selectedFiles .. " 个文件")
end