窗口
每个应用窗口是一张独立的网页, 有自己的 DOM 和 JS 堆; 一个窗口崩溃不影响别的. 同一个应用的所有窗口共享 localStorage、IndexedDB、cookie 等存储.
尺寸和标题栏
尺寸和标题栏 一节的链接- 在桌面里, 新窗口的内容区是配置的
size(默认 800 × 600), 居中打开; 下次打开时摆回上次关闭的位置. - 只跑一个应用的
acdev dev会话里 (应用工程, 没带--desktop), 应用铺满宿主窗口,size决定宿主窗口打开时有多大: 配置是"size": [400, 300]时, 宿主窗口的内容区是 400 × 300. 标题栏画在内容区里面, 所以页面是 400 × 268. 没写size时, 宿主窗口占屏幕的大部分 (宽的 90%、高的 85%, 最大 1440 × 900). acdev dev --headless没有宿主窗口,size不起作用: 屏幕是 1440 × 900 (acdev test里是 1280 × 800), 应用铺满它, 所以页面是 1440 × 868. 想看应用在按它自己的size开的窗口里的样子, 让它跑在桌面里:acdev dev --desktop ./my-desktop, 或装了那个桌面之后用--desktop dopame(见 acdev dev).- 系统画的标题栏不在页面的文档里:
innerHeight、100vh、resize事件都只算内容区. 不要标题栏时配置"frame": false, 自己画, 再用setGrabHint告诉系统哪里能拖. - 标题取
document.title或window.setTitle(), 以后设的那个为准 (页面里的<title>会替换文档载入之前设的标题); 都没有时用label. - 像在浏览器里一样, 声明页面支持的配色方案: 页面跟着系统走 (用
prefers-color-scheme) 时, 在根上写color-scheme: light dark(:root { color-scheme: light dark }) 或写<meta name="color-scheme" content="light dark">; 总是深色时写dark. 只有写了dark的页面, 系统才画深色的标题栏; 什么都没声明的页面被当作只支持浅色, 在深色主题里也是浅色的标题栏.html模板跟着系统走, 声明的是light dark. 单独跑的应用 (应用自己的acdev dev、acdev test) 在页面是深色时标题栏就是深色: 只写了dark的页面总是深色, 写了light dark的页面在prefers-color-scheme是dark时 (系统的配色, 或测试里的emulate({ colorScheme })) 是深色. 和浏览器一样, 根元素的color-scheme先于 meta: 应用自己有深浅切换时, 在根上写color-scheme: dark或light, 标题栏跟着它.
acde:window
acde:window 一节的链接import { window as self } from 'acde:window'
self.setTitle('未命名 — 笔记')
self.on('beforeclose', async () => { if (!dirty) return true return confirmDiscard() // 返回 false 留住窗口})模块名
window和全局的window同名, 导入时改个名字更清楚.
| 成员 | 作用 |
|---|---|
id |
这个窗口的 id (一个数字) |
setTitle(title) |
标题 |
setMenus(menus) |
应用菜单 (桌面的菜单栏显示它) |
close() |
立刻关闭窗口; 不问 beforeclose |
minimize() |
最小化窗口, 和 requestState('minimized') 一样; 窗口不能最小化时 promise reject, status: 409、code: 'unavailable' |
state / requestState(state) |
窗口的状态: normal、minimized、filled (铺满工作区)、fullscreen, 见 窗口状态 |
requestMode(mode) |
用户能不能移动窗口和改它的大小: free (都能)、fixed (只能移动)、pinned (都不能) |
output |
窗口所在的屏幕: {width, height, scale, workArea: {x, y, width, height}}, 逻辑像素; workArea 不含桌面的面板保留的部分. 在只跑一个应用的会话里, 屏幕就是宿主窗口: "size": [400, 300] 时, output 和它的 workArea 都是 400 × 300 |
requestAttention() |
请求注意 (比如 Dock 图标跳动, 由桌面决定) |
requestActivate() |
提到最前并请求焦点; 系统可能把它变成一次请求注意 |
setGrabHint(rect, edges?) |
按在这块区域时系统开始移动窗口 (不给 edges) 或改大小 (给边) |
setBackdrop(rect, effect?) |
这块区域下面的内容做毛玻璃: {radius, blur, saturate, brightness}; null 取消 |
requestGrab(kind) / releaseGrab(kind) |
独占指针或键盘 ('pointer' / 'keyboard') |
shortcut(combo) / unshortcut(combo) |
注册应用级全局快捷键, 如 'ctrl+shift+k' |
hostControls |
宿主系统画了窗口的最小化 / 最大化 / 关闭按钮时是 true, 这时没有标题栏的应用该藏起自己画的按钮 |
minimizable |
这个窗口不能最小化时是 false. 只跑一个应用的会话, 在 macOS 上和 headless 时, 应用的窗口就是这样的窗口: 它铺满宿主窗口 |
窗口状态
窗口状态 一节的链接全屏是窗口的一种状态, 不是模式: requestMode('fullscreen') 会抛 TypeError (requestMode: full screen is a window state, use requestState('fullscreen')).
self.on('state', ({ state, previous }) => { document.body.dataset.windowState = state})
self.requestState('fullscreen') // 'normal' | 'minimized' | 'filled' | 'fullscreen'requestState()没有返回值. 由系统决定: 它不答应时什么都不变, 也没有事件.fixed的窗口只能最小化,pinned的窗口不能改状态.minimizable是false的窗口不能最小化:requestState('minimized')什么都不变,minimize()则 reject.- 页面没请求时状态也会变: 标题栏的按钮、桌面把窗口最小化、用户把最小化的窗口拿回来. 界面要跟着
state事件 (或self.state) 走, 不要跟着页面上一次请求的状态走. - 最小化的窗口重新得到焦点时, 回到它之前的状态 (比如
fullscreen). - 只跑一个应用的
acdev dev会话里, 应用本来就铺满宿主窗口, 请求状态可能什么都不变 (macOS 上的 headless 会话里,minimized、filled和fullscreen都让状态留在normal, 也没有事件). 要试各种状态, 用跑着桌面的会话. - 不支持标准的 Fullscreen API (
element.requestFullscreen()); 它 rejectNotSupportedError.
事件
事件 一节的链接on(name, handler) 订阅, 返回退订函数. 模块没有的名字会抛 TypeError (acde:window has no nosuch event (activate, deactivate, beforeclose, request, suspend, resume, grab, grablost, state, output, hostcontrols, minimizable, shortcut)). 事件不派发到全局 window 上.
| 事件 | 什么时候 |
|---|---|
activate / deactivate |
窗口得到 / 失去焦点 |
state |
窗口的状态变了, {state, previous} |
output |
屏幕或它的工作区变了; 处理函数收到新的 output |
beforeclose |
用户或桌面要关窗口. 返回 false (或 resolve 成 false) 留住它; 3 秒不答就关 |
request |
别的应用或系统要这个窗口打开东西 (见 打开应用) |
shortcut |
注册的快捷键被按下, {key} |
grab / grablost |
独占的请求有了答复, {kind, granted} / 独占被收回, {kind: 'lost', reason} |
hostcontrols / minimizable |
hostControls / minimizable 变了; 处理函数收到新的值 |
菜单
菜单 一节的链接self.setMenus([ { id: 'file', label: '文件', items: [ { id: 'new', label: '新建', shortcut: 'ctrl+n', onSelect: () => newDoc() }, { type: 'separator' }, { id: 'close', label: '关闭', onSelect: () => self.close() }, ], },])要改什么 (一个 checked 勾、一项 disabled) 就带着整份列表再调一次 setMenus. 菜单显示在哪里:
- 在桌面里, 显示在它的菜单栏 (Dopame 桌面显示有焦点的窗口的菜单).
- 单独跑的应用 (应用自己的
acdev dev、acdev test) 把它们显示在系统画的标题栏上: 菜单名在窗口按钮后面, 窗口标题让到它们右边. 按一下菜单名打开它的菜单; 方向键、回车和 Esc 操作打开的菜单, 选中一项就跑它的onSelect. 没有onSelect的项显示为禁用.acdev inspect最先列出菜单 (menuitem "文件" [collapsed] [w1.m1], 和打开的那个的各项,w1.m1.2),acdev act w1.m1.2 click打开菜单并选中这一项, 测试里getByRole('menuitem', { name: '新建' })能找到它们."frame": false时没有标题栏, 也就没有菜单.
一项的 shortcut ('ctrl+n', 写法同 shortcut(), 还认 mod, 在 macOS 上是 ⌘, 别处是 Ctrl) 显示在它旁边. 在桌面里它只是显示: 要让这个键起作用, 还要用 self.shortcut() 注册这个组合, 再处理 shortcut 事件. 单独跑的应用里它也被绑定, 在窗口有焦点时: 按下就跑这一项的 onSelect, 只要这一项有 onSelect 且没禁用. 这时页面收不到这个组合的 keydown (带 ctrl+c 的「编辑」菜单项也会从文本框那里拿走复制); 应用另外用 self.shortcut() 注册了同一组合时, 跑的是这一项, 不再来 shortcut 事件, 所以不会跑两次.
应用的第二个窗口
应用的第二个窗口 一节的链接应用和打开别的应用一样, 用 acde:open 的 open 再开一个自己的窗口. 配置里要有两样: multiple, 允许开第二个窗口; 以及 open 能力里有它自己的 id:
{ "id": "notes", "multiple": true, "requests": ["edit-note"], "capabilities": { "open": ["notes"] }}import { open } from 'acde:open'import { window as self } from 'acde:window'
const { window } = await open('notes', { kind: 'edit-note', note: 'todo' })
self.on('request', (request) => { if (request.kind === 'edit-note') load(request.note)})- 新窗口跑的是同一个
entry; 由请求告诉它显示什么. 和别的请求一样, 它要有一个应用在自己的requests里列出的kind; 不带请求的open('notes')开一个普通的窗口. - 没有
multiple时,open('notes', …)不开新窗口: 它 resolve 成已经在跑的那个窗口, 请求交给那个窗口. open里没有notes时, 调用被拒绝, 403forbidden(Notes may not use open notes (not in its manifest's capabilities)), 尽管那是应用自己的 id.- 第三个参数传
{ parent: self.id }, 新窗口就成为这个窗口的子窗口 (见 打开应用). - 这些窗口共享存储 (
localStorage、IndexedDB、cookie), 但不共享内存: 每个都是单独的页面.
浏览器接口
浏览器接口 一节的链接| 接口 | 在 acdev 里 |
|---|---|
window.close() |
关闭这个窗口 |
location.reload() |
重新载入这个窗口 |
alert() |
画在窗口里; confirm() / prompt() 返回 false / null |
| 外部链接 | 交给浏览器应用 |
| 下载 | 存进下载文件夹 |
Notification |
交给桌面显示 (没有桌面时发系统通知, Windows 除外: 那里单个应用什么都不显示, acde:capabilities 报告 notifications 是 unsupported) |
visibilitychange |
窗口隐藏 / 显示 |
screen.* |
屏幕的逻辑尺寸 |
模块入口
模块入口 一节的链接entry 也可以是一个模块, 默认导出 WindowApp:
import type { WindowApp } from '@dopame/acde-api'
const app: WindowApp = { mount(element, host) { host.setTitle('Hello') element.textContent = 'Hello from a module' return () => { element.textContent = '' } // 卸载 },}export default app内存和卡死
内存和卡死 一节的链接- 每个窗口的 JS 堆有上限 (
heapMb, 默认 256 MB). 超过只结束这一个窗口. - 一个任务跑超过 5 秒, 桌面会收到「无响应」, 可以结束它.