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

系统能力

页面里只有标准的 Web 接口. 系统能力只有一个入口: acde: 内置模块, 写法和 node:fs 一样:

import { fs } from 'acde:fs'
import { window } from 'acde:window'
import fs2 from 'acde:fs' // 默认导出也是同一个对象

没有 acdev 全局变量, 运行时也不往 window 上挂任何非标准的东西.

访问别的主机不需要申请能力: fetch、WebSocket 等标准接口照常可用, 系统设了代理时经系统代理. 见 Web 兼容性.

应用能导入哪些模块, 由配置的 capabilities 决定:

{
"capabilities": {
"fs": true,
"openFiles": true,
"open": ["notes", "viewer"]
}
}
能力 给什么
fs acde:fs. true: 应用的私有文件夹和用户为它选的文件夹. { "roots": ["downloads", … ] } 再加上共享位置, 见 文件与文件夹
terminal acde:terminal: 伪终端
network acde:network: 网络设置, Wi-Fi (仅 Linux, 包括 Dopame OS)
system acde:system: 主机名、时区和时钟同步、存储、用户 (仅 Linux)
bluetooth acde:bluetooth: 适配器、配对和设备 (仅 Linux)
audio acde:audio: 声音设备、音量、音频流 (仅 Linux)
devices acde:devices: 驱动器 (挂载、弹出、自动挂载) 和打印机 (仅 Linux)
power acde:power: 电池、电源模式和设置、挂起、亮度 (仅 Linux)
input acde:input: 键盘布局、鼠标和触摸板、输入法 (仅 Linux)
display acde:display: 显示模式、缩放、旋转、亮度、夜间模式 (仅 Linux)
office acde:office: 办公文档服务 (仅 Linux)
open 用 acde:open 打开别的应用. true 是任意应用, 或应用 id 的列表
openFiles acde:openPath / acde:handlers, 以及不指定目标应用的 open(request): 文件或链接交给它的默认应用
launch acde:launch 的 start: 起原生程序
slots acde:launch 的 embed: 嵌在自己窗口里的原生程序 (仅 Dopame OS)
camera / microphone navigator.mediaDevices.getUserMedia() 的视频 / 音频 (Windows 上没有); 要问用户, 见下文
idleDetection IdleDetector (仅 Linux); 页面调用 IdleDetector.requestPermission() 时问用户

这些模块每个应用不用申请就能导入: acde:window (自己的窗口)、acde:capabilities (自己有哪些能力, 见下文)、acde:apps (list() 和 open())、acde:open (打开别的应用仍然要有 open).

表里没有的名字, acdev check 会报错:

  • 桌面服务写在 services 里, 不写在 capabilities 里: "services": ["clock"], 然后 import { clock } from 'acde:clock'. 这样应用只在跑着这个服务的桌面里启动. 见 服务.
  • shell 模块 (acde:windows、acde:packages、acde:session、acde:desktops、acde:inspect、acde:desktop、acde:setDefault、acde:permissions) 属于桌面. 只有桌面页面、它的服务和桌面自带的应用 (系统应用) 拿得到, 见 桌面.

导入应用无权使用的模块会失败, 抛出 AcdeError (name === 'AcdeError' 的 Error, 带 code: 'forbidden'、status: 403 和 module, 即去掉 acde: 的模块名), 消息里指出缺的是哪项声明; 提供模块的服务停了时, 以同样的方式失败, code 是 'service_not_running', status 是 503 (见 错误). acdev check 和 acdev build 在运行之前就对源码里的每个 import 报告同样的问题:

error: app "notes": capability "clock" is not a system capability; list desktop services under services
error: src/main.js:1: app "notes": acde:terminal needs "terminal" in the capabilities of Notes
error: src/main.js:2: app "notes": acde:windows is a shell module: only the desktop, its services and system apps may import it, and Notes is not a system app

调用应用无权使用的方法会被拒绝, status: 403 (code: 'forbidden'), 比如 open 里只列了别的应用时调 open('mail').

