Node.js v26.0.0 文档

TTY#

node:tty 模块提供了 tty.ReadStream 和 tty.WriteStream 类。在大多数情况下，无需也不可能直接使用此模块。不过，可以通过以下方式访问它

const tty = require('node:tty');
copy

当 Node.js 检测到它是在附加了文本终端（“TTY”）的情况下运行时，process.stdin 默认会被初始化为 tty.ReadStream 的实例，而 process.stdout 和 process.stderr 默认会是 tty.WriteStream 的实例。确定 Node.js 是否在 TTY 上下文中运行的首选方法是检查 process.stdout.isTTY 属性的值是否为 true。

$ node -p -e "Boolean(process.stdout.isTTY)"
true
$ node -p -e "Boolean(process.stdout.isTTY)" | cat
false
copy

在大多数情况下，应用程序几乎没有理由手动创建 tty.ReadStream 和 tty.WriteStream 类的实例。

类：tty.ReadStream#

• 继承自：<net.Socket>

表示 TTY 的可读端。在正常情况下，process.stdin 将是 Node.js 进程中唯一的 tty.ReadStream 实例，因此没有理由创建额外的实例。

readStream.isRaw#

一个 boolean 值，如果 TTY 当前配置为以原始（raw）设备模式运行，则为 true。

当进程启动时，此标志始终为 false，即使终端在原始模式下运行也是如此。其值将随着后续对 setRawMode 的调用而改变。

readStream.isTTY#

一个对于 tty.ReadStream 实例始终为 true 的 boolean 值。

readStream.setRawMode(mode)#

• mode <boolean> 如果为 true，则将 tty.ReadStream 配置为以原始设备模式运行。如果为 false，则将 tty.ReadStream 配置为以其默认模式运行。readStream.isRaw 属性将被设置为所得到的模式。
• 返回：<this> 读取流实例。

允许配置 tty.ReadStream 以使其作为原始设备运行。

在原始模式下，输入始终是逐字符可用的，不包括修饰符。此外，终端对字符的所有特殊处理都会被禁用，包括回显输入字符。在此模式下，Ctrl+C 将不再导致 SIGINT。

类：tty.WriteStream#

• 继承自：<net.Socket>

表示 TTY 的可写端。在正常情况下，process.stdout 和 process.stderr 将是为 Node.js 进程创建的仅有的 tty.WriteStream 实例，不应有理由创建额外的实例。

new tty.ReadStream(fd[, options])#

• fd <number> 与 TTY 关联的文件描述符。
• options <Object> 传递给父级 net.Socket 的选项，请参阅 net.Socket 构造函数 的 options。
• 返回：<tty.ReadStream>

为与 TTY 关联的 fd 创建一个 ReadStream。

new tty.WriteStream(fd)#

• fd <number> 与 TTY 关联的文件描述符。
• 返回：<tty.WriteStream>

为与 TTY 关联的 fd 创建一个 WriteStream。

事件：'resize'#

每当 writeStream.columns 或 writeStream.rows 属性发生变化时，就会触发 'resize' 事件。调用监听器回调时不会传入任何参数。

process.stdout.on('resize', () => {
  console.log('screen size has changed!');
  console.log(`${process.stdout.columns}x${process.stdout.rows}`);
});
copy

writeStream.clearLine(dir[, callback])#

• dir <number>
  • -1：从光标向左清除
  • 1：从光标向右清除
  • 0：清除整行
• callback <Function> 操作完成后调用。
• 返回: <boolean> 如果流希望调用代码等待 'drain' 事件触发后再继续写入更多数据，则返回 false；否则返回 true。

writeStream.clearLine() 会按照 dir 指定的方向清除此 WriteStream 的当前行。

writeStream.clearScreenDown([callback])#

• callback <Function> 操作完成后调用。
• 返回: <boolean> 如果流希望调用代码等待 'drain' 事件触发后再继续写入更多数据，则返回 false；否则返回 true。

writeStream.clearScreenDown() 从当前光标位置向下清除此 WriteStream。

writeStream.columns#

一个 number，指定 TTY 当前拥有的列数。此属性在每次触发 'resize' 事件时更新。

writeStream.cursorTo(x[, y][, callback])#

• x <number>
• y <number>
• callback <Function> 操作完成后调用。
• 返回: <boolean> 如果流希望调用代码等待 'drain' 事件触发后再继续写入更多数据，则返回 false；否则返回 true。

writeStream.cursorTo() 将此 WriteStream 的光标移动到指定位置。

writeStream.getColorDepth([env])#

• env <Object> 包含要检查的环境变量的对象。这使得模拟特定终端的使用成为可能。默认值： process.env。
• 返回: <number>

返回

• 1 表示支持 2 色，
• 4 表示支持 16 色，
• 8 表示支持 256 色，
• 24 表示支持 16,777,216 色。

使用此方法可确定终端支持的颜色。由于终端颜色的性质，可能会出现误报或漏报。这取决于进程信息以及可能对所用终端进行虚假陈述的环境变量。可以传入 env 对象来模拟特定终端的使用。这对于检查特定环境设置的行为非常有用。

要强制执行特定的颜色支持，请使用以下环境变量设置之一：

• 2 色：FORCE_COLOR = 0（禁用颜色）
• 16 色：FORCE_COLOR = 1
• 256 色：FORCE_COLOR = 2
• 16,777,216 色：FORCE_COLOR = 3

也可以通过使用 NO_COLOR 和 NODE_DISABLE_COLORS 环境变量来禁用颜色支持。

writeStream.getWindowSize()#

• 返回：<number[]>

writeStream.getWindowSize() 返回与此 WriteStream 对应的 TTY 大小。该数组的类型为 [numColumns, numRows]，其中 numColumns 和 numRows 分别代表对应 TTY 的列数和行数。

writeStream.hasColors([count][, env])#

• count <integer> 请求的颜色数量（最少为 2）。默认值： 16。
• env <Object> 包含要检查的环境变量的对象。这使得模拟特定终端的使用成为可能。默认值： process.env。
• 返回：<boolean>

如果 writeStream 支持的颜色数量至少达到 count，则返回 true。最低支持为 2 色（黑白）。

这与 writeStream.getColorDepth() 中描述的内容具有相同的误报和漏报情况。

process.stdout.hasColors();
// Returns true or false depending on if `stdout` supports at least 16 colors.
process.stdout.hasColors(256);
// Returns true or false depending on if `stdout` supports at least 256 colors.
process.stdout.hasColors({ TMUX: '1' });
// Returns true.
process.stdout.hasColors(2 ** 24, { TMUX: '1' });
// Returns false (the environment setting pretends to support 2 ** 8 colors).
copy

writeStream.isTTY#

一个始终为 true 的 boolean 值。

writeStream.moveCursor(dx, dy[, callback])#

• dx <number>
• dy <number>
• callback <Function> 操作完成后调用。
• 返回: <boolean> 如果流希望调用代码等待 'drain' 事件触发后再继续写入更多数据，则返回 false；否则返回 true。

writeStream.moveCursor() 将此 WriteStream 的光标相对于其当前位置进行移动。

writeStream.rows#

一个 number，指定 TTY 当前拥有的行数。此属性在每次触发 'resize' 事件时更新。

tty.isatty(fd)#

• fd <number> 数字文件描述符。
• 返回：<boolean>

如果给定的 fd 与 TTY 关联，则 tty.isatty() 方法返回 true，否则返回 false（包括 fd 不是非负整数的情况）。