跳转到内容
选择主题
选择语言简体中文

打开应用

{ "capabilities": { "open": ["viewer"] } }
import { open } from 'acde:open'
const { window } = await open('viewer', { kind: 'show-image', image: '/photos/cat.png' })

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

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

{ "id": "viewer", "requests": ["show-image"] }
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 是同一个函数:

import { apps } from 'acde:apps'
const installed = await apps.list() // [{ id, label, icon, script }]

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

{
"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 }. 应用拿不到路径:

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, 由系统来选:

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, 而不是句柄:

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 上的类型是系统给每个文件扩展名注册的类型, 系统不知道类型的名字, 类型是 ''.