app.wakelock - 防休眠 API

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

权限：L1 标准 — 需在 permissions 中声明（"wakelock"）

方法

app.wakelock.preventSleep(opts?)

创建防休眠断言。

参数:

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

返回值: wakelockHandle - 防休眠句柄；失败时返回 nil, error

返回的是句柄表，不是字符串 ID。 拿它去拼字符串会报 attempt to concatenate a table value。它的方法：release()。

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

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

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

handle:release()

释放指定断言。

返回值: boolean, error

local ok, err = lock:release()

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 lock = app.wakelock.preventSleep({
        type = "idle",
        reason = "Processing files"
    })

    local p = app.progress.create({title = "处理中", message = "正在处理..."})

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

    p:close()

    -- 任务完成后释放
    if lock then
        lock:release()
    end

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