# 打开应用

## 应用

```jsonc
{ "capabilities": { "open": ["viewer"] } }
```

```js
import { open } from 'acde:open'

const { window } = await open('viewer', { kind: 'show-image', image: '/photos/cat.png' })
```

第二个参数是一个**请求**: 带 `kind` 的可结构化克隆的对象, 交给对方. 不带请求的 `open('viewer')` 只是打开这个应用 (或把它的窗口提到最前). `open` 能力写 `true` 是任意应用, 写列表只能打开列出的.

被打开的一方在配置里写明接受哪些种类的请求, 用 `request` 事件接:

```jsonc
{ "id": "viewer", "requests": ["show-image"] }
```

```js
import { window as self } from 'acde:window'

self.on('request', (request) => {
  if (request.kind === 'show-image') showImage(request.image)
})
```

`requests` 列出应用自己的请求种类 (小写的词, 如 `show-image`). 运行时只检查 `kind`; 对象的其余部分由接收的应用检查. 没写 `requests` 的应用什么请求都不接受.

为某个请求新开的窗口, 请求只交给第一个 `request` 处理函数一次; 在处理函数注册之前到达的请求会留着, 注册时再交. 不是 `multiple` 而且已经在跑的应用, 在它现有的窗口里收到请求.

`open(app, request, { parent, modal })` 让新窗口成为你自己某个窗口的子窗口 (`parent` 是窗口 id, 比如 `self.id`), 居中盖在它上面; `modal: true` 时, 子窗口关闭之前父窗口收不到输入.

会出的错:

| 调用 | 拒绝 (`status`、`code`) |
| --- | --- |
| `open` 不允许 `mail` 时调 `open('mail')` | 403 `forbidden`: `Notes may not use open mail (not in its manifest's capabilities)` |
| 没有 `kind` 的请求 | 400 `untyped_request`: `a request to viewer needs a kind` |
| `kind` 不在目标应用的 `requests` 里 | 409 `not_accepted`: `viewer does not accept other-kind requests (its manifest's requests)` |

要列出装了哪些应用, 用 `acde:apps`; 它的 `open` 是同一个函数:

```js
import { apps } from 'acde:apps'

const installed = await apps.list() // [{ id, label, icon, script }]
```

## 文件和链接

应用在配置里声明能打开的文件类型和链接的 scheme:

```jsonc
{
  "id": "notes",
  "mimeTypes": ["text/markdown", "text/plain"],
  "schemes": ["mailto"]
}
```

用户在文件管理器里双击 `.md`, 或别的应用要求打开它, 系统按下面的顺序选应用:

1. 用户设过的默认应用 (XDG MIME Applications 规范, `mimeapps.list`; Windows 上按文件扩展名记);
2. `mimeTypes` 里写了这个类型的第一个应用 (完整类型优先于 `text/*`);
3. 原生程序 (Dopame OS / Linux), 或系统的默认程序 (macOS 和 Windows 上的宿主窗口).

被选中的应用收到一个**系统请求**. 文件是 `{ kind: 'open-file', handle }`, 其中 `handle` 是标准的 `FileSystemFileHandle` (或目录句柄); 链接是 `{ kind: 'open-link', url }`. 应用拿不到路径:

```js
self.on('request', async (request) => {
  if (request.kind === 'open-file') showText(await (await request.handle.getFile()).text())
  if (request.kind === 'open-link') compose(request.url)
})
```

申请了 `openFiles` 的应用可以自己把文件或链接交给它的默认应用. 不写应用 id, 由系统来选:

```js
import { open } from 'acde:open'

await open({ kind: 'open-file', handle }) // 来自选择器、拖放或请求的句柄
await open({ kind: 'open-link', url: 'mailto:someone@example.com' })
```

挑应用的顺序同上, 所以在 `mimeTypes` 里列了这种类型的应用会以请求的形式收回自己的文件 (除非用户设了别的默认应用); 没有办法改要系统的程序. 在 macOS 和 Windows 上, 系统的默认程序只接文档和媒体的普通文件: `pdf`, 图片 (`png`、`jpg`、`jpeg`、`gif`、`webp`、`bmp`、`tif`、`tiff`、`heic`、`heif`、`avif`、`ico`), 音频和视频 (`mp3`、`wav`、`ogg`、`oga`、`flac`、`m4a`、`aac`、`opus`、`wma`、`mp4`、`m4v`、`webm`、`mov`、`mkv`、`avi`、`wmv`), `txt`、`md`、`csv`、`log`、`json`, 以及办公文档 (`docx`、`xlsx`、`pptx`、`odt`、`ods`、`odp`). 文件夹、`.html` 页面或别的文件都被拒绝, promise 以这样的消息 reject: `no app can open this kind of file (text/html): /…/index.html is not handed to the system: only documents and media open in system apps, not .html files`. `http` 和 `https` 链接在默认浏览器里打开.

写了应用 id (`open('viewer', { kind: 'open-file', handle })`) 时, 请求交给那个应用; 这要的是 `open` 而不是 `openFiles`, 目标应用没在 `mimeTypes` 里声明这个文件的类型, 或没在 `schemes` 里声明这个链接的 scheme 时, 会被拒绝, 409 `not_accepted`. 只读的句柄 (来自拖放) 到了接收方还是只读的.

`acde:openPath` 和 `acde:handlers` (也要 `openFiles`) 用的是路径或 URI, 而不是句柄:

```js
import { openPath } from 'acde:openPath'
import { handlers } from 'acde:handlers'

await openPath('/home/me/Notes/todo.md')
const { mime, association, handlers: list } = await handlers('/home/me/Notes/todo.md')
```

它们适合桌面和系统应用, 因为这两者知道路径. 对普通应用, 文件必须在它的某个 `acde:fs` 根里, 否则调用被拒绝, 404 `outside_roots`; 手里有句柄的应用用 `open({ kind: 'open-file', handle })`.

改某个类型的默认应用用 `acde:setDefault` 的 `setDefault(association, app)`, 它是给桌面和系统应用的 shell 模块 (`association` 是 `handlers()` 返回的那个值).

文件类型按 shared-mime-info 判断, 所以 macOS 上的开发会话和 Dopame OS 得到一样的结果 (比如 `.md` 是 `text/markdown`). macOS 上需要 `brew install shared-mime-info`, 没有时会打一行警告. Windows 上的类型是系统给每个文件扩展名注册的类型, 系统不知道类型的名字, 类型是 `''`.
