控制台覆盖层

OpenTUI 包含一个内置的控制台覆盖层，可以捕获所有 console.log、console.info、console.warn、console.error 和 console.debug 调用。你可以将控制台定位在终端的任意边缘。它支持滚动和焦点管理。

基本用法

import { createCliRenderer, ConsolePosition } from "@opentui/core"

const renderer = await createCliRenderer({
  consoleOptions: {
    position: ConsolePosition.BOTTOM,
    sizePercent: 30,
  },
})

// 这些将显示在覆盖层中而不是 stdout
console.log("This appears in the overlay")
console.error("Errors are color-coded red")
console.warn("Warnings appear in yellow")

控制台与 stdout

consoleMode 仅控制覆盖层面板。要禁用全局 console.* 捕获，请设置 OTUI_USE_CONSOLE=false。

externalOutputMode 控制通过渲染器配置的 stdout.write 进行的写入。stderr 是独立的。

配置选项

const renderer = await createCliRenderer({
  consoleOptions: {
    position: ConsolePosition.BOTTOM, // 屏幕位置
    sizePercent: 30, // 以终端百分比表示的大小
    colorInfo: "#00FFFF", // console.info 的颜色
    colorWarn: "#FFFF00", // console.warn 的颜色
    colorError: "#FF0000", // console.error 的颜色
    startInDebugMode: false, // 在日志中显示文件/行号信息
  },
})

控制台位置

import { ConsolePosition } from "@opentui/core"

ConsolePosition.TOP // 停靠在顶部
ConsolePosition.BOTTOM // 停靠在底部
ConsolePosition.LEFT // 停靠在左侧
ConsolePosition.RIGHT // 停靠在右侧

切换控制台

在代码中切换控制台覆盖层：

// 切换可见性和焦点
renderer.console.toggle()

// 当打开但未获得焦点时，toggle() 会让控制台获得焦点
// 当获得焦点时，toggle() 会关闭控制台

控制台快捷键

当控制台获得焦点时：

切换快捷键绑定

添加键盘快捷键来切换控制台：

renderer.keyInput.on("keypress", (key) => {
  // 使用反引号键切换
  if (key.name === "`") {
    renderer.console.toggle()
  }

  // 或使用修饰键
  if (key.ctrl && key.name === "l") {
    renderer.console.toggle()
  }
})

为什么使用控制台？

终端 UI 应用程序会捕获 stdout 用于渲染。普通的 console.log 调用会干扰你的界面。控制台覆盖层解决了这个问题：

• 捕获所有控制台输出而不干扰 UI
• 在专用的覆盖层区域显示日志
• 用不同颜色标识不同的日志级别，便于识别
• 允许你滚动浏览历史记录进行调试

环境变量

通过环境变量控制控制台行为：

# 完全禁用控制台捕获
OTUI_USE_CONSOLE=false bun app.ts

# 启动时显示控制台
SHOW_CONSOLE=true bun app.ts

# 退出时转储捕获的输出
OTUI_DUMP_CAPTURES=true bun app.ts