# 桌面

Dopame OS 的桌面本身也是一个 acde 工程: 一张铺满屏幕、在所有窗口后面的网页. 桌面能导入这个平台上除 `acde:window` (它是给应用窗口用的) 以外的所有 `acde:` 模块, 包括应用拿不到的 shell 模块, 负责 Dock、菜单栏、窗口切换、通知、摄像头和麦克风的提示这些「系统界面」. Dopame 自带的桌面叫 `dopame`; 你可以做自己的.

```sh
acdev new my-desktop --template desktop
cd my-desktop
acdev dev
```

## 配置

```jsonc
{
  "$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" }
  ]
}
```

- `services`: 跑在后台的[服务](https://docs.dopame.ai/zh/guide/services.md), 名字 → 模块.
- `apps`: 这个桌面自带的应用, 字段和应用工程一样 (`id`、`entry` 必填). 它们是[系统应用](#系统应用).

桌面工程要让编辑器有类型, 引用 SDK 的 shell 入口: `/// <reference types="@dopame/acde-api/shell" />`.

## 应用

```js
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` (见 [打开应用](https://docs.dopame.ai/zh/guide/open.md#文件和链接)). 安装包、列出原生程序在 `acde:packages` 里 (`refresh`、`install`、`natives`、`runNative`).

## 窗口

```js
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` 把桌面页面里的一个元素变成单独的置顶窗口:

```js
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` 的面板不占位置.

## 标题栏

每个应用窗口的标题栏由运行时画; 桌面决定它的样子和行为:

```js
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`, 见 [窗口](https://docs.dopame.ai/zh/guide/window.md#尺寸和标题栏)) 的窗口用; 这时 `active` 和 `inactive` 给声明了支持深色的页面用. 每次调用给的都是整套主题. 值不对会抛 `TypeError`; 不认识的键被忽略, 日志里打一条警告.

## 通知、下载、快捷键

```js
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 的桌面, 用它把它们再显示出来.

## 摄像头和麦克风提示

摄像头和麦克风在应用第一次使用它们时问用户 (见 [系统能力](https://docs.dopame.ai/zh/guide/capabilities.md#摄像头和麦克风)), 空闲检测 (`idleDetection`) 在页面调用 `IdleDetector.requestPermission()` 时问; 别的能力都不问. `reason` 总是 `'request'`. 桌面负责显示这些提示, 并用 `acde:permissions` 把回答传回去:

```js
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 用), 见 [参考](https://docs.dopame.ai/zh/reference/modules.md#acdeinspect).

## 在桌面里开发

开发一个应用时, 也可以让它跑在某个桌面里:

```sh
acdev dev ./my-app --desktop ./my-desktop
acdev dev ./my-app --desktop dopame
```

见 [acdev dev](https://docs.dopame.ai/zh/guide/dev.md).
