Alfred - Script Filter JSON 字段说明

Alfred 3 推荐 JSON 作为 Script Filter 返回的格式。这样以来,用 Alfred 写 Workflow 就更加方便,更加通用。所以翻译了一下官方文档

环境信息
Alfred 3.8.1


第一步…最后一步

差不多只需要一步,就能知道 Script Filter 是什么。Alfred -> Workflows -> + -> Getting Started -> Script Filter。创建以后,能看到 jsonformatxmlformat 模板。在 Alfred 中,输入 jsonformat,能看到效果:

双击 jsonformat,能看到这个 Script Filter 返回了一个 items 数组。数组有四个元素,就对应着 Alfred 显示的四个 item。所以规则也就显而易见了。

规则

Script Filter 要求返回 items 数组,每个 item 就是 Alfred 显示的行。

{"items": [
{
"uid": "desktop",
"type": "file",
"title": "Desktop",
"subtitle": "~/Desktop",
"arg": "~/Desktop",
"autocomplete": "Desktop",
"icon": {
"type": "fileicon",
"path": "~/Desktop"
}
}
]}

属性

上面看到的实例只是其中一部分属性,接下来一一说明下。

uid : String(可选)

每个 item 的唯一标识,后续 Alfred 能依托这个 uid,根据用户操作进行排序。如果想保持自己脚本返回的顺序,不用 Alfred 的排序,可以不设置这个字段。

"uid" : "xxx-xxx-xxx"

title

顾名思义,Row 的标题。

"title" : "Desktop"

subtitle(可选)

副标题

"subtitle" : "~/Desktop"

arg : String (可选)

非常建议 item 包含这个字段,它会作为 item 的输出,传递给下一个事件。如果不包含这个字段,就无法知道用户选的是哪个。

"arg": "~/Desktop"

icon

图标。Workflow 会在当前 workflow 的沙盒中运行,所以可以以相对路径形式引用 workflow 沙盒中的图标(Workflow 沙盒可以右键 Open In Finder)。

"icon": {
"type": "fileicon",
"path": "~/Desktop"
}

typepath 的关系如下:

  • 不指定 type,直接按 path 指定的绝对路径加载某张图片;
  • 指定为 fileicon,会按照 path 的类型显示图标。比如 path 是文件夹,则显示文件夹图标;Ruby 文件,则显示一个红宝石;Python 文件,则显示 🐍;
  • 指定为 filetype,貌似是显示指定的文件类型。比如 pathpublic.png,就会显示一个图片的图标,上面写的图片类型为 PNG(这个字段貌似只能是指定图片格式,其他文件格式的后缀都不支持)。

valid : true | false(可选,默认 true)

用于标识这个 item 是否有效。如果有效,则按照正常的逻辑走。如果无效,用户选中不会有任何响应。

match : String(可选)

从 Alfred 3.5 开始,如果 workflow 勾选了 “Alfred Filters Results” 选项,那么可以定义一些自定义的 match 规则。如果设置了 match 字段,那么根据 title 的匹配会失效。

"match": "my family photos"

autocomplete : String(可选)

自动补全。如果用户自动补全(默认是 tab 键),指定的字段会填充到 Alfred 输入框。如果 item 被标记为 "valid": false,在用户 Enter 以后才会补全。

"autocomplete": "Alfred Website"

type : “default” | “file” | “file:skipcheck”(可选,默认 “default”)

如果指定为 file,会将 item 当做文件来处理(选中 item 后,键盘 → 支持 Open With,Move To 等操作)。同时 Alfred 会校验指定路径是否存在,不存在的话,键盘 → 就没反应。如果不希望 Alfred 自动校验,可指定为 file:skipcheck

"type": "file"

mods : Map(可选)

这个字段能自定义修饰符,用户可以通过不同修饰符,传不同的 arg。Alfred 3.4.1 以后,还可以给每个 mod 自定义 icon 和 variables。

"mods": {
"alt": {
"valid": true,
"arg": "alfredapp.com/powerpack",
"subtitle": "https://www.alfredapp.com/powerpack/"
},
"cmd": {
"valid": true,
"arg": "alfredapp.com/powerpack/buy/",
"subtitle": "https://www.alfredapp.com/powerpack/buy/"
},
}

text : Map(可选)

这个字段能让用户键入 ⌘C 的时候,拷贝 copy 指定的值;⌘L 的时候,显示 largetype 指定的值。如果没有指定 text 字段,两个操作默认为 arg 的值。

"text": {
"copy": "https://www.alfredapp.com/ (text here to copy)",
"largetype": "https://www.alfredapp.com/ (text here for large type)"
}

quicklookurl : String(可选)

指定 Alfred Quick Look 的数据源(键入 shift 或 ⌘Y),同时 quicklookurl 也支持指定文件路径(HOME 的 ~ 相对路径也支持)。

"quicklookurl": "https://www.alfredapp.com/"

最后

如果看官方文档,或者通过模板创建 Workflow 的时候,可以发现 Script Filter 还有 Advanced 的版本。其中提到了 Variables、Session Variables、Re-run 等,后续有机会再学习。