系统能力
页面里只有标准的 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 serviceserror: src/main.js:1: app "notes": acde:terminal needs "terminal" in the capabilities of Noteserror: 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()以NotAllowedErrorreject, 和浏览器里一样. 应用照常运行, 也留在应用列表里, 被拒绝的是它必需的那一样时也是如此. - 谁来问: 在桌面里, 由桌面显示提示 (见 桌面). 在只跑一个应用的宿主窗口里, Windows 用一个对话框问, macOS 的宿主窗口用一个 sheet 问 (
Allow/Don't Allow), Linux 的宿主窗口用一条带 Allow 和 Deny 按钮的桌面通知问 (没有通知服务时什么都不显示). - 在 Dopame OS 会话里: 摄像头和麦克风还不能用, 声明了也一样:
getUserMedia()立刻以NotAllowedErrorreject, 也不问用户. - 在开发会话里: 用
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 设成可选, 它的共享位置也就成了可选的.
acde:capabilities
acde:capabilities 一节的链接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: 模块.