app.dialog - 对话框 API

对话框和表单 API。

消息对话框

app.dialog.alert(config)

显示消息对话框。

参数:

config (table):
- title (string) - 标题
- message (string) - 消息内容
- detail (string, 可选) - 详情长文本，显示在可滚动的等宽字体文本框中（适合展示脚本输出、错误日志等）
- buttons (array, 可选) - 按钮数组（默认 [“确定”]）
- style (string, 可选) - 样式：”info”（默认）、”warning”、”critical”

返回值: number - 点击的按钮索引（从 1 开始）

-- 简单提示
app.dialog.alert({title = "提示", message = "操作完成"})

-- 带多个按钮
local result = app.dialog.alert({
    title = "确认",
    message = "确定要继续吗？",
    buttons = {"继续", "取消"},
    style = "warning"
})

if result == 1 then
    -- 点击了"继续"
end

-- 展示长文本详情（detail 在可滚动文本框中显示）
local result = app.shell.execute("git log --oneline -20")
app.dialog.alert({
    title = "Git 日志",
    message = "最近 20 条提交记录：",
    detail = result
})

表单对话框

app.dialog.form(config)

显示表单对话框，收集用户输入。

参数:

config (table):
- title (string) - 表单标题
- fields (array) - 字段配置数组
- width (number, 可选) - 宽度（默认 500）
- maxHeight (number, 可选) - 最大高度（默认 500）
- onLoad (function, 可选) - 表单加载后回调（非阻塞模式）
- onSubmit (function, 可选) - 提交回调（非阻塞模式）
- onCancel (function, 可选) - 取消回调（非阻塞模式）

返回值:

阻塞模式：table|nil - 字段值或 nil（取消）
非阻塞模式：formHandle - 表单句柄

阻塞模式（无回调时）:

local result = app.dialog.form({
    title = "设置",
    width = 400,
    fields = {
        {type = "text", id = "name", label = "名称", default = ""},
        {type = "number", id = "count", label = "数量", default = 10},
        {type = "select", id = "format", label = "格式",
         options = {"PNG", "JPEG", "WebP"}, default = "PNG"},
        {type = "checkbox", id = "optimize", label = "优化", default = true}
    }
})

if result then
    print(result.name)      -- string
    print(result.count)     -- number
    print(result.format)    -- string
    print(result.optimize)  -- boolean
end

非阻塞模式（带回调时）:

app.dialog.form({
    title = "选择证书",
    fields = {
        {type = "select", id = "cert", label = "证书",
         options = {}, loading = true}
    },
    onLoad = function(form)
        -- 异步加载数据
        app.thread.create(function()
            local certs = loadCertificates()
            form:setFieldOptions("cert", certs, certs[1])
            form:setFieldLoading("cert", false)
        end)
    end,
    onSubmit = function(values)
        print("选择: " .. values.cert)
    end,
    onCancel = function()
        print("已取消")
    end
})

表单句柄方法（非阻塞模式）:

方法	说明
`form:updateField(id, props)`	更新字段属性（通用方法，见下方说明）
`form:setFieldValue(id, value)`	设置字段值
`form:setFieldOptions(id, options, default?)`	设置下拉选项
`form:setFieldLoading(id, bool)`	显示/隐藏加载动画
`form:setFieldEnabled(id, bool)`	启用/禁用字段
`form:setFieldPlaceholder(id, text)`	设置占位符文本
`form:close()`	关闭表单

form:updateField(id, props) — 通用字段更新方法，可一次更新多个属性：

-- 一次更新多个属性
form:updateField("cert", {
    options = {"Cert A", "Cert B"},
    default = "Cert A",
    loading = false,
    enabled = true
})

-- 等价于分别调用：
-- form:setFieldOptions("cert", {"Cert A", "Cert B"}, "Cert A")
-- form:setFieldLoading("cert", false)
-- form:setFieldEnabled("cert", true)

支持的属性：value, options, default, loading, enabled, placeholder。

文件选择对话框

app.dialog.openFile(config?)

显示打开文件对话框。

参数:

config (table, 可选):
- title (string, 可选) - 对话框标题
- message (string, 可选) - 提示信息
- directory (string, 可选) - 初始目录
- allowedTypes (array, 可选) - 允许的文件扩展名
- allowsMultiple (boolean, 可选) - 允许多选（默认 false）

返回值: string|array|nil - 路径或 nil（取消）

local path = app.dialog.openFile({
    title = "选择图片",
    directory = "~/Pictures",
    allowedTypes = {"png", "jpg", "gif"},
    allowsMultiple = false
})

-- 多选
local paths = app.dialog.openFile({
    allowsMultiple = true
})

app.dialog.saveFile(config?)

显示保存文件对话框。

参数:

config (table, 可选):
- title (string, 可选) - 对话框标题
- message (string, 可选) - 提示信息
- directory (string, 可选) - 初始目录
- nameFieldLabel (string, 可选) - 文件名标签
- nameFieldValue (string, 可选) - 默认文件名
- allowedTypes (array, 可选) - 允许的文件扩展名

返回值: string|nil - 路径或 nil（取消）

local path = app.dialog.saveFile({
    title = "另存为",
    nameFieldValue = "output.png"
})

app.dialog.chooseFolder(config?)

显示文件夹选择对话框。

参数:

config (table, 可选):
- title (string, 可选) - 对话框标题
- message (string, 可选) - 提示信息
- directory (string, 可选) - 初始目录
- allowsMultiple (boolean, 可选) - 允许多选（默认 false）