TUI API

终端 UI 辅助能力位于 ptool.tui 和 p.tui 下。

第一版聚焦于由 Lua 事件循环驱动的小型交互式终端界面。

ptool.tui.run

Unreleased - 引入。

ptool.tui.run(options) 启动一个 TUI 会话，运行 Lua 生命周期回调，并返回 app:quit(value) 传入的值。如果调用的是 app:quit()，则返回 nil。

options 字段：

• tick_ms（integer，可选）：tick 间隔，单位毫秒。默认值为 100。
• init（function，可选）：在绘制第一帧前调用一次。它的返回值会成为初始 state。
• update（function，必填）：以 update(state, event, app) 的形式调用，在每次输入事件或 tick 后执行。如果它返回非 nil 值，该值会成为下一次的 state。返回 nil 会保留当前 state。
• view（function，必填）：以 view(state, app) 的形式调用，用来构建下一帧的根节点。

行为：

• 需要交互式 TTY。
• 运行时会进入终端 alternate screen 并启用 raw mode。
• 退出时会恢复终端状态，包括错误路径。

事件：

• { type = "tick" }
• { type = "resize", width = <integer>, height = <integer> }
• { type = "key", key = <string>, ctrl = <boolean>, alt = <boolean>, shift = <boolean> }

常见按键名包括 up、down、left、right、enter、esc、tab、backspace、delete、home、end、pageup 和 pagedown。字符键直接使用字符本身，例如 "q" 或 "j"。

示例：

local result = p.tui.run({
  tick_ms = 200,
  init = function()
    return {
      items = {"alpha", "beta", "gamma"},
      selected = 1,
    }
  end,
  update = function(state, event, app)
    if event.type == "key" then
      if event.key == "q" then
        app:quit(state.items[state.selected])
      elseif event.key == "down" then
        state.selected = math.min(#state.items, state.selected + 1)
      elseif event.key == "up" then
        state.selected = math.max(1, state.selected - 1)
      end
    end
  end,
  view = function(state)
    return p.tui.column({
      title = "Demo",
      border = true,
      padding = 1,
      children = {
        p.tui.text("Press q to quit", {
          align = "center",
        }),
        p.tui.list(state.items, {
          selected = state.selected,
          highlight_style = {
            reversed = true,
          },
        }),
      },
    })
  end,
})

print("selected:", result)

App

Unreleased - 引入。

app 会传给 update(...) 和 view(...)。

quit

规范 API 名称：ptool.tui.App:quit。

app:quit(value?) 会请求在当前回调结束后停止 TUI 会话。

• value（Lua 值，可选）：ptool.tui.run(...) 的返回值。

节点构造器

Unreleased - 引入。

下面这些构造器返回普通的节点 table。view(...) 必须返回其中一个节点作为根视图树。

通用节点字段：

• title（string，可选）：为节点绘制带标题的 block。
• border（boolean，可选）：为节点绘制边框。默认值为 false。
• padding（integer，可选）：统一的内边距。默认值为 0。
• grow（integer，可选）：节点位于 row 或 column 中时的相对尺寸。默认值为 1。
• style（table，可选）：通用样式字段：
  • fg / bg：可选值为 black、red、green、yellow、blue、magenta、cyan、white、gray、dark_gray。
  • bold、dim、italic、underlined、reversed：布尔样式开关。

ptool.tui.text

Unreleased - 引入。

ptool.tui.text(text[, options]) 创建一个文本节点。

• text（string，必填）：要渲染的文本。
• options.align（string，可选）：left、center 或 right。默认值为 left。

ptool.tui.list

Unreleased - 引入。

ptool.tui.list(items[, options]) 创建一个垂直列表节点。

• items（table，必填）：一个致密 list table。元素值可以是字符串、数字或布尔值。
• options.selected（integer，可选）：使用 Lua 的 1-based 索引指定选中行。超出元素数量的值会被忽略。
• options.highlight_style（table，可选）：应用到选中行的样式。使用与 style 相同的键。

说明：

• 只有当 highlight_style 改变渲染样式时，选中项才会在视觉上明显区分。

ptool.tui.row

Unreleased - 引入。

ptool.tui.row(options) 创建一个水平容器。

• options.children（table，必填）：一个由子节点组成的致密 list table。

ptool.tui.column

Unreleased - 引入。

ptool.tui.column(options) 创建一个垂直容器。

• options.children（table，必填）：一个由子节点组成的致密 list table。

当前限制

ptool.tui 当前支持：

• tick、resize 和键盘事件。
• text、list、row 和 column 节点。
• 基础的 block 装饰和样式选项。

暂时还不提供文本输入框、弹窗、表格、鼠标驱动控件或任意 ratatui widget 绑定。