Node.js v24.0.0 文档

事件：'close'#

当发生以下情况之一时，会触发 'close' 事件

• 调用 rl.close() 方法，并且 InterfaceConstructor 实例已放弃对 input 和 output 流的控制；
• input 流接收到其 'end' 事件；
• input 流接收到 Ctrl+D 以表示传输结束（EOT）；
• input 流接收到 Ctrl+C 以表示 SIGINT，并且在 InterfaceConstructor 实例上未注册 'SIGINT' 事件监听器。

调用监听器函数时不传递任何参数。

一旦触发 'close' 事件，InterfaceConstructor 实例就完成了。

事件：'line'#

每当 input 流接收到行尾输入（\n、\r 或 \r\n）时，就会触发 'line' 事件。 这通常发生在用户按下 Enter 或 Return 时。

如果已从流中读取新数据，并且该流在没有最终行尾标记的情况下结束，也会触发 'line' 事件。

调用监听器函数时会传递一个字符串，其中包含接收到的输入的单行。

rl.on('line', (input) => {
  console.log(`Received: ${input}`);
}); copy

事件：'history'#

每当历史记录数组发生更改时，都会触发 'history' 事件。

调用监听器函数时会传递一个包含历史记录数组的数组。 它将反映由于 historySize 和 removeHistoryDuplicates 导致的所有更改、添加的行和删除的行。

主要目的是允许监听器持久化历史记录。 监听器也可以更改历史记录对象。 这对于防止某些行添加到历史记录中很有用，例如密码。

rl.on('history', (history) => {
  console.log(`Received: ${history}`);
}); copy

事件：'pause'#

当发生以下情况之一时，会触发 'pause' 事件

• input 流已暂停。
• input 流未暂停，并且接收到 'SIGCONT' 事件。 （请参阅事件 'SIGTSTP' 和 'SIGCONT'。）

调用监听器函数时不传递任何参数。

rl.on('pause', () => {
  console.log('Readline paused.');
}); copy

事件：'resume'#

每当 input 流恢复时，就会触发 'resume' 事件。

调用监听器函数时不传递任何参数。

rl.on('resume', () => {
  console.log('Readline resumed.');
}); copy

事件：'SIGCONT'#

当之前使用 Ctrl+Z（即 SIGTSTP）移到后台的 Node.js 进程然后使用 fg(1p) 带回前台时，会触发 'SIGCONT' 事件。

如果 input 流在 SIGTSTP 请求之前暂停，则不会触发此事件。

调用监听器函数时不传递任何参数。

rl.on('SIGCONT', () => {
  // `prompt` will automatically resume the stream
  rl.prompt();
}); copy

Windows 上不支持 'SIGCONT' 事件。

事件：'SIGINT'#

每当 input 流接收到 Ctrl+C 输入（通常称为 SIGINT）时，就会触发 'SIGINT' 事件。 如果在 input 流接收到 SIGINT 时未注册 'SIGINT' 事件监听器，则会触发 'pause' 事件。

调用监听器函数时不传递任何参数。

rl.on('SIGINT', () => {
  rl.question('Are you sure you want to exit? ', (answer) => {
    if (answer.match(/^y(es)?$/i)) rl.pause();
  });
}); copy

事件：'SIGTSTP'#

当 input 流接收到 Ctrl+Z 输入（通常称为 SIGTSTP）时，会触发 'SIGTSTP' 事件。 如果在 input 流接收到 SIGTSTP 时未注册 'SIGTSTP' 事件监听器，则 Node.js 进程将被发送到后台。

当使用 fg(1p) 恢复程序时，将触发 'pause' 和 'SIGCONT' 事件。 这些可用于恢复 input 流。

如果在进程发送到后台之前暂停了 input，则不会触发 'pause' 和 'SIGCONT' 事件。

调用监听器函数时不传递任何参数。

rl.on('SIGTSTP', () => {
  // This will override SIGTSTP and prevent the program from going to the
  // background.
  console.log('Caught SIGTSTP.');
}); copy

Windows 上不支持 'SIGTSTP' 事件。

rl.close()#

rl.close() 方法关闭 InterfaceConstructor 实例，并放弃对 input 和 output 流的控制。 调用时，将触发 'close' 事件。

调用 rl.close() 不会立即停止 InterfaceConstructor 实例触发的其他事件（包括 'line'）。

rl[Symbol.dispose]()#

rl.close() 的别名。

rl.pause()#

rl.pause() 方法暂停 input 流，允许在必要时稍后恢复。

调用 rl.pause() 不会立即暂停 InterfaceConstructor 实例触发的其他事件（包括 'line'）。

rl.prompt([preserveCursor])#

• preserveCursor <boolean> 如果为 true，则防止光标位置重置为 0。

