app.chooser - 快速选择器 API

提供类似 Raycast/Alfred 的快速选择界面，支持搜索过滤。

权限: 需在 manifest 中声明 chooser（L1 standard）

方法

app.chooser.show(items, opts?)

显示快速选择器窗口。

参数:

• items (array) - 选项列表，每项为 table:
  • text (string) - 主文本（必填）
  • subText (string, 可选) - 副文本/描述
  • icon (string, 可选) - 图标（支持 sf:symbol.name 格式使用 SF Symbols）
  • id (string|number, 可选) - 唯一标识
• opts (table, 可选):
  • title (string, 可选) - 窗口标题
  • placeholder (string, 可选) - 搜索框占位符
  • multiSelect (boolean, 可选) - 是否多选（默认 false）
  • width (number, 可选) - 窗口宽度（默认 500）
  • maxVisibleItems (number, 可选) - 最大可见项数（默认 10）

返回值:

• 单选：选中的 item table 或 nil（取消）
• 多选：选中的 item 数组或 nil（取消）

-- 基本使用
local selected = app.chooser.show({
    {text = "新建文件",     subText = "创建空白文件",   icon = "sf:doc.badge.plus"},
    {text = "新建文件夹",   subText = "创建空文件夹",   icon = "sf:folder.badge.plus"},
    {text = "从模板创建",   subText = "使用预定义模板", icon = "sf:doc.on.doc"},
}, {
    title = "快速操作",
    placeholder = "搜索操作..."
})

if selected then
    app.log.info("选择了: " .. selected.text)
end

与 dialog.choose 的区别

示例

快速打开项目

function MyPlugin:handleQuickOpen(context)
    -- 构建项目列表
    local items = {}
    local projects = app.file.find("~/Projects", {type = "directory", maxDepth = 1})

    for _, path in ipairs(projects) do
        table.insert(items, {
            id = path,
            text = app.path.basename(path),
            subText = path,
            icon = "sf:folder.fill"
        })
    end

    local selected = app.chooser.show(items, {
        title = "打开项目",
        placeholder = "搜索项目..."
    })

    if selected then
        app.shell.execute("open " .. app.shell.quote(selected.id))
    end
end

命令面板

function MyPlugin:handleCommandPalette(context)
    local commands = {
        {id = "copy_path",   text = "复制路径",     subText = "复制文件完整路径", icon = "sf:doc.on.clipboard"},
        {id = "copy_name",   text = "复制文件名",   subText = "复制文件名称",     icon = "sf:textformat"},
        {id = "open_term",   text = "在终端打开",   subText = "打开 Terminal",    icon = "sf:terminal"},
        {id = "compress",    text = "压缩文件",     subText = "创建 ZIP 压缩包",  icon = "sf:archivebox"},
        {id = "hash",        text = "计算哈希",     subText = "SHA256 校验",      icon = "sf:number"},
    }

    local selected = app.chooser.show(commands, {
        placeholder = "输入命令..."
    })

    if selected then
        self:executeCommand(selected.id, context)
    end
end

多选操作

function MyPlugin:handleSelectTags(context)
    local tags = {
        {id = "important", text = "重要",   icon = "sf:star.fill"},
        {id = "urgent",    text = "紧急",   icon = "sf:exclamationmark.triangle"},
        {id = "review",    text = "待审核", icon = "sf:eye"},
        {id = "archive",   text = "归档",   icon = "sf:archivebox"},
    }

    local selected = app.chooser.show(tags, {
        title = "选择标签",
        placeholder = "搜索标签...",
        multiSelect = true
    })

    if selected then
        for _, tag in ipairs(selected) do
            app.log.info("选中标签: " .. tag.text)
        end
    end
end

注意事项

1. 搜索过滤：自动匹配 text 和 subText 字段
2. 阻塞调用：调用后等待用户选择或取消，阻塞当前线程
3. 图标格式：使用 sf: 前缀加载 SF Symbols（如 sf:folder.fill）