桌面
Dopame OS 的桌面本身也是一个 acde 工程: 一张铺满屏幕、在所有窗口后面的网页. 桌面能导入这个平台上除 acde:window (它是给应用窗口用的) 以外的所有 acde: 模块, 包括应用拿不到的 shell 模块, 负责 Dock、菜单栏、窗口切换、通知、摄像头和麦克风的提示这些「系统界面」. Dopame 自带的桌面叫 dopame; 你可以做自己的.
acdev new my-desktop --template desktopcd my-desktopacdev dev配置
配置 一节的链接{ "$schema": "./acde.config.schema.json", "type": "desktop", "id": "my-desktop", "label": "My Desktop", "entry": "index.html", "services": { "clock": "services/clock.ts" }, "apps": [ { "id": "hello", "label": "Hello", "icon": "app", "entry": "apps/hello/index.html" } ]}桌面工程要让编辑器有类型, 引用 SDK 的 shell 入口: /// <reference types="@dopame/acde-api/shell" />.
应用
应用 一节的链接import { apps } from 'acde:apps'
for (const app of await apps.list()) { const button = document.createElement('button') button.textContent = app.label button.onclick = () => apps.open(app.id) dock.append(button)}
apps.on('changed', ({ apps }) => render(apps))app.icon 是图标名或图片 URL, 桌面自己决定怎么画. 在这里跑不了的应用不在列表里: 必需的能力这个平台没有的. 列表变了, changed 就带着新的列表触发.
应用启动不了时 apps.open(id) reject: 应用必需的东西这个平台没有时是 status: 404、code: 'unsupported_app' (Viewer needs "network" (not available on macOS host windows); list it in "optional" to run without it), 应用的服务没在跑时是 status: 503、code: 'service_not_running' (Viewer needs "clock" (service not running)). 用户拒绝了应用必需的摄像头或麦克风时, 应用照常启动. 桌面还能导入 acde:openPath、acde:handlers 和 acde:setDefault (见 打开应用). 安装包、列出原生程序在 acde:packages 里 (refresh、install、natives、runNative).
窗口
窗口 一节的链接import { windows } from 'acde:windows'
windows.on('open', (e) => addToTaskbar(e.window))windows.on('close', (e) => removeFromTaskbar(e.window))windows.on('state', (e) => markMinimized(e.window, e.state === 'minimized'))
await windows.focus(id)await windows.requestState(id, 'minimized')await windows.animate(id, { opacity: 0, scale: 0.9, duration: 180, easing: 'ease-out' })窗口事件: open close title state activate minsize parent menus crash hang responsive attention ready show animated. 别的名字会抛 TypeError. 每个事件是 {type: 'window<名字>', window, …}.
窗口的状态是 normal、minimized、filled 或 fullscreen. 状态的改变由运行时自己执行, 不管是应用请求的 (minimize()、requestState())、用户按了标题栏的按钮, 还是桌面调了 windows.requestState(id, state); 桌面从 state 事件 ({window, state, previous}) 得知每一次改变. windows.list() 给出每个窗口和它当前的 state. 对最小化的窗口调 windows.focus(id) 或 windows.show(id), 它会按之前的状态回来. 隐藏 (hide / show) 和状态是两回事, 只有桌面能做. 卡住的窗口 (hang) 可以 kill; close(id) 会先问应用 (它的 beforeclose).
面板
面板 一节的链接Dock、菜单栏、弹出层这类要浮在应用窗口上面的东西, 用 pin 把桌面页面里的一个元素变成单独的置顶窗口:
import { desktop } from 'acde:desktop'
const panel = desktop.pin(document.querySelector('#dock'), { margin: 8, reserve: { edge: 'bottom' } })// 元素变了系统会自动重新测量; 也可以手动:panel.update()panel.reserve({ edge: 'bottom', thickness: 64 }) // 或 null, 什么都不保留panel.unpin()元素还在同一个文档里, 状态、React 树、事件都照常. 元素要是一个 stacking context (比如有 position 加 z-index, 或 isolation: isolate); 它的 backdrop-filter 会变成真正的窗口间毛玻璃.
reserve 在屏幕的一条边 (top、bottom、left、right) 上保留一条, 不让铺满的窗口占: 工作区相应缩小, filled 的窗口跟着变, 应用在 acde:window 的 output 里看到新的 workArea. 不给 thickness 时, 这一条从屏幕的边一直到面板离这条边远的那一侧. 没有 reserve 的面板不占位置.
标题栏
标题栏 一节的链接每个应用窗口的标题栏由运行时画; 桌面决定它的样子和行为:
desktop.setDoubleClick('fill') // 双击标题栏: 'fill' | 'minimize' | 'none'desktop.setFrameTheme({ active: { background: '#202030', title: '#ffffff' }, inactive: { background: '#2a2a35', title: '#a0a0b0' }, buttonStyle: 'glyphs', // 或 'dots' buttonSide: 'right', // 或 'left' titleAlign: 'start', // 或 'center'})desktop.setFrameTheme(null) // 回到默认的样子颜色写 #rgb、#rgba、#rrggbb、#rrggbbaa、rgb() 或 rgba(); active 和 inactive 各自可以有 background、title、line 和 buttons. 再加上 light: { active, inactive }, 给页面没声明支持深色 (color-scheme 里没有 dark, 见 窗口) 的窗口用; 这时 active 和 inactive 给声明了支持深色的页面用. 每次调用给的都是整套主题. 值不对会抛 TypeError; 不认识的键被忽略, 日志里打一条警告.
通知、下载、快捷键
通知、下载、快捷键 一节的链接desktop.on('notification', (n) => toast(n.title, n.body, n.icon))desktop.on('download', (d) => showDownload(d.name, d.path))desktop.on('edge', ({ edge, entered }) => { if (edge === 'top') menuBar.hidden = !entered })
await windows.shortcut('ctrl+alt+t', 'desktop')desktop.on('shortcut', ({ key }) => { if (key === 'ctrl+alt+t') apps.open('term') })快捷键的作用域: session (最高, 不可覆盖) → 焦点窗口的应用级 → desktop. 冲突时以先注册的为准.
指针到达 (entered: true) 或离开屏幕的一条边 (top、right、bottom、left) 时触发 edge, 不抢焦点: 在全屏窗口上藏起菜单栏或 Dock 的桌面, 用它把它们再显示出来.
摄像头和麦克风提示
摄像头和麦克风提示 一节的链接摄像头和麦克风在应用第一次使用它们时问用户 (见 系统能力), 空闲检测 (idleDetection) 在页面调用 IdleDetector.requestPermission() 时问; 别的能力都不问. reason 总是 'request'. 桌面负责显示这些提示, 并用 acde:permissions 把回答传回去:
import { permissions } from 'acde:permissions'
const ask = async (prompt) => { // prompt: { id, app, label, capability: 'camera' | 'microphone', reason: 'request' } const allow = await showPrompt(`Allow ${prompt.label} to use ${prompt.capability}?`) await permissions.answer(prompt.id, allow)}
permissions.on('prompt', ask)for (const prompt of await permissions.pending()) ask(prompt) // 页面订阅之前就发出的提示permissions.list(app?) 返回存下来的决定 ({app, label, capability, decision: 'granted' | 'denied'}; 用户为应用选的文件夹列成 fs.folder-…, 带 folder: {label, exists}), permissions.revoke(app, capability) 收回一个决定, 本来就没有时 resolve 成 false. answered 事件 ({id, app, capability, allowed}) 报告每一次回答.
系统应用
系统应用 一节的链接桌面的 apps 里的应用和桌面在同一个包里, 所以是系统应用. 它们和别的应用有三点不同:
- 可以把 shell 模块声明成能力并导入:
"capabilities": { "windows": true, "permissions": true }. 不在桌面包里的应用声明了 shell 模块, 过不了acdev check(acde:windows is a shell module: only apps of a desktop package (system apps) may declare it). - 它们的摄像头和麦克风不用问用户.
fs.roots里写了共享位置时, 它们的acde:fs根带着文件夹的path,fs.locate()/fs.openPath()也能用.
系统应用只能导入它声明了的模块: 没写 "session": true 就 import 'acde:session' 会失败, 报 acde:session is a shell module: declare "session" in the capabilities of <label>.
其它模块
其它模块 一节的链接acde:session:logout()、reboot()、poweroff()、setLanguage(tag). 只有桌面页面和声明了"session": true的系统应用能用它; 普通应用不能.acde:desktops:list()、choose(id, remember?)切换桌面.acde:launch:start(argv)起一个原生程序,embed(argv)把一个原生程序嵌进窗口 (仅 Dopame OS).acde:inspect: 把屏幕变成文字的语义树, 并按 ref 操作 (给 AI agent 用), 见 参考.
在桌面里开发
在桌面里开发 一节的链接开发一个应用时, 也可以让它跑在某个桌面里:
acdev dev ./my-app --desktop ./my-desktopacdev dev ./my-app --desktop dopame见 acdev dev.