rl.prompt() 方法将 InterfaceConstructor 实例配置的 prompt 写入 output 中的新行，以便为用户提供一个新位置来提供输入。

调用时，如果 input 流已暂停，rl.prompt() 将恢复该流。

如果使用设置为 null 或 undefined 的 output 创建了 InterfaceConstructor，则不会写入提示符。

rl.resume()#

如果 input 流已暂停，则 rl.resume() 方法会恢复该流。

rl.setPrompt(prompt)#

• prompt <string>

rl.setPrompt() 方法设置将在每次调用 rl.prompt() 时写入 output 的提示符。

rl.getPrompt()#

• 返回值: <string> 当前提示符字符串

rl.getPrompt() 方法返回 rl.prompt() 使用的当前提示符。

rl.write(data[, key])#

• data <string>
• key <Object>
  • ctrl <boolean> true 表示 Ctrl 键。
  • meta <boolean> true 表示 Meta 键。
  • shift <boolean> true 表示 Shift 键。
  • name <string> 键的名称。

rl.write() 方法会将 data 或 key 标识的键序列写入到 output。 仅当 output 是 TTY 文本终端时，才支持 key 参数。 有关键组合的列表，请参见 TTY 键绑定。

如果指定了 key，则忽略 data。

调用时，如果 input 流已暂停，则 rl.write() 将恢复该流。

如果使用将 output 设置为 null 或 undefined 创建了 InterfaceConstructor，则不会写入 data 和 key。

rl.write('Delete this!');
// Simulate Ctrl+U to delete the line written previously
rl.write(null, { ctrl: true, name: 'u' }); copy

rl.write() 方法会将数据写入 readline Interface 的 input，如同用户提供的数据一样。

rl[Symbol.asyncIterator]()#

• 返回值: <AsyncIterator>

创建一个 AsyncIterator 对象，该对象将输入流中的每一行作为字符串进行迭代。 此方法允许通过 for await...of 循环异步迭代 InterfaceConstructor 对象。

输入流中的错误不会转发。

如果循环以 break、throw 或 return 终止，则将调用 rl.close()。 换句话说，迭代 InterfaceConstructor 将始终完全消耗输入流。

性能与传统的 'line' 事件 API 不相上下。 对于对性能敏感的应用，请改用 'line'。

async function processLineByLine() {
  const rl = readline.createInterface({
    // ...
  });

  for await (const line of rl) {
    // Each line in the readline input will be successively available here as
    // `line`.
  }
} copy

readline.createInterface() 将在调用后开始消耗输入流。 在接口创建和异步迭代之间进行异步操作可能会导致错过行。

rl.line#

• <string>

节点正在处理的当前输入数据。

这可以在从 TTY 流收集输入时使用，以检索到目前为止已处理的当前值，在发出 line 事件之前。 发出 line 事件后，此属性将是一个空字符串。

请注意，如果在实例运行时修改该值，如果未同时控制 rl.cursor，则可能会产生意想不到的后果。

如果不使用 TTY 流进行输入，请使用 'line' 事件。

一个可能的用例如下

const values = ['lorem ipsum', 'dolor sit amet'];
const rl = readline.createInterface(process.stdin);
const showResults = debounce(() => {
  console.log(
    '\n',
    values.filter((val) => val.startsWith(rl.line)).join(' '),
  );
}, 300);
process.stdin.on('keypress', (c, k) => {
  showResults();
}); copy

rl.cursor#

• <number> | <undefined>

相对于 rl.line 的光标位置。

当从 TTY 流读取输入时，这将跟踪当前光标在输入字符串中的位置。 光标的位置确定了在处理输入时将修改的输入字符串的部分，以及将呈现终端插入符的列。

rl.getCursorPos()#

• 返回值: <Object>
  • rows <number> 光标当前所在的提示符的行
  • cols <number> 光标当前所在的屏幕列

返回光标相对于输入提示符 + 字符串的实际位置。 长输入（换行）字符串以及多行提示符都包含在计算中。

类: readlinePromises.Interface#

• 继承: <readline.InterfaceConstructor>

readlinePromises.Interface 类的实例使用 readlinePromises.createInterface() 方法构造。 每个实例都与单个 input Readable 流和单个 output Writable 流相关联。 output 流用于打印提示符，以提示用户在 input 流上到达并从该流读取的输入。

const answer = await rl.question('What is your favorite food? ');
console.log(`Oh, so your favorite food is ${answer}`); copy

const signal = AbortSignal.timeout(10_000);

signal.addEventListener('abort', () => {
  console.log('The food question timed out');
}, { once: true });

const answer = await rl.question('What is your favorite food? ', { signal });
console.log(`Oh, so your favorite food is ${answer}`); copy

