跳到主要内容
TABTAB

导航

能力桥 API

41 个方法，全部取自宿主源码的单一数据源。此表并非文档誊抄 —— 宿主增删一个方法，此处随之增减一行。

桥挂在每个插件窗口的 window.__TABTAB__ 上。 装上 @tabtab/plugin-sdk 可以拿到与之对应的类型声明与门面。

index.html
// 原始用法
await window.__TABTAB__.storage.set("k", "v");
const v = await window.__TABTAB__.storage.get("k");

// SDK 门面（推荐，有类型）
import { storage } from "@tabtab/plugin-sdk";
await storage.set("k", "v");

启动配置

宿主在页面加载前注入 window.__TABTAB__.config，包含：

appearancecommandCodehasAgenthostVersionpermissionspluginIdsensitiveversionwindowLabel

sensitive 标示该插件当前是否处于敏感权限同意门之下，permissions 是已被授权的权限集合 —— 判断「我现在能不能干某件事」应该读它，而不是读你自己的 manifest （后者写着但没被同意，一调就是 PERMISSION_DENIED）。

clipboard.*

  • clipboard.history→ ClipboardEntry[]后台线程代价：blocking

    读取宿主维护的剪贴板历史（新→旧，最多 50 条）。文本条目带全文，图片条目带尺寸与 48px 缩略图 dataURL。敏感能力，安装时需用户确认。

    需要权限clipboard:read
  • clipboard.readText→ string主线程

    读取系统剪贴板文本。敏感能力，安装时需用户确认。

    需要权限clipboard:read
  • clipboard.writeImage→ void主线程代价：blocking

    把历史里的某张图片写回系统剪贴板。文件名由宿主校验，插件无法借此读取任意磁盘文件。

    参数类型说明
    namestring`clipboard.history` 返回的图片条目 id（`<16位hex>.png`）。文件名会被宿主校验。
    需要权限clipboard:readclipboard:write
  • clipboard.writeText→ void主线程

    写入系统剪贴板。敏感能力，安装时需用户确认。

    参数类型说明
    textstring要写入的文本。
    需要权限clipboard:write

events.*

  • events.subscribe→ EventSubscription主线程

    订阅宿主事件。返回订阅 id，用 events.unsubscribe 取消。

    参数类型说明
    topicsstring[]要订阅的主题名，见 contract.json 的 bridge.topics。
    options可选object可选 `{ minIntervalMs }`。只能**收紧**不能放宽主题自带的下限。
    需要权限无
  • events.unsubscribe→ void主线程

    取消订阅。幂等：不存在的 id 也返回成功。

    参数类型说明
    idstringsubscribe 返回的订阅 id。
    需要权限无

