Textarea

支持光标、选择和丰富按键绑定的多行文本输入。

基本用法

Renderable API

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

const renderer = await createCliRenderer()

const textarea = new TextareaRenderable(renderer, {
  id: "notes",
  width: 50,
  height: 6,
  placeholder: "Type notes here...",
  backgroundColor: "#1a1a1a",
  focusedBackgroundColor: "#222222",
  textColor: "#FFFFFF",
  cursorColor: "#00FF88",
})

renderer.root.add(textarea)
textarea.focus()

提交处理

绑定提交操作并监听 onSubmit：

import { TextareaRenderable } from "@opentui/core"

const textarea = new TextareaRenderable(renderer, {
  width: 50,
  height: 6,
  onSubmit: () => {
    console.log("Submitted:", textarea.plainText)
  },
  keyBindings: [{ name: "return", ctrl: true, action: "submit" }],
})

占位符样式

const textarea = new TextareaRenderable(renderer, {
  width: 40,
  height: 4,
  placeholder: "Type here",
  placeholderColor: "#666666",
})

Construct API

暂不可用。目前请使用 TextareaRenderable。

属性

属性	类型	默认值	描述
`width`	`number` 或 `string`	-	以字符数或百分比表示的宽度
`height`	`number` 或 `string`	-	以行数或百分比表示的高度
`initialValue`	`string`	`""`	初始文本内容
`placeholder`	`string`、`StyledText` 或 `null`	`null`	占位符内容
`placeholderColor`	`string` 或 `RGBA`	`#666666`	占位符颜色
`backgroundColor`	`string` 或 `RGBA`	transparent	未聚焦时的背景颜色
`textColor`	`string` 或 `RGBA`	`#FFFFFF`	未聚焦时的文本颜色
`focusedBackgroundColor`	`string` 或 `RGBA`	transparent	聚焦时的背景颜色
`focusedTextColor`	`string` 或 `RGBA`	`#FFFFFF`	聚焦时的文本颜色
`wrapMode`	`"none"`、`"char"` 或 `"word"`	`"word"`	自动换行模式
`selectionBg`	`string` 或 `RGBA`	-	选区背景颜色
`selectionFg`	`string` 或 `RGBA`	-	选区前景颜色
`cursorColor`	`string` 或 `RGBA`	`#FFFFFF`	光标颜色
`cursorStyle`	`CursorStyleOptions`	-	光标样式和闪烁设置
`keyBindings`	`KeyBinding[]`	-	自定义按键绑定
`keyAliasMap`	`Record<string, string>`	-	按键别名映射
`onSubmit`	`(event: SubmitEvent) => void`	-	提交处理程序
`onContentChange`	`(event: ContentChangeEvent) => void`	-	内容变更时触发
`onCursorChange`	`(event: CursorChangeEvent) => void`	-	光标移动时触发

实用属性

属性	类型	描述
`plainText`	`string`	当前文本内容
`cursorOffset`	`number`	光标在缓冲区中的偏移量
`cursorCharacterOffset`	`number \| undefined`	光标下字符的偏移量（跳过尾部空白）
`logicalCursor`	`{ row, col }`	光标的逻辑行/列位置
`visualCursor`	`{ row, col, visualLine }`	视觉（换行后）光标位置
`traits`	`EditorTraits`	发布到宿主 UI 的编辑器特征（参见 Traits）

光标和选择控制

TextareaRenderable（及其基类 EditBufferRenderable）暴露了编程 API。你可以通过自己的按键绑定或命令来移动光标、编辑文本和驱动选择操作。所有支持选择的移动方法都接受 { select: true } 参数，用于扩展当前选择而不是移动光标。

光标移动

textarea.setCursor(row, col)
textarea.moveCursorLeft()
textarea.moveCursorRight({ select: true })
textarea.moveCursorUp()
textarea.moveCursorDown()

textarea.moveWordForward({ select: true })
textarea.moveWordBackward()

textarea.gotoLine(0)
textarea.gotoLineStart()
textarea.gotoLineTextEnd()
textarea.gotoLineHome({ select: true }) // Emacs-style smart home
textarea.gotoLineEnd()
textarea.gotoVisualLineHome()
textarea.gotoVisualLineEnd()
textarea.gotoBufferHome()
textarea.gotoBufferEnd({ select: true })

选择

textarea.setSelection(start, end) // half-open offsets
textarea.setSelectionInclusive(start, end) // inclusive end
textarea.selectAll()
textarea.clearSelection()
textarea.deleteSelection()

编辑

textarea.insertChar("a")
textarea.insertText("\ninserted")
textarea.deleteChar() // forward delete
textarea.deleteCharBackward() // backspace
textarea.deleteWordForward()
textarea.deleteWordBackward()
textarea.deleteToLineEnd()
textarea.deleteToLineStart()
textarea.deleteLine()
textarea.newLine()
textarea.undo()
textarea.redo()

这些方法会自动更新光标、清除任何活动的全局选择，并调用 requestRender()。

特征（Traits）

traits 属性允许编辑器向宿主 UI 声明其意图——它希望捕获哪些内置按键、是否希望界面在视觉上暂停，以及用于页脚或状态栏的简短状态标签。当赋值的 EditorTraits 对象与之前的值不同时，会触发 traits-changed 事件。

import { EditBufferRenderableEvents, type EditorTraits } from "@opentui/core"

textarea.traits = {
  capture: ["escape", "submit"], // consume these before host binds
  suspend: false,
  status: "Composing reply",
} satisfies EditorTraits

textarea.on(EditBufferRenderableEvents.TRAITS_CHANGED, (traits) => {
  updateFooter(traits.status ?? "")
})

字段	类型	描述
`capture`	`EditorCapture[]`	编辑器希望捕获的按键：`"escape"`、`"navigate"`、`"submit"`、`"tab"`
`suspend`	`boolean`	提示宿主暂停环境 UI（调暗边框、隐藏提示等）
`status`	`string`	可选的简短标签，用于在状态栏中显示编辑器模式

当销毁 renderable 时，traits 会重置为空对象。如果你需要在通用树中区分编辑器 renderable 和纯文本 renderable，可以使用 isEditBufferRenderable(renderable) 方法。