TTY#

稳定性:2 - 稳定

源代码: lib/tty.js

node:tty 模块提供了 tty.ReadStreamtty.WriteStream 类。在大多数情况下,没有必要或可能直接使用此模块。但是,可以使用以下方式访问它:

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

当 Node.js 检测到它在连接了文本终端("TTY")的情况下运行时,process.stdin 默认会被初始化为 tty.ReadStream 的实例,而 process.stdoutprocess.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 

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

类: tty.ReadStream#

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

readStream.isRaw#

一个 boolean 值,如果 TTY 当前配置为作为原始设备运行,则为 true

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

readStream.isTTY#

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

readStream.setRawMode(mode)#

  • mode <boolean> 如果为 true,则将 tty.ReadStream 配置为作为原始设备运行。如果为 false,则将 tty.ReadStream 配置为其默认模式运行。readStream.isRaw 属性将被设置为最终的模式。
  • 返回: <this> 读取流实例。

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

当处于原始模式时,输入总是逐个字符可用,不包括修饰符。此外,终端对字符的所有特殊处理都被禁用,包括回显输入字符。Ctrl+C 在此模式下将不再触发 SIGINT 事件。

类: tty.WriteStream#

表示 TTY 的可写端。在正常情况下,process.stdoutprocess.stderr 将是为 Node.js 进程创建的唯一的 tty.WriteStream 实例,并且没有理由创建额外的实例。

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

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

new tty.WriteStream(fd)#

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

事件: 'resize'#

每当 writeStream.columnswriteStream.rows 属性发生变化时,就会触发 'resize' 事件。调用时不会向监听器回调函数传递任何参数。

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

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 色。

用此方法确定终端支持的颜色。由于终端中颜色的特性,可能会出现假阳性(false positive)或假阴性(false negative)。这取决于进程信息和可能谎报所用终端的环境变量。可以传入一个 env 对象来模拟特定终端的使用。这对于检查特定环境设置的行为很有用。

要强制执行特定的颜色支持,请使用以下环境设置之一。

  • 2 色: FORCE_COLOR = 0 (禁用颜色)
  • 16 色: FORCE_COLOR = 1
  • 256 色: FORCE_COLOR = 2
  • 16,777,216 色: FORCE_COLOR = 3

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

writeStream.getWindowSize()#

writeStream.getWindowSize() 返回与此 WriteStream 对应的 TTY 的大小。数组的类型为 [numColumns, numRows],其中 numColumnsnumRows 分别代表相应 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). 

writeStream.isTTY#

一个 boolean 值,始终为 true

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 与 TTY 相关联,则 tty.isatty() 方法返回 true,否则返回 false,包括当 fd 不是非负整数时。