通知

OpenTUI 可以请求终端模拟器使用 OSC 转义序列显示桌面通知。将其用于长时间运行的任务、后台工作或需要关注的提示。

const ok = renderer.triggerNotification("Build finished", "OpenTUI")

triggerNotification(message, title?) 在 OpenTUI 检测到支持的通知协议时返回 true，否则返回 false。

能力检测

通过渲染器能力检查检测状态：

if (renderer.capabilities?.notifications) {
  renderer.triggerNotification("Tests passed", "CI")
}

OpenTUI 仅检测和发出终端 OSC 通知协议。它不调用平台工具，如 notify-send、AppleScript 或 PowerShell toast。

终端行为

终端和操作系统设置决定通知的显示方式。某些终端仅在终端未获焦点时显示横幅，macOS 可能根据应用通知设置将通知存储在通知中心而不显示横幅。

多路复用器

tmux 不转发原始通知 OSC 序列。当 OpenTUI 检测到 renderer.capabilities?.multiplexer === "tmux" 时，通知输出会包装在 tmux DCS 直通中。tmux 必须允许直通才能让外部终端接收通知：

set -g allow-passthrough on

如果通知需要从不可见的面板中工作，请使用 allow-passthrough all。

Zellij 通知转发基于 OSC 99。OpenTUI 忽略 Zellij 中继承的宿主终端通知提示，仅在 OSC 99 通知查询成功后或显式覆盖时才启用通知。Zellij 需要 OSC 99 通知转发支持才能正常工作。

覆盖设置

当终端检测无法查询最终终端路径时，使用环境覆盖进行诊断或部署：

OPENTUI_NOTIFICATION_PROTOCOL=osc99
OPENTUI_NOTIFICATIONS=0

OPENTUI_NOTIFICATION_PROTOCOL 接受 osc9、osc777、osc99 或 none。OPENTUI_NOTIFICATIONS=0、false 或 off 禁用通知。

请参阅 packages/examples/src/notification-demo.ts 获取交互式示例。