本指南目前只有简体中文版。 This guide is only in Chinese for now.

LaunchUS 插件

插件是 LaunchUS 本体之外的可选功能：想用才装，不占本体的体积。插件有两种：

安装

任选一种，从官网下载的 .zip 不用自己解压：

1. 设置 › 插件 › 「安装插件…」，选 .zip 或解压出来的文件夹；
2. 把 .zip 或文件夹拖进小组件库；
3. 直接放进上面的文件夹，LaunchUS 会监视它，增删立刻生效。

LaunchUS 会自己解压 .zip，找到里面的 .launchuswidget 或 .launchusplugin 文件夹装好；压缩包里只有一个带 manifest.json 的文件夹也行。解压出来的东西不会被运行，只是复制。

能力插件

一个以 .launchusplugin 结尾的文件夹，里面只有一个 manifest.json：

{
  "spec": 1,
  "id": "com.launchus.notch-shelf",
  "capability": "notch-shelf",
  "name": { "en": "Notch Shelf", "zh-Hans": "刘海暂存区" },
  "description": { "en": "Drag files to the notch to park them there." },
  "version": "1.0.0",
  "author": "LaunchUS",
  "symbol": "tray.and.arrow.down"
}

能力的代码在 LaunchUS 里，插件包不带可执行内容，所以装一个能力插件不会让第三方代码在你的 Mac 上运行。新的能力随 LaunchUS 更新加入；想要新的能力，到论坛提出来。

现有的能力

• notch-shelf（刘海暂存区）：拖文件时，屏幕上方的刘海下面刷出一个暂存区。把文件放进去，它们会一直留着（小标签显示个数，指针移上去展开），直到你把它们拖出来；拖到别处放下成功后，才会从暂存区拿掉。暂存区记的是文件的位置，不复制文件。文件被删或移走后，下次显示时自动去掉。

不需要任何权限提示：它只读你正在拖的文件，只在你拖动时出现。

小组件插件规范（第 1 版）

插件有两种：小组件插件（本文）和给系统加能力的能力插件，见 PLUGINS.md。

LaunchUS 的小组件和 App 图标一起放在网格里，占 2×2、4×2 或 4×4 格，可以拖动、改大小、移除。 小组件分两种：

• 系统小组件：LaunchUS 自带，ID 以 launchus. 开头：
• 时间与日程：时钟与日期（launchus.clock）、指针时钟（launchus.analog-clock）、日历与提醒事项（launchus.calendar）、节日倒数（launchus.countdown）、时间进度（launchus.progress）。
• 实用工具：便签（launchus.note，支持 Markdown）、待办（launchus.todo）、常用应用（launchus.apps）、计时器（launchus.timer）、快捷操作（launchus.actions）、剪贴板（launchus.clipboard，只存在内存里）。
• 系统：系统状态（launchus.system）、电池（launchus.battery）、网络（launchus.network）、存储空间（launchus.storage）。
• 生活：天气（launchus.weather，接下来几小时和一周的预报）、快递（launchus.parcel，记下快递单号，点一下打开快递公司的查询页）。
• 插件小组件：任何人用 HTML / CSS / JavaScript 写的外置插件，本文就是它的规范。

在启动台空白处右键 →「添加小组件…」打开小组件库，或者用链接 launchus://widgets。库里列出全部系统小组件和已安装的插件，可以预览每种尺寸，再添加到当前页。

1. 插件包

一个插件是一个以 .launchuswidget 结尾的文件夹：

weekend.launchuswidget/
├── manifest.json   必需：插件说明
├── index.html      必需：画小组件的页面（文件名可在 manifest 里改）
├── icon.png        可选：小组件库里显示的图标，建议 256×256
└── …               页面用到的其他文件（CSS、JS、图片、字体）

安装

任选一种：

1. 小组件库里点「安装插件…」，选中插件文件夹；
2. 把插件文件夹拖进小组件库；
3. 直接放进 ~/Library/Application Support/LaunchUS/Widgets/（库里点「打开插件文件夹」）。

LaunchUS 会监视这个文件夹，增删插件立刻生效。改了插件里的文件后，打开一次小组件库就会重新扫描，网格上的页面也会重新载入。 安装同一个 id 的插件会替换旧的（旧的移到废纸篓）。库里可以把插件「移到废纸篓」；网格上用了这个插件的小组件会显示「未安装的小组件」，装回来就恢复。

2. manifest.json