fs.*

  • fs.listDir→ DirListing后台线程代价：blocking

    列举一个目录下的条目。目录排在文件之前、同类按名称排序，符号链接整个跳过（不列出也不跟随）。超限时 `truncated` 为 true，`total` 是目录里的真实条目数。

    参数类型说明
    pathstring要列举的目录绝对路径。必须是已存在的目录，不能是符号链接。
    limit可选number最多返回多少条，缺省 500，上限 2000。
    需要权限fs:read
  • fs.open→ void后台线程

    用**系统默认程序**打开一个本地文件（图片看图、pdf 进阅读器…）。路径校验与 `fs.preview` 同一条闸门 —— 它比 `shell.openUrl` 宽，因为那一条只放行 http/https。

    参数类型说明
    pathstring要用系统默认程序打开的文件的绝对路径。必须是存在的普通文件。
    需要权限fs:read
  • fs.preview→ FilePreview后台线程代价：blocking

    读一个文件并暂存，返回一个 `tabtab-file://` 地址交给 `<img>`/`<video>`/`<audio>` 直接渲染。字节不过桥 —— 一个 40MB 的 mp4 走桥会撞上客户端10 秒硬超时。超过 128MB 的文件拒绝暂存。

    参数类型说明
    pathstring要预览的文件的绝对路径。必须是存在的普通文件，且不能是符号链接。
    需要权限fs:read
  • fs.readText→ FileText后台线程代价：blocking

    把一个文本文件读成字符串，供代码/日志/配置类文件直接显示。超过上限时返回截断内容并置 `truncated: true` —— 插件应当明说「只显示了前 N 字节」，而不是假装读到了全文。

    参数类型说明
    pathstring要读的文件的绝对路径。
    maxBytes可选number最多读取多少字节，缺省 1 MiB，上限 4 MiB。超限截断并在返回值里标注。
    需要权限fs:read
  • fs.reveal→ void后台线程

    在系统文件管理器里定位一个路径（macOS Finder 选中、Windows 资源管理器选中、Linux 打开所在目录）。

    参数类型说明
    pathstring绝对路径。文件则定位到它，目录则直接打开。
    需要权限fs:read
  • fs.search→ FileSearchOutcome后台线程代价：expensive

    搜索本机文件。优先走系统索引（macOS Spotlight / Windows Everything），索引不可用时自动退到有界目录遍历。返回里的 `backend` 是**实际**生效的那个，插件可据此提示「索引没响应，已改用遍历」。

    参数类型说明
    querystring查询串。支持 `ext:png,jpg` / `path:/Users/me` / `type:folder` 三个前缀，其余部分对文件名做子串匹配（`*` 为通配符）。空串不触发任何搜索。
    limit可选number最多返回多少条，缺省 50，上限 200。
    需要权限fs:read
  • fs.writeText→ FileWriteResult后台线程代价：blocking

    创建一个文本文件，或在 `overwrite` 为 true 时覆盖它。**写不可逆**，请谨慎使用。敏感能力，安装时需用户确认。

    参数类型说明
    pathstring目标绝对路径。**必须落在用户家目录内**（比较前双方都规范化，所以家目录里的符号链接指不出去）。父目录必须已存在，宿主不替你建。
    textstring要写入的 UTF-8 文本。UTF-8 上限 16 MiB（比 fs.readText 的 4 MiB 宽：写出去的内容不渲染进 DOM，一整份日志是没问题的）。
    overwrite可选bool目标已存在时是否允许覆盖。缺省 false —— 宁可失败也不要静默吃掉用户的文件。
    需要权限fs:write

runtime.*

  • runtime.call→ any后台线程代价：expensive

    调用插件自带子进程的一个方法。仅 runtime.kind = "process" 的插件可用。

    参数类型说明
    methodstring子进程自己协议里的方法名。不受宿主命名空间约束。
    params可选object透传给子进程的参数对象。
    需要权限无

screen.*

  • screen.capture→ ScreenCapture主线程代价：blocking

    截取显示器画面。返回宿主暂存图的地址而非 base64。

    参数类型说明
    monitor可选number显示器 id，缺省主显示器。
    需要权限screen:capture
  • screen.copyImage→ void主线程代价：blocking

    把截图以图片形式写入剪贴板。

    参数类型说明
    rect可选rect裁剪区域，缺省整图。
    image可选string(image)插件合成的标注结果图（dataURL），优先于 rect。
    需要权限clipboard:writescreen:capture
  • screen.crop→ ScreenImage主线程代价：blocking

    从最近一次截图裁出一块，返回可访问地址。

    参数类型说明
    rect可选rect裁剪区域，缺省整图。四个字段须齐全。
    format可选enum(png|jpeg)输出格式，缺省 png（无损）。
    maxSide可选number限制最长边（只缩不放大）。
    需要权限screen:capture
  • screen.debug→ void主线程

    把一行诊断写进宿主终端。永不抛出。不需要任何权限。

    参数类型说明
    messagestring单行诊断文本，超长在宿主侧截断。
    需要权限无
  • screen.hide→ void主线程

    收起本插件窗（隐藏，不销毁）。

    需要权限screen:capture
  • screen.monitors→ MonitorInfo[]主线程

    列出全部显示器。

    需要权限screen:capture
  • screen.overlay→ void主线程

    把本插件窗切换成／还原自全屏取图层。

    参数类型说明
    active可选booltrue 进入全屏取图层，false 还原。缺省 true。
    monitor可选number浮层铺在哪块屏，须与 capture 同屏。
    需要权限screen:capture
  • screen.pin→ { pinned, url }主线程代价：blocking

    把截图钉在屏幕最上层（贴图）。

    参数类型说明
    rect可选rect裁剪区域，缺省整图。
    image可选string(image)插件合成的标注结果图，优先于 rect。
    需要权限screen:capture
  • screen.present→ void主线程

    把已隐藏的取图浮层重新显示并聚焦。

    需要权限screen:capture
  • screen.saveImage→ SaveImageResult主线程代价：blocking

    把截图保存成 PNG，路径由宿主决定。

    参数类型说明
    rect可选rect裁剪区域，缺省整图。
    name可选string文件名。目录由宿主决定，插件无法指定路径。
    image可选string(image)插件合成的标注结果图，优先于 rect。
    需要权限screen:capture
  • screen.saveImageAs→ SaveImageAsResult后台线程代价：blocking

    弹系统保存对话框由用户选位置。用户取消返回 saved:false，不是错误。

    参数类型说明
    rect可选rect裁剪区域，缺省整图。
    name可选string建议文件名，缺省用时间戳。
    image可选string(image)插件合成的标注结果图，优先于 rect。
    需要权限screen:capture
  • screen.windows→ WindowRect[]后台线程代价：expensive

    列出指定屏上的窗口矩形（已换算为截图像素）。实测约 2.2 秒。

    参数类型说明
    monitor可选number显示器 id，缺省主显示器。
    需要权限screen:capture