类: readlinePromises.Readline#

readlinePromises.createInterface(options)#

• options <Object>
  • input <stream.Readable> 要监听的 Readable 流。此选项为必需。
  • output <stream.Writable> 用于将 readline 数据写入的 Writable 流。
  • completer <Function> (函数) 用于 Tab 自动完成的可选函数。
  • terminal <boolean> （布尔值）如果 input 和 output 流应被视为 TTY，并且应将 ANSI/VT100 转义码写入其中，则为 true。默认值： 在实例化时检查 output 流上的 isTTY。
  • history <string[]> (字符串数组) 历史记录行的初始列表。 仅当用户或内部 output 检查将 terminal 设置为 true 时，此选项才有意义，否则根本不会初始化历史记录缓存机制。 默认值： []。
  • historySize <number> （数字）保留的历史记录行的最大数量。 要禁用历史记录，请将此值设置为 0。 仅当用户或内部 output 检查将 terminal 设置为 true 时，此选项才有意义，否则根本不会初始化历史记录缓存机制。 默认值： 30。
  • removeHistoryDuplicates <boolean> (布尔值) 如果为 true，则当添加到历史记录列表中的新输入行与较旧的行重复时，这将从列表中删除较旧的行。 默认值： false。
  • prompt <string> （字符串）要使用的提示字符串。 默认值： '> '。
  • crlfDelay <number> （数字）如果 \r 和 \n 之间的延迟超过 crlfDelay 毫秒，则 \r 和 \n 都将被视为单独的行尾输入。 crlfDelay 将被强制转换为不小于 100 的数字。 可以将其设置为 Infinity，在这种情况下，\r 后跟 \n 将始终被视为单个换行符（这对于使用 \r\n 行分隔符读取文件可能是合理的）。 默认值： 100。
  • escapeCodeTimeout <number> （数字）readlinePromises 将等待字符的持续时间（以毫秒为单位读取模糊键序列时，该序列既可以使用到目前为止读取的输入形成完整的键序列，也可以采用其他输入来完成更长的键序列）。 默认值： 500。
  • tabSize <integer> （整数）一个制表符等于的空格数（最小值为 1）。 默认值： 8。
• 返回：<readlinePromises.Interface>

readlinePromises.createInterface() 方法创建一个新的 readlinePromises.Interface 实例。

import { createInterface } from 'node:readline/promises';
import { stdin, stdout } from 'node:process';
const rl = createInterface({
  input: stdin,
  output: stdout,
});const { createInterface } = require('node:readline/promises');
const rl = createInterface({
  input: process.stdin,
  output: process.stdout,
});copy

创建 readlinePromises.Interface 实例后，最常见的情况是监听 'line' 事件

rl.on('line', (line) => {
  console.log(`Received: ${line}`);
}); copy

如果此实例的 terminal 为 true，则如果 output 流定义了 output.columns 属性，并且在列发生更改时或何时在 output 上发出 'resize' 事件（process.stdout 在它是 TTY 时会自动执行此操作），则该流将获得最佳兼容性。

function completer(line) {
  const completions = '.help .error .exit .quit .q'.split(' ');
  const hits = completions.filter((c) => c.startsWith(line));
  // Show all completions if none found
  return [hits.length ? hits : completions, line];
} copy

async function completer(linePartial) {
  await someAsyncWork();
  return [['123'], linePartial];
} copy

类：readline.Interface#

• 继承: <readline.InterfaceConstructor>

readline.Interface 类的实例是使用 readline.createInterface() 方法构造的。 每个实例都与单个 input Readable 流和单个 output Writable 流相关联。 output 流用于打印用户输入的提示，这些提示到达并从 input 流中读取。

rl.question('What is your favorite food? ', (answer) => {
  console.log(`Oh, so your favorite food is ${answer}`);
}); copy

const ac = new AbortController();
const signal = ac.signal;

rl.question('What is your favorite food? ', { signal }, (answer) => {
  console.log(`Oh, so your favorite food is ${answer}`);
});

signal.addEventListener('abort', () => {
  console.log('The food question timed out');
}, { once: true });

setTimeout(() => ac.abort(), 10000); copy

readline.clearLine(stream, dir[, callback])#

• stream <stream.Writable>
• dir <number> （数字）
  • -1：从光标向左
  • 1：从光标向右
  • 0：整行
• callback <Function> (函数) 操作完成后调用。
• 返回：<boolean> （布尔值）如果 stream 希望调用代码在继续写入其他数据之前等待发出 'drain' 事件，则为 false；否则为 true。

readline.clearLine() 方法清除给定 TTY 流中由 dir 标识的指定方向的当前行。

readline.clearScreenDown(stream[, callback])#

