Alfred - Script Filter JSON 字段说明

# TODO:

2019-05-04

alfred, others

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

环境信息
Alfred 3.8.1

第一步…最后一步

差不多只需要一步，就能知道 Script Filter 是什么。Alfred -> Workflows -> + -> Getting Started -> Script Filter。创建以后，能看到 jsonformat 和 xmlformat 模板。在 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"
}

type 和 path 的关系如下：

不指定 type，直接按 path 指定的绝对路径加载某张图片；
指定为 fileicon，会按照 path 的类型显示图标。比如 path 是文件夹，则显示文件夹图标；Ruby 文件，则显示一个红宝石；Python 文件，则显示 🐍；
指定为 filetype，貌似是显示指定的文件类型。比如 path 为 public.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 等，后续有机会再学习。