声明了能力, 应用就能用它: 不问用户, fs.roots 里的共享位置、terminal、network、launch 和 slots 也一样. 只有摄像头和麦克风要问用户, 还有空闲检测 (idleDetection, 在页面调用 IdleDetector.requestPermission() 时), 问法相同. 桌面自带的应用 (系统应用) 不用问.

  • 什么时候问: 页面第一次调 navigator.mediaDevices.getUserMedia() (或下文的 request()) 时; 这次调用等着用户回答. 应用必需的摄像头或麦克风也是这样.
  • 允许: 决定按应用存下来 ($XDG_CONFIG_HOME/acde/permissions.json), 不会再问用户.
  • 拒绝: getUserMedia() 以 NotAllowedError reject, 和浏览器里一样. 应用照常运行, 也留在应用列表里, 被拒绝的是它必需的那一样时也是如此.
  • 谁来问: 在桌面里, 由桌面显示提示 (见 桌面). 在只跑一个应用的宿主窗口里, Windows 用一个对话框问, macOS 的宿主窗口用一个 sheet 问 (Allow / Don't Allow), Linux 的宿主窗口用一条带 Allow 和 Deny 按钮的桌面通知问 (没有通知服务时什么都不显示).
  • 在 Dopame OS 会话里: 摄像头和麦克风还不能用, 声明了也一样: getUserMedia() 立刻以 NotAllowedError reject, 也不问用户.
  • 在开发会话里: 用 acdev allow 或 acdev deny 回答 (什么都没显示时、headless 时也一样), 用 acdev revoke 收回决定; 见 调试工具. 测试用 acde.allow() 回答 (见 端到端测试).

capabilities 里的每一项默认都是必需的: 平台没有其中一项, 应用就不启动. 应用没有也能跑的那些, 列在 optional 里:

{
"capabilities": { "terminal": true },
"optional": ["terminal"]
}
  • 在没有这个能力的平台上, 应用也能启动.
  • 可选的模块不能静态导入 (acdev check: acde:terminal is optional ("terminal" is in optional): import it dynamically, await import('acde:terminal'), which rejects where this platform lacks it). 动态导入它; 模块拿不到时 promise 会 reject.
  • camera 和 microphone 没有可加载的模块: 页面调 navigator.mediaDevices.getUserMedia(), 第一次调用时由它问用户. 见 Web 兼容性.
const terminal = await import('acde:terminal').then((m) => m.default, () => null) // 这个平台没有它时是 null

把 fs 设成可选, 它的共享位置也就成了可选的.

import { capabilities } from 'acde:capabilities'
capabilities.level // 1: 运行时的契约级别
capabilities.platform // 'linux' | 'darwin' | 'win32'
capabilities.mode // 'session' (Dopame OS) | 'desktop' (宿主窗口里的桌面) | 'standalone' (宿主窗口里的单个应用)
capabilities.get('terminal') // { name, kind: 'system' | 'service', state, reason, optional }
capabilities.list() // 同上, 每个系统能力和 shell 模块、notifications, 以及应用声明的每个 fs.<位置> 和服务各一项
await capabilities.request('camera') // 为摄像头或麦克风问用户; resolve 成状态
state 含义
available 声明了, 这个平台也有 (摄像头、麦克风: 用户也已经允许)
not-asked 摄像头或麦克风, 还没问过用户: request() 会问
asking 摄像头或麦克风的提示在等用户回答
not-declared 不在应用的 capabilities / services 里
unsupported 这个平台或这种运行方式没有它
service-not-running 桌面服务没在跑
shell-only 是 shell 模块, 而应用不是系统应用
denied 摄像头或麦克风: 用户拒绝了它, 或这个决定被收回了

对别的能力, 或用户已经回答过的能力调 request(), 马上 resolve 成当前的状态.

notifications 就是标准的 Notification 接口, 不用声明: 它是 available, 在这种运行方式不显示通知的地方 (Windows 上的单个应用) 是 unsupported.

所有模块的类型在 SDK @dopame/acde-api 里, 引用适合工程的那个入口, 编辑器就认识它能导入的 acde:* 模块:

/// <reference types="@dopame/acde-api/app" />
  • @dopame/acde-api/app: 应用的模块 (acde:fs、acde:window、acde:open ……).
  • @dopame/acde-api/shell: 上面这些再加 shell 模块, 给桌面和它自带的应用用.
  • @dopame/acde-api: 全部.

同一份代码要在普通浏览器里预览时:

  • 动态导入 acde: 模块, 导入 reject 时退回别的做法 (浏览器里没有 acde: 模块):
const fs = await import('acde:fs').then((m) => m.default, () => null)
模块 用途 文档
acde:window 自己的窗口: 标题、菜单、关闭、状态、快捷键、事件 窗口
acde:capabilities 应用有哪些能力、请求可选能力 上文
acde:fs 文件 文件与文件夹
acde:apps acde:open acde:openPath acde:handlers 别的应用、打开文件和链接 打开应用
acde:launch 原生程序 参考
acde:terminal 伪终端 参考
acde:network 网络 参考
acde:windows acde:packages acde:desktop acde:inspect acde:permissions acde:session acde:desktops acde:setDefault shell 模块: 桌面和系统应用 桌面

完整签名见 参考: acde: 模块.