入门 iOS 自动化：读懂 URL Schemes

之前我写过一篇《URL Schemes 使用详解》，其中把 URL Schemes 从功能上分为了 4 种：

1. 基础 URL Schemes：用于启动应用，比如：drafts4://；
2. 复杂 URL Schemes：用于直接打开应用的具体功能，比如：drafts4://dictate；
3. 变形 URL Schemes：用于输入内容，含有第三方应用的特殊语法，比如：在 Launch Center Pro 里用这一条 drafts4://create?text=[prompt]；
4. x-callback-URL：前面的 URL Schemes 只能执行一个动作，而 x-callback-URL 可以根据根据前一段 URL Schemes 的执行情况决定进一步的行动。

作为补充，在这篇文章，我来介绍一下 URL Schemes 正式的读法。包括每个部分是什么、符号都是什么意思，以及阅读文档时该从哪些地方入手，注意哪些细节。

概览

一个 URL Schemes 分为 Scheme、Action、Parameter、Value 这 4 个部分，中间用冒号 :、斜线 /、问号 ?、等号 =相连接。

拿 things:///add?title=正文内容&note=备注来说：

1. Scheme（链接头）是 things；
2. Action（动作）是 add；
3. Parameter（参数）是 title和 note；
4. Value（值）是 正文内容和 备注。

另外在不同的部分之间有符号相连，它们也有一定的规则：

• 冒号:：在链接头和命令之间；

• 双斜杠 //：在链接头和命令之间，有时会是三斜杠 ///；
• 问号 ?：在命令和参数之间；
• 等号 =：在参数和值之间；
• 「和」符号 &：在一组参数和另一组参数之间。

接下来就来详细地讲一下这些部分，以及链接它们的符号。

Scheme（链接头）

这个东西在 URL 里本来用来表示协议，比如 http、https、ftp 等。但是，在 iOS 的这些 URL 里它们就不是协议了，而是启动一个应用的 URL。

除此之外，通过 URL 执行的复杂命令都得以这一段 Scheme 为起始，鉴于没有官方的翻译，我暂且在此称其为「链接头」。

如果我们只是需要一个启动应用的 URL，那么「链接头+冒号」的部分就足够满足需求。比如 things:、omnifocus:、spotify:都可以直接跳转到相应应用。

文档阅读注意点：斜线数量

我们会发现一般的链接头后面都会加冒号和双斜线 ://——比如 weixin://——以至于我们会把链接头和这个双斜线看为一个整体。

然而这个双斜线其实是有特殊作用的。根据我的理解，在 iOS 上的 URL Schemes 中，跟在链接头后的双斜线 //用于声明一个领域。这一点在支持 URL Schemes 的社交应用、支持 x-callback-URL 的应用都有一定的体现，还有一些特例。

在社交工具里的使用

最典型的用例是 Tweetbot 这样的社交应用，在它的 URL Schemes 文档里，每一个 URL 的双斜线后面都有 <screenname>这个部分。它的作用是，当你在 Tweetbot 登录了多个 Twitter 账户，可以用 <screenname>，来指定执行操作的是哪个账户。

一个使用情境：

1. 在 Tweetbot 里，我登录了 @JailbreakHum 和 @CheckedFM 这两个账户；
2. 我一般只看 @JailbreakHum 这个账户的时间线；
3. 所以我 Tweetbot 的首页是 @JailbreakHum 的时间线；
4. 这时我想直接使用 @CheckedFM 这个账户发推文；
5. 我可以用 tweetbot://checkedfm/post这段 URL 直接把账户切换到 @CheckedFM，并弹出编写推文的界面。

在 Tweetbot 中，这个 <screenname> 的部分可以不填。如果不填，也就是留白的话，链接会变成 tweetbot:///post，链接里是 3 条斜线，功能会变成是使用当前正在使用的账户发推。也就是说，它会使用 @JailbreakHum 这个账户发推，而不会切换到 @CheckedFM 发推。

这个逻辑同样适用于微博第三方客户端墨客。

在 x-callback-URL 中的使用

在这里我打算用 Drafts 来举例，如果我们想通过 URL Schemes 在 Drafts 里添加一个草稿，有 3 个可以用的 URL：

1. 双斜线 //，比如 drafts4://create?text=A，
2. 三斜线 ///，比如 drafts4:///create?text=A
3. 双斜线 + 内容 + 斜线 //[Something]/，drafts4://x-callback-url/create?text=A

这三种用法，都可以让 Drafts 生成一个新的草稿，内容为 A。那么它们的区别是什么？

在这个例子里，最完整、也最不容易产生理解问题的用法是最后这个：drafts4://x-callback-url/create?text=A。

而第二个用法 drafts4:///create?text=A，是省略掉了 x-callback-url 。在用不到 x-callback-URL 的情况下，把链接中的 x-callback-URL省掉是比较通常的做法，Things 的用法也是一样。

最后，是双斜线的情况，drafts4://create?text=A。

这种用法其实应该是不太规范的。如果一个应用支持 x-callback-URL，并且用 drafts4://x-callback-url/的形式来使用 x-callback-URL，那它要么要带上这个 x-callback-URL ，要么它把它省去，变成三斜线 drafts4:///。比如 Things 的 URL Schemes，要么带上这个 x-callback-URL，要么三斜线，如果用双斜线会被提示错误：

但是 URL Schemes 的写法似乎并没有一个特别严格的标准，所以只要在功能上可用，我们也不用纠结对错。只是如果出现问题，可以在这里找一下原因。