{
  "spec": 1,
  "id": "com.example.weekend",
  "name": { "en": "Weekend", "zh-Hans": "周末倒计时", "ja": "週末まで" },
  "description": { "en": "Days left until the weekend.", "zh-Hans": "离周末还有几天。" },
  "version": "1.0.0",
  "author": "Example",
  "homepage": "https://example.com",
  "icon": "icon.png",
  "symbol": "calendar.badge.clock",
  "sizes": ["small", "medium"],
  "entry": "index.html",
  "refresh": 60,
  "permissions": [],
  "open": "https://example.com"
}

没有 open 和 openApp 时点击小组件不做任何事。

3. 页面

页面在一个不接收鼠标的网页视图里显示，铺满整张卡片：

• 点击、拖动、长按都归启动台：点击打开 open / openApp，拖动挪位置，长按进入编辑。页面里的按钮、链接、滚动都不会响应——把小组件当成一块会自己更新的屏幕来设计。
• 背景要透明：卡片的玻璃 / 半透明底由 LaunchUS 画，页面别设 body 背景色（或用半透明色）。
• 边距自己留：系统小组件的内边距是卡片短边的 9%，约等于 calc(var(--launchus-unit) * 0.18)。
• 跟着卡片缩放：同一个尺寸在不同显示器、不同网格密度下大小不同。用 --launchus-unit 定字号和间距，不要写死像素。
• 深色 / 浅色：全屏启动台里卡片总是深色；窗口模式跟随系统外观。看 launchus.theme 或 <html data-theme>，color-scheme 已经设好。
• 页面只能读自己文件夹里的文件，不能跳转到别的页面；本地存储（localStorage 等）不会保留到下次载入。

页面拿到的 CSS 变量和属性

LaunchUS 在页面脚本运行之前给 <html> 设好：

window.launchus

interface LaunchUS {
  readonly spec: 1
  readonly size: "small" | "medium" | "large"
  readonly width: number        // 卡片宽，pt
  readonly height: number       // 卡片高，pt
  readonly unit: number         // 同 --launchus-unit，pt
  readonly theme: "dark" | "light"
  readonly locale: string       // Mac 的首选语言，如 "zh-Hans-CN"
  readonly visible: boolean     // 启动台是否打开着
  on(event: "change" | "show" | "hide" | "refresh", fn: (detail?: any) => void): void
  off(event: string, fn: Function): void
  system(): Promise<SystemSample>   // 需要 "system" 权限
}

interface SystemSample {
  cpu: number                                   // 0–1，全部核心
  memory: { used: number, total: number }       // 字节
  disk:   { used: number, total: number }       // 字节，启动磁盘
  battery: { level: number, charging: boolean } | null   // level 0–1；没有电池时为 null
  network: { download: number, upload: number } // 字节 / 秒
  uptime: number                                // 开机以来的秒数
}

事件：

launchus 在页面任何脚本之前就已存在，不需要等待。

4. 权限

小组件库会把插件的权限显示给用户（「可以联网」「不联网」「读取系统状态」）。只申请真正用到的权限。

插件拿不到的东西：本地文件（自己文件夹以外）、日历、通讯录、剪贴板、启动台的布局和 App 列表、打开链接或 App（只能由用户点击触发 open / openApp）。

5. 性能

• 启动台收起时 LaunchUS 停发 refresh，并发 hide；请在 hide 时停掉 setInterval 和 requestAnimationFrame，show 时恢复。
• 每个小组件是一个网页视图。保持页面轻：不要引入大型框架，不要持续动画。
• 小组件库里的预览也是真实运行的页面。

6. 版本兼容

• 新版 LaunchUS 读得懂旧版插件。规范只做向后兼容的扩展：加字段、加权限、加事件。
• 不兼容的改动会把 spec 加 1，旧版 LaunchUS 遇到更高的 spec 不载入插件。
• 插件可以检查 launchus.spec 和某个方法是否存在，在旧版上降级。

7. 示例

docs/widgets/ 里有两个能直接安装的示例：

• weekend.launchuswidget：离周末还有几天和今年过了多少，不需要任何权限，演示多语言名字、data-size 和 --launchus-unit。
• cpu-graph.launchuswidget：CPU 和内存的走势图，用 system 权限和 refresh，在 hide 时暂停。

最小可用的插件：

{ "id": "com.example.hello", "name": "Hello", "sizes": ["small"] }

<!doctype html>
<meta charset="utf-8">
<style>
  body { margin: 0; height: 100vh; display: grid; place-items: center;
         font: 600 calc(var(--launchus-unit) * 0.3) -apple-system, sans-serif; color: white; }
  html[data-theme="light"] body { color: black; }
</style>
<body>Hello</body>

← 插件社区