• stream <stream.Writable>
• callback <Function> (函数) 操作完成后调用。
• 返回：<boolean> （布尔值）如果 stream 希望调用代码在继续写入其他数据之前等待发出 'drain' 事件，则为 false；否则为 true。

readline.clearScreenDown() 方法从光标的当前位置向下清除给定的 TTY 流。

readline.createInterface(options)#

• options <Object>
  • input <stream.Readable> 要监听的 Readable 流。此选项为必需。
  • output <stream.Writable> 用于将 readline 数据写入的 Writable 流。
  • completer <Function> (函数) 用于 Tab 自动完成的可选函数。
  • terminal <boolean> （布尔值）如果 input 和 output 流应被视为 TTY，并且应将 ANSI/VT100 转义码写入其中，则为 true。默认值： 在实例化时检查 output 流上的 isTTY。
  • history <string[]> (字符串数组) 历史记录行的初始列表。 仅当用户或内部 output 检查将 terminal 设置为 true 时，此选项才有意义，否则根本不会初始化历史记录缓存机制。 默认值： []。
  • historySize <number> （数字）保留的历史记录行的最大数量。 要禁用历史记录，请将此值设置为 0。 仅当用户或内部 output 检查将 terminal 设置为 true 时，此选项才有意义，否则根本不会初始化历史记录缓存机制。 默认值： 30。
  • removeHistoryDuplicates <boolean> (布尔值) 如果为 true，则当添加到历史记录列表中的新输入行与较旧的行重复时，这将从列表中删除较旧的行。 默认值： false。
  • prompt <string> （字符串）要使用的提示字符串。 默认值： '> '。
  • crlfDelay <number> （数字）如果 \r 和 \n 之间的延迟超过 crlfDelay 毫秒，则 \r 和 \n 都将被视为单独的行尾输入。 crlfDelay 将被强制转换为不小于 100 的数字。 可以将其设置为 Infinity，在这种情况下，\r 后跟 \n 将始终被视为单个换行符（这对于使用 \r\n 行分隔符读取文件可能是合理的）。 默认值： 100。
  • escapeCodeTimeout <number> （数字）readline 将等待字符的持续时间（以毫秒为单位读取模糊键序列时，该序列既可以使用到目前为止读取的输入形成完整的键序列，也可以采用其他输入来完成更长的键序列）。 默认值： 500。
  • tabSize <integer> （整数）一个制表符等于的空格数（最小值为 1）。 默认值： 8。
  • signal <AbortSignal> 允许使用 AbortSignal 关闭接口。 中止信号将在内部调用接口上的 close。
• 返回：<readline.Interface>

readline.createInterface() 方法创建一个新的 readline.Interface 实例。

import { createInterface } from 'node:readline';
import { stdin, stdout } from 'node:process';
const rl = createInterface({
  input: stdin,
  output: stdout,
});const { createInterface } = require('node:readline');
const rl = createInterface({
  input: process.stdin,
  output: process.stdout,
});copy

创建 readline.Interface 实例后，最常见的情况是监听 'line' 事件

rl.on('line', (line) => {
  console.log(`Received: ${line}`);
}); copy

如果此实例的 terminal 为 true，则如果 output 流定义了 output.columns 属性，并且在列发生更改时或何时在 output 上发出 'resize' 事件（process.stdout 在它是 TTY 时会自动执行此操作），则该流将获得最佳兼容性。

当使用 stdin 作为输入创建 readline.Interface 时，程序将不会终止，直到它收到一个 EOF 字符。 要在不等待用户输入的情况下退出，请调用 process.stdin.unref()。

function completer(line) {
  const completions = '.help .error .exit .quit .q'.split(' ');
  const hits = completions.filter((c) => c.startsWith(line));
  // Show all completions if none found
  return [hits.length ? hits : completions, line];
} copy

function completer(linePartial, callback) {
  callback(null, [['123'], linePartial]);
} copy

readline.cursorTo(stream, x[, y][, callback])#

• stream <stream.Writable>
• x <number>
• y <number>
• callback <Function> (函数) 操作完成后调用。
• 返回：<boolean> （布尔值）如果 stream 希望调用代码在继续写入其他数据之前等待发出 'drain' 事件，则为 false；否则为 true。

readline.cursorTo() 方法将光标移动到给定的 TTY stream 中的指定位置。

readline.moveCursor(stream, dx, dy[, callback])#

• stream <stream.Writable>
• dx <number>
• dy <number>
• callback <Function> (函数) 操作完成后调用。
• 返回：<boolean> （布尔值）如果 stream 希望调用代码在继续写入其他数据之前等待发出 'drain' 事件，则为 false；否则为 true。

readline.moveCursor() 方法将光标*相对于*它在给定的 TTY stream 中的当前位置移动。