其它的情况

除了社交应用和支持 x-callback-URL 的应用这两种比较典型的情况外，还有一些其它零散的找不到规律的情况，也会在三斜线之间加入内容。之前的微信和现在的支付宝就属于这种情况。

现在微信的 URL Schemes 已经几乎全部失效了，但是过去它的 URL Schemes 中总会带一个 dl，也就是 weixin://dl/moments（打开朋友圈）这样的。

支付宝的 URL Schemes 也有 platformapi这个部分，比如付款码是：alipayqr://platformapi/startapp?saId=20000056。

最后，除了上述这三种情况，有相当一部分支持 URL Schemes 的应用不需要三斜线，只用双斜线就可以正常工作。

Action（动作）

链接头和斜线之后，跟的是动作（Action）。动作在一些文档里¹ 也被称为「Command（命令）」。

一段 URL 里加上这个部分就说明它有具体的功能了，比如：drafts4:///create?text=A里的「create」，它代表的动作就是「创建」，所以在 Drafts 中相应的动作就是新建笔记。

文档阅读注意点

一般的 URL Schemes 文档都是由动作来组织的，所以阅读文档时，可以先找自己需要的动作，再进行研究。比如 Bear 的文档里就以 /动作名的形式给出了 12 个动作：

• /open-note是打开笔记
• /create是创建笔记
• /open-tag是打开标签
• 剩下 9 个就不一一列举了

在动作之后可以接参数（Parameter）也可以不接，比如 OmniFocus 打开 Inbox 的 URL Schemes 是 omnifocus:///inbox，就没有接参数。如果要接参数的话，动作和参数之间，按规定由问号 ?连接。这个地方，更确切地说，应该是「参数以问号 ?为起始」，所以不接参数就不用带这个问号。

Parameter（参数）和 Value（值）

在动作之后，是 Parameter（参数）和 Value（值），参数是该程序的程序员决定的，值是用户根据自己需求填入的。参数和值的中间用等号 =连接，因为 =在编程中多是赋值的意思。比如我们写 A = 3，就是让 A 等于 3的意思，这就是赋值。

拿 drafts4:///create?text=A来说，参数是「text」，值是「A」。「text」这个参数是开发者决定的，我们不能改，改了就无效了。而「A」这个值是我们用户决定的，可以写成任何我们需要的内容。

如果有两组参数，比如我们在 Things 中添加任务要添加任务名和备注，就要用「和」符号 &来连接它们：things:///add?title=任务名&notes=备注。

Parameter（参数）文档阅读注意点

前面说过，文档一般是由动作组织的，也就是一篇文档的文章中，大标题一般都是动作。而接下来的中标题，一般都是参数，还拿 Bear 的文档举例子，在 「/create」下面，有「parameter」的字样，下面有 10 个参数：

• title，笔记标题
• text，笔记内容
• tags，标签
• ……

我们还会发现，在每个具体的参数后面，会有「optional（可选的）」和「required（必要的）」的字样。它们指示了执行这个动作，某个参数是不是必要的。

来看 omnifocus:///add?name=买牛奶，这里的「add」是动作名，后面跟了问号 ?，再后面的「name」是参数名，后面跟了等号 =，最后的「买牛奶」是值。通过它我们可以建立一个任务名为「买牛奶」任务。

而这其中的参数「name」是 optional（可选的），也就是说我不用加参数，只用 omnifocus:///add也可以工作。点前面的连接，如果你有 OmniFocus 的话，就会发现打开了 OmniFocus 添加任务的界面，但是接下来需要自己填写内容。

小结

以上总结的是比较常见的 URL Schemes 使用方法，但是实际上 iOS 上的 URL Schemes 并没有特别严格的规范。写这篇文章时，我发现哪怕是知名应用的开发者在制作 URL Schemes 时，也会出现不大规范的地方，比如：

最开始提到的 Drafts 的三种斜线的情况，理论上 drafts://create这种 URL 应该是不规范的，它自己文档里都写了：「All URLs should begin with the base URL "drafts4://x-callback-url/[action]” where action is one of the actions listed below.」

OmniFocus 显示今天的任务时，可以直接用 omnifocus:///today，这种行为是把「today」当成了一个动作，理解可以理解，但不是特别舒服。而更规范的用法应该是 Things 的 things:///show?id=today，动作是「show」，即显示，显示什么呢？显示「today」里的内容。

Bear 在文档中，「/create」下的所有参数都是 optional，也就是说，哪怕我只填写「create」这个命令，也是应该有效的，因为所有参数都是选填嘛。但是实际上，bear://x-callback-url/create这段 URL 是没效果的，不会触发「create」这个动作。更好的做法应该是 OmniFocus 那样，omnifocus:///add也能触发添加任务的动作。

Spotify 的 URL Schemes 更是完全没有按照传统的规范来写，但是也可以正常使用，查看文档。

iOS 开发者 @陈某豪 在 Power+ 本文下的评论中表示，其实只有链接头（配置文件中叫「HOST」）这个部分是苹果强制要求的，而其他部分则根据开发者的理解发挥，因此出现这种乱象。

不过，如果开发者能按照一定的规范，特别是知名应用们已经建立起的更 iOS 的思路去写 URL，会更有助于用户理解你的 URL 和文档。

另外，这篇文章没有涉及到 x-callback-URL 的细节。x-callback-URL 的文档毫无疑问也有一些特殊的地方，那是另一个主题，有机会我会再写一篇文章去说明。