shell.*

  • shell.openUrl→ void主线程

    用系统默认浏览器打开网址。页面在宿主之外，插件无法读取或操控它。

    参数类型说明
    urlstring仅接受 http:// 与 https:// 地址。其它 scheme 一律拒绝。
    需要权限shell:open

storage.*

  • storage.delete→ void主线程

    删除本插件存储中的某个键。

    参数类型说明
    keystring键名。
    需要权限storage
  • storage.get→ string主线程

    读取本插件私有存储的值。

    参数类型说明
    keystring键名。不能含 `:`（否则可注入他人命名空间）。
    需要权限storage
  • storage.list→ string[]主线程

    列出本插件存储的键（已剥掉命名空间前缀）。

    参数类型说明
    prefix可选string可选前缀。空串等同不过滤。
    需要权限storage
  • storage.set→ void主线程

    写入本插件私有存储。

    参数类型说明
    keystring键名。不能含 `:`。
    value可选string值。单次上限 64 KiB。
    需要权限storage

web.*

  • web.close→ { closed }主线程

    关闭网页窗口。幂等。

    参数类型说明
    slot可选string槽位名：同一插件可开多个互不干扰的网页窗口。不传即默认槽。
    需要权限web
  • web.eval→ { evaluated }主线程

    在网页窗口执行一段 JS。结果经 web.result 读回。

    参数类型说明
    scriptstring要执行的 JS。上限 8 MiB。建议写成表达式。
    slot可选string槽位名：同一插件可开多个互不干扰的网页窗口。不传即默认槽。
    需要权限web
  • web.getTitle→ { title }主线程

    读取网页窗口的 document.title。

    参数类型说明
    slot可选string槽位名：同一插件可开多个互不干扰的网页窗口。不传即默认槽。
    需要权限web
  • web.hide→ { hidden }主线程

    隐藏本插件的网页窗口。

    参数类型说明
    slot可选string槽位名：同一插件可开多个互不干扰的网页窗口。不传即默认槽。
    需要权限web
  • web.open→ { opened, window }主线程

    打开（或复用）本插件的网页窗口并导航到 url。

    参数类型说明
    urlstring仅接受 https:// 地址。
    slot可选string槽位名：同一插件可开多个互不干扰的网页窗口。不传即默认槽。
    visible可选boolfalse 时隐藏打开（页面照常加载）。缺省 true。
    需要权限web
  • web.result→ { result?, pending? }主线程

    取回最近一次 eval 的返回值，未就绪时 pending。

    参数类型说明
    slot可选string槽位名：同一插件可开多个互不干扰的网页窗口。不传即默认槽。
    需要权限web
  • web.show→ { shown }主线程

    显示本插件的网页窗口。

    参数类型说明
    slot可选string槽位名：同一插件可开多个互不干扰的网页窗口。不传即默认槽。
    需要权限web

顶层方法

  • ping()→ { ok }主线程

    连通性自检，不做任何事。

    需要权限无

事件

用 events.subscribe(topic, handler) 订阅，返回的订阅 id 用 events.unsubscribe 取消。

  • app.focus

    宿主主窗被唤起。payload: {}

  • clipboard.changed

    系统剪贴板文本变化。payload: { text }

  • timer.cron

    周期心跳。payload: { at }（毫秒时间戳）。宿主按 minIntervalMs 节流。