快速入门

OpenTUI 是一个用 Zig 编写的原生终端 UI 核心，带有 TypeScript 绑定。原生核心通过 C ABI 暴露接口，可以从任何语言使用。OpenTUI 目前在生产环境中驱动 OpenCode，未来也将驱动 terminal.shop。它是一个可扩展的核心，专注于正确性、稳定性和高性能。它提供基于组件的架构和灵活的布局能力，让你能够创建复杂的终端应用程序。

安装

OpenTUI 的渲染器示例使用 Bun。你可以在 Node.js 中导入可移植的入口点，如 @opentui/keymap 和 @opentui/core，无需安装 Bun 或启用 FFI。这些导入不会创建原生渲染器。要在 Node.js 中创建原生渲染器，你需要 Node.js 26.3.0 并启用实验性 FFI。

mkdir my-tui && cd my-tui
bun init -y
bun add @opentui/core

运行时支持

导入包不需要原生 FFI。例如，Node.js 可以加载 await import("@opentui/keymap") 和 await import("@opentui/core")，无需 --experimental-ffi。

创建原生渲染器需要 FFI。这包括调用 createCliRenderer() 或任何其他加载和调用 OpenTUI 原生 Zig 渲染器的 API。在 Node.js 中，使用 Node.js 26.3.0 并添加 --experimental-ffi。如果你使用 Node.js 权限机制，还必须添加 --allow-ffi 以及应用所需的文件系统权限。OpenTUI 不会安装 Node.js，因此在运行 Node.js 相关示例或脚本之前，请选择所需的版本。

Hello world

创建 index.ts：

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

const renderer = await createCliRenderer({
  exitOnCtrlC: true,
})

renderer.root.add(
  Text({
    content: "Hello, OpenTUI!",
    fg: "#00FF00",
  }),
)

运行它：

bun index.ts

你应该能看到绿色的文本。按 Ctrl+C 退出。

组合组件

组件可以自然嵌套。以下是一个带边框和内容的面板示例：

import { createCliRenderer, Box, Text } from "@opentui/core"

const renderer = await createCliRenderer({
  exitOnCtrlC: true,
})

renderer.root.add(
  Box(
    { borderStyle: "rounded", padding: 1, flexDirection: "column", gap: 1 },
    Text({ content: "Welcome", fg: "#FFFF00" }),
    Text({ content: "Press Ctrl+C to exit" }),
  ),
)

Box 和 Text 是工厂函数。第一个参数是属性（props），后续参数是子元素。

下一步

核心概念

• 渲染器 - 渲染引擎
• 布局 - Flexbox 定位
• Constructs - 声明式组件 API

组件

• Text、Box - 显示和布局
• Input、Select - 用户交互

框架绑定

OpenTUI 单仓库包含 @opentui/react 和 @opentui/solid。其他语言和框架绑定位于独立的仓库中。

• React
• Solid.js