Node.js v20.18.0 文档

类：InterfaceConstructor#

¥Class: InterfaceConstructor

• 继承：<EventEmitter>

  ¥Extends: <EventEmitter>

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

¥Instances of the InterfaceConstructor class are constructed using the readlinePromises.createInterface() or readline.createInterface() method. Every instance is associated with a single input Readable stream and a single output Writable stream. The output stream is used to print prompts for user input that arrives on, and is read from, the input stream.

事件：'close'#

¥Event: 'close'

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

¥The 'close' event is emitted when one of the following occur:

• rl.close() 方法被调用，InterfaceConstructor 实例放弃了对 input 和 output 流的控制；

  ¥The rl.close() method is called and the InterfaceConstructor instance has relinquished control over the input and output streams;

• input 流接收到它的 'end' 事件；

  ¥The input stream receives its 'end' event;

• input 流接收 Ctrl+D 以表示传输结束（EOT）；

  ¥The input stream receives Ctrl+D to signal end-of-transmission (EOT);

• input 流接收 Ctrl+C 来向 SIGINT 触发信号，并且 InterfaceConstructor 实例上没有注册 'SIGINT' 事件监听器。

  ¥The input stream receives Ctrl+C to signal SIGINT and there is no 'SIGINT' event listener registered on the InterfaceConstructor instance.

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

¥The listener function is called without passing any arguments.

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

¥The InterfaceConstructor instance is finished once the 'close' event is emitted.

事件：'line'#

¥Event: 'line'

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

¥The 'line' event is emitted whenever the input stream receives an end-of-line input (\n, \r, or \r\n). This usually occurs when the user presses Enter or Return.

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

¥The 'line' event is also emitted if new data has been read from a stream and that stream ends without a final end-of-line marker.

使用包含单行接收输入的字符串调用监听器函数。

¥The listener function is called with a string containing the single line of received input.

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

事件：'history'#

¥Event: 'history'

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

¥The 'history' event is emitted whenever the history array has changed.

使用包含历史数组的数组调用监听器函数。它将反映由于 historySize 和 removeHistoryDuplicates 引起的所有更改、添加的行和删除的行。

¥The listener function is called with an array containing the history array. It will reflect all changes, added lines and removed lines due to historySize and removeHistoryDuplicates.

主要目的是允许监听器保留历史记录。监听器也可以更改历史对象。这可能有助于防止将某些行添加到历史记录中，例如密码。

¥The primary purpose is to allow a listener to persist the history. It is also possible for the listener to change the history object. This could be useful to prevent certain lines to be added to the history, like a password.

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

事件：'pause'#

¥Event: 'pause'

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

¥The 'pause' event is emitted when one of the following occur:

• input 流已暂停。

  ¥The input stream is paused.

• input 流没有暂停并接收 'SIGCONT' 事件。（参见事件 'SIGTSTP' 和 'SIGCONT'。）

  ¥The input stream is not paused and receives the 'SIGCONT' event. (See events 'SIGTSTP' and 'SIGCONT'.)

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

¥The listener function is called without passing any arguments.

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

事件：'resume'#

¥Event: 'resume'

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

¥The 'resume' event is emitted whenever the input stream is resumed.

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

¥The listener function is called without passing any arguments.

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

事件：'SIGCONT'#

¥Event: 'SIGCONT'

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

¥The 'SIGCONT' event is emitted when a Node.js process previously moved into the background using Ctrl+Z (i.e. SIGTSTP) is then brought back to the foreground using fg(1p).

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

¥If the input stream was paused before the SIGTSTP request, this event will not be emitted.

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

¥The listener function is invoked without passing any arguments.

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

Windows 不支持 'SIGCONT' 事件。

¥The 'SIGCONT' event is not supported on Windows.

事件：'SIGINT'#

¥Event: 'SIGINT'

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

¥The 'SIGINT' event is emitted whenever the input stream receives a Ctrl+C input, known typically as SIGINT. If there are no 'SIGINT' event listeners registered when the input stream receives a SIGINT, the 'pause' event will be emitted.

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

¥The listener function is invoked without passing any arguments.

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

事件：'SIGTSTP'#

¥Event: 'SIGTSTP'

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

¥The 'SIGTSTP' event is emitted when the input stream receives a Ctrl+Z input, typically known as SIGTSTP. If there are no 'SIGTSTP' event listeners registered when the input stream receives a SIGTSTP, the Node.js process will be sent to the background.

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

¥When the program is resumed using fg(1p), the 'pause' and 'SIGCONT' events will be emitted. These can be used to resume the input stream.

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

¥The 'pause' and 'SIGCONT' events will not be emitted if the input was paused before the process was sent to the background.

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

¥The listener function is invoked without passing any arguments.

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

Windows 不支持 'SIGTSTP' 事件。

¥The 'SIGTSTP' event is not supported on Windows.

rl.close()#

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

¥The rl.close() method closes the InterfaceConstructor instance and relinquishes control over the input and output streams. When called, the 'close' event will be emitted.

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

¥Calling rl.close() does not immediately stop other events (including 'line') from being emitted by the InterfaceConstructor instance.

rl.pause()#

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

¥The rl.pause() method pauses the input stream, allowing it to be resumed later if necessary.

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

¥Calling rl.pause() does not immediately pause other events (including 'line') from being emitted by the InterfaceConstructor instance.

rl.prompt([preserveCursor])#

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

  ¥preserveCursor <boolean> If true, prevents the cursor placement from being reset to 0.

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

¥The rl.prompt() method writes the InterfaceConstructor instances configured prompt to a new line in output in order to provide a user with a new location at which to provide input.

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

¥When called, rl.prompt() will resume the input stream if it has been paused.

如果 InterfaceConstructor 是在 output 设置为 null 或 undefined 的情况下创建的，则不会写入提示。

¥If the InterfaceConstructor was created with output set to null or undefined the prompt is not written.

rl.resume()#

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

¥The rl.resume() method resumes the input stream if it has been paused.

rl.setPrompt(prompt)#

• prompt <string>

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

¥The rl.setPrompt() method sets the prompt that will be written to output whenever rl.prompt() is called.

rl.getPrompt()#

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

  ¥Returns: <string> the current prompt string

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

¥The rl.getPrompt() method returns the current prompt used by rl.prompt().

rl.write(data[, key])#

• data <string>

• key <Object>

  • ctrl <boolean> true 表示 Ctrl 键。

    ¥ctrl <boolean> true to indicate the Ctrl key.

  • meta <boolean> true 表示 Meta 键。

    ¥meta <boolean> true to indicate the Meta key.

  • shift <boolean> true 表示 Shift 键。

    ¥shift <boolean> true to indicate the Shift key.

  • name <string> 键的名称。

    ¥name <string> The name of the a key.

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

¥The rl.write() method will write either data or a key sequence identified by key to the output. The key argument is supported only if output is a TTY text terminal. See TTY keybindings for a list of key combinations.

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

¥If key is specified, data is ignored.

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

¥When called, rl.write() will resume the input stream if it has been paused.

如果 InterfaceConstructor 是在 output 设置为 null 或 undefined 的情况下创建的，则不会写入 data 和 key。

¥If the InterfaceConstructor was created with output set to null or undefined the data and key are not written.

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

rl.write() 方法会将数据写入 readline Interface 的 input，就好像它是由用户提供的一样。

¥The rl.write() method will write the data to the readline Interface's input as if it were provided by the user.

rl[Symbol.asyncIterator]()#

• 返回：<AsyncIterator>

  ¥Returns: <AsyncIterator>

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

¥Create an AsyncIterator object that iterates through each line in the input stream as a string. This method allows asynchronous iteration of InterfaceConstructor objects through for await...of loops.

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

¥Errors in the input stream are not forwarded.

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

¥If the loop is terminated with break, throw, or return, rl.close() will be called. In other words, iterating over a InterfaceConstructor will always consume the input stream fully.

性能无法与传统的 'line' 事件 API 相提并论。对于性能敏感的应用，请改用 'line'。

¥Performance is not on par with the traditional 'line' event API. Use 'line' instead for performance-sensitive applications.

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`.
  }
} 拷贝

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

¥readline.createInterface() will start to consume the input stream once invoked. Having asynchronous operations between interface creation and asynchronous iteration may result in missed lines.

rl.line#

• <string>

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

¥The current input data being processed by node.

这可用于从 TTY 流中收集输入以检索迄今为止（在 line 事件触发之前）已处理的当前值。一旦触发 line 事件，则此属性将是空字符串。

¥This can be used when collecting input from a TTY stream to retrieve the current value that has been processed thus far, prior to the line event being emitted. Once the line event has been emitted, this property will be an empty string.

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

¥Be aware that modifying the value during the instance runtime may have unintended consequences if rl.cursor is not also controlled.

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

¥If not using a TTY stream for input, use the 'line' event.

一个可能的用例如下：

¥One possible use case would be as follows:

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();
}); 拷贝

rl.cursor#

• <number> | <undefined>

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

¥The cursor position relative to rl.line.

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

¥This will track where the current cursor lands in the input string, when reading input from a TTY stream. The position of cursor determines the portion of the input string that will be modified as input is processed, as well as the column where the terminal caret will be rendered.

rl.getCursorPos()#

• 返回：<Object>

  ¥Returns: <Object>

  • rows <number> 光标当前所在的提示行

    ¥rows <number> the row of the prompt the cursor currently lands on

  • cols <number> 光标当前所在的屏幕列

    ¥cols <number> the screen column the cursor currently lands on

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

¥Returns the real position of the cursor in relation to the input prompt + string. Long input (wrapping) strings, as well as multiple line prompts are included in the calculations.

Promise API#

类：readlinePromises.Interface#

¥Class: readlinePromises.Interface

• 继承：<readline.InterfaceConstructor>

  ¥Extends: <readline.InterfaceConstructor>

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

¥Instances of the readlinePromises.Interface class are constructed using the readlinePromises.createInterface() method. Every instance is associated with a single input Readable stream and a single output Writable stream. The output stream is used to print prompts for user input that arrives on, and is read from, the input stream.

rl.question(query[, options])#

• query <string> 要写入 output 的语句或查询，位于提示之前。

  ¥query <string> A statement or query to write to output, prepended to the prompt.

• options <Object>

  • signal <AbortSignal> 可选择允许使用 AbortSignal 取消 question()。

    ¥signal <AbortSignal> Optionally allows the question() to be canceled using an AbortSignal.

• 返回：<Promise> 使用用户响应 query 的输入履行的 promise。

  ¥Returns: <Promise> A promise that is fulfilled with the user's input in response to the query.

rl.question() 方法通过将 query 写入 output 来显示 query，等待在 input 上提供用户输入，然后调用 callback 函数，将提供的输入作为第一个参数传入。

¥The rl.question() method displays the query by writing it to the output, waits for user input to be provided on input, then invokes the callback function passing the provided input as the first argument.

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

¥When called, rl.question() will resume the input stream if it has been paused.

如果 readlinePromises.Interface 是在 output 设置为 null 或 undefined 的情况下创建的，则不会写入 query。

¥If the readlinePromises.Interface was created with output set to null or undefined the query is not written.

如果问题在 rl.close() 之后被调用，则它返回被拒绝的 promise。

¥If the question is called after rl.close(), it returns a rejected promise.

用法示例：

¥Example usage:

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

使用 AbortSignal 取消问题。

¥Using an AbortSignal to cancel a question.

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}`); 拷贝

类：readlinePromises.Readline#

¥Class: readlinePromises.Readline

new readlinePromises.Readline(stream[, options])#

• stream <stream.Writable> TTY 流。

  ¥stream <stream.Writable> A TTY stream.

• options <Object>

  • autoCommit <boolean> 如果是 true，则不需要调用 rl.commit()。

    ¥autoCommit <boolean> If true, no need to call rl.commit().

rl.clearLine(dir)#

• dir <integer>

  • -1：从光标向左

    ¥-1: to the left from cursor

  • 1：从光标向右

    ¥1: to the right from cursor

  • 0：整行

    ¥0: the entire line

• 返回：自身

  ¥Returns: this

rl.clearLine() 方法在待处理动作的内部列表中添加一个动作，该动作在 dir 标识的指定方向上清除关联 stream 的当前行。调用 rl.commit() 看看这个方法的效果，除非 autoCommit: true 传给了构造函数。

¥The rl.clearLine() method adds to the internal list of pending action an action that clears current line of the associated stream in a specified direction identified by dir. Call rl.commit() to see the effect of this method, unless autoCommit: true was passed to the constructor.

rl.clearScreenDown()#

• 返回：自身

  ¥Returns: this

rl.clearScreenDown() 方法向待处理动作的内部列表添加一个动作，该动作从光标向下的当前位置清除关联流。调用 rl.commit() 看看这个方法的效果，除非 autoCommit: true 传给了构造函数。

¥The rl.clearScreenDown() method adds to the internal list of pending action an action that clears the associated stream from the current position of the cursor down. Call rl.commit() to see the effect of this method, unless autoCommit: true was passed to the constructor.

rl.commit()#

• 返回：<Promise>

  ¥Returns: <Promise>

rl.commit() 方法将所有待处理的操作发送到关联的 stream 并清除待处理操作的内部列表。

¥The rl.commit() method sends all the pending actions to the associated stream and clears the internal list of pending actions.

rl.cursorTo(x[, y])#

• x <integer>

• y <integer>

• 返回：自身

  ¥Returns: this

rl.cursorTo() 方法向待处理动作的内部列表添加一个动作，该动作将光标移动到相关 stream 中指定的位置。调用 rl.commit() 看看这个方法的效果，除非 autoCommit: true 传给了构造函数。

¥The rl.cursorTo() method adds to the internal list of pending action an action that moves cursor to the specified position in the associated stream. Call rl.commit() to see the effect of this method, unless autoCommit: true was passed to the constructor.

rl.moveCursor(dx, dy)#

• dx <integer>

• dy <integer>

• 返回：自身

  ¥Returns: this

rl.moveCursor() 方法向待处理操作的内部列表添加一个操作，该操作将光标相对于关联的 stream 中的当前位置移动。调用 rl.commit() 看看这个方法的效果，除非 autoCommit: true 传给了构造函数。

¥The rl.moveCursor() method adds to the internal list of pending action an action that moves the cursor relative to its current position in the associated stream. Call rl.commit() to see the effect of this method, unless autoCommit: true was passed to the constructor.

rl.rollback()#

• 返回：自身

  ¥Returns: this

rl.rollback 方法清除内部待处理操作列表，而不将其发送到关联的 stream。

¥The rl.rollback methods clears the internal list of pending actions without sending it to the associated stream.

readlinePromises.createInterface(options)#

• options <Object>

  • input <stream.Readable> 要收听的 可读 流。此选项是必需的。

    ¥input <stream.Readable> The Readable stream to listen to. This option is required.

  • output <stream.Writable> 要写入 readline 数据的 可写 流。

    ¥output <stream.Writable> The Writable stream to write readline data to.

  • completer <Function> 可选的用于制表符自动补全的函数。

    ¥completer <Function> An optional function used for Tab autocompletion.

  • terminal <boolean> true（如果 input 和 output 流应被视为 TTY，并且写入了 ANSI/VT100 转义码）。默认值：在实例化时检查 output 流上的 isTTY。

    ¥terminal <boolean> true if the input and output streams should be treated like a TTY, and have ANSI/VT100 escape codes written to it. Default: checking isTTY on the output stream upon instantiation.

  • history <string[]> 历史行的初始列表。仅当 terminal 由用户或内部的 output 检查设置为 true 时，此选项才有意义，否则历史缓存机制根本不会初始化。默认值：[]。

    ¥history <string[]> Initial list of history lines. This option makes sense only if terminal is set to true by the user or by an internal output check, otherwise the history caching mechanism is not initialized at all. Default: [].

  • historySize <number> 保留的最大历史行数。要禁用历史记录，则将此值设置为 0。仅当 terminal 由用户或内部的 output 检查设置为 true 时，此选项才有意义，否则历史缓存机制根本不会初始化。默认值：30。

    ¥historySize <number> Maximum number of history lines retained. To disable the history set this value to 0. This option makes sense only if terminal is set to true by the user or by an internal output check, otherwise the history caching mechanism is not initialized at all. Default: 30.

  • removeHistoryDuplicates <boolean> 如果为 true，则当添加到历史列表的新输入行与旧输入行重复时，这将从列表中删除旧行。默认值：false。

    ¥removeHistoryDuplicates <boolean> If true, when a new input line added to the history list duplicates an older one, this removes the older line from the list. Default: false.

  • prompt <string> 要使用的提示字符串。默认值：'> '。

    ¥prompt <string> The prompt string to use. Default: '> '.

  • crlfDelay <number> 如果 \r 和 \n 之间的延迟超过 crlfDelay 毫秒，则 \r 和 \n 都将被视为单独的行尾输入。crlfDelay 将被强制为不小于 100 的数字。它可以设置为 Infinity，在这种情况下，\r 后跟 \n 将始终被视为单个换行符（这对于带有 \r\n 行分隔符的 读取文件 可能是合理的）。默认值：100。

    ¥crlfDelay <number> If the delay between \r and \n exceeds crlfDelay milliseconds, both \r and \n will be treated as separate end-of-line input. crlfDelay will be coerced to a number no less than 100. It can be set to Infinity, in which case \r followed by \n will always be considered a single newline (which may be reasonable for reading files with \r\n line delimiter). Default: 100.

  • escapeCodeTimeout <number> readlinePromises 将等待字符的时长（当以毫秒为单位读取不明确的键序列时，既可以使用目前读取的输入形成完整的键序列，又可以采用额外的输入来完成更长的键序列）。默认值：500。

    ¥escapeCodeTimeout <number> The duration readlinePromises will wait for a character (when reading an ambiguous key sequence in milliseconds one that can both form a complete key sequence using the input read so far and can take additional input to complete a longer key sequence). Default: 500.

  • tabSize <integer> 一个制表符等于的空格数（最小为 1）。默认值：8。

    ¥tabSize <integer> The number of spaces a tab is equal to (minimum 1). Default: 8.

• 返回：<readlinePromises.Interface>

  ¥Returns: <readlinePromises.Interface>

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

¥The readlinePromises.createInterface() method creates a new readlinePromises.Interface instance.

const readlinePromises = require('node:readline/promises');
const rl = readlinePromises.createInterface({
  input: process.stdin,
  output: process.stdout,
}); 拷贝

一旦创建了 readlinePromises.Interface 实例，则最常见的场景就是监听 'line' 事件：

¥Once the readlinePromises.Interface instance is created, the most common case is to listen for the 'line' event:

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

如果此实例的 terminal 是 true，则如果它定义了 output.columns 属性，并且如果或当列发生变化时（process.stdout 会当其是终端时自动执行此操作）在 output 上触发 'resize' 事件，则 output 流将获得最佳的兼容性。

¥If terminal is true for this instance then the output stream will get the best compatibility if it defines an output.columns property and emits a 'resize' event on the output if or when the columns ever change (process.stdout does this automatically when it is a TTY).

completer 函数的使用#

¥Use of the completer function

completer 函数将用户输入的当前行作为参数，并返回包含 2 个条目的 Array：

¥The completer function takes the current line entered by the user as an argument, and returns an Array with 2 entries:

• 使用匹配条目的 Array 补全。

  ¥An Array with matching entries for the completion.

• 用于匹配的子字符串。

  ¥The substring that was used for the matching.

例如：[[substr1, substr2, ...], originalsubstring]。

¥For instance: [[substr1, substr2, ...], originalsubstring].

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];
} 拷贝

completer 函数也可以返回 <Promise>，或者是异步的：

¥The completer function can also return a <Promise>, or be asynchronous:

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

回调接口#

¥Callback API

类：readline.Interface#

¥Class: readline.Interface

• 继承：<readline.InterfaceConstructor>

  ¥Extends: <readline.InterfaceConstructor>

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

¥Instances of the readline.Interface class are constructed using the readline.createInterface() method. Every instance is associated with a single input Readable stream and a single output Writable stream. The output stream is used to print prompts for user input that arrives on, and is read from, the input stream.

rl.question(query[, options], callback)#

• query <string> 要写入 output 的语句或查询，位于提示之前。

  ¥query <string> A statement or query to write to output, prepended to the prompt.

• options <Object>

  • signal <AbortSignal> 可选择允许使用 AbortController 取消 question()。

    ¥signal <AbortSignal> Optionally allows the question() to be canceled using an AbortController.

• callback <Function> 使用用户输入调用的回调函数以响应 query。

  ¥callback <Function> A callback function that is invoked with the user's input in response to the query.

rl.question() 方法通过将 query 写入 output 来显示 query，等待在 input 上提供用户输入，然后调用 callback 函数，将提供的输入作为第一个参数传入。

¥The rl.question() method displays the query by writing it to the output, waits for user input to be provided on input, then invokes the callback function passing the provided input as the first argument.

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

¥When called, rl.question() will resume the input stream if it has been paused.

如果 readline.Interface 是在 output 设置为 null 或 undefined 的情况下创建的，则不会写入 query。

¥If the readline.Interface was created with output set to null or undefined the query is not written.

传给 rl.question() 的 callback 函数不遵循接受 Error 对象或 null 作为第一个参数的典型模式。以提供的答案作为唯一参数调用 callback。

¥The callback function passed to rl.question() does not follow the typical pattern of accepting an Error object or null as the first argument. The callback is called with the provided answer as the only argument.

在 rl.close() 之后调用 rl.question() 会报错。

¥An error will be thrown if calling rl.question() after rl.close().

用法示例：

¥Example usage:

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

使用 AbortController 取消问题。

¥Using an AbortController to cancel a question.

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); 拷贝

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

• stream <stream.Writable>

• dir <number>

  • -1：从光标向左

    ¥-1: to the left from cursor

  • 1：从光标向右

    ¥1: to the right from cursor

  • 0：整行

    ¥0: the entire line

• callback <Function> 操作完成后调用。

  ¥callback <Function> Invoked once the operation completes.

• 返回：<boolean> false（如果 stream 希望调用代码在继续写入附加数据之前等待 'drain' 事件触发）；否则 true。

  ¥Returns: <boolean> false if stream wishes for the calling code to wait for the 'drain' event to be emitted before continuing to write additional data; otherwise true.

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

¥The readline.clearLine() method clears current line of given TTY stream in a specified direction identified by dir.

readline.clearScreenDown(stream[, callback])#

• stream <stream.Writable>

• callback <Function> 操作完成后调用。

  ¥callback <Function> Invoked once the operation completes.

• 返回：<boolean> false（如果 stream 希望调用代码在继续写入附加数据之前等待 'drain' 事件触发）；否则 true。

  ¥Returns: <boolean> false if stream wishes for the calling code to wait for the 'drain' event to be emitted before continuing to write additional data; otherwise true.

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

¥The readline.clearScreenDown() method clears the given TTY stream from the current position of the cursor down.

readline.createInterface(options)#

• options <Object>

  • input <stream.Readable> 要收听的 可读 流。此选项是必需的。

    ¥input <stream.Readable> The Readable stream to listen to. This option is required.

  • output <stream.Writable> 要写入 readline 数据的 可写 流。

    ¥output <stream.Writable> The Writable stream to write readline data to.

  • completer <Function> 可选的用于制表符自动补全的函数。

    ¥completer <Function> An optional function used for Tab autocompletion.

  • terminal <boolean> true（如果 input 和 output 流应被视为 TTY，并且写入了 ANSI/VT100 转义码）。默认值：在实例化时检查 output 流上的 isTTY。

    ¥terminal <boolean> true if the input and output streams should be treated like a TTY, and have ANSI/VT100 escape codes written to it. Default: checking isTTY on the output stream upon instantiation.

  • history <string[]> 历史行的初始列表。仅当 terminal 由用户或内部的 output 检查设置为 true 时，此选项才有意义，否则历史缓存机制根本不会初始化。默认值：[]。

    ¥history <string[]> Initial list of history lines. This option makes sense only if terminal is set to true by the user or by an internal output check, otherwise the history caching mechanism is not initialized at all. Default: [].

  • historySize <number> 保留的最大历史行数。要禁用历史记录，则将此值设置为 0。仅当 terminal 由用户或内部的 output 检查设置为 true 时，此选项才有意义，否则历史缓存机制根本不会初始化。默认值：30。

    ¥historySize <number> Maximum number of history lines retained. To disable the history set this value to 0. This option makes sense only if terminal is set to true by the user or by an internal output check, otherwise the history caching mechanism is not initialized at all. Default: 30.

  • removeHistoryDuplicates <boolean> 如果为 true，则当添加到历史列表的新输入行与旧输入行重复时，这将从列表中删除旧行。默认值：false。

    ¥removeHistoryDuplicates <boolean> If true, when a new input line added to the history list duplicates an older one, this removes the older line from the list. Default: false.

  • prompt <string> 要使用的提示字符串。默认值：'> '。

    ¥prompt <string> The prompt string to use. Default: '> '.

  • crlfDelay <number> 如果 \r 和 \n 之间的延迟超过 crlfDelay 毫秒，则 \r 和 \n 都将被视为单独的行尾输入。crlfDelay 将被强制为不小于 100 的数字。它可以设置为 Infinity，在这种情况下，\r 后跟 \n 将始终被视为单个换行符（这对于带有 \r\n 行分隔符的 读取文件 可能是合理的）。默认值：100。

    ¥crlfDelay <number> If the delay between \r and \n exceeds crlfDelay milliseconds, both \r and \n will be treated as separate end-of-line input. crlfDelay will be coerced to a number no less than 100. It can be set to Infinity, in which case \r followed by \n will always be considered a single newline (which may be reasonable for reading files with \r\n line delimiter). Default: 100.

  • escapeCodeTimeout <number> readline 将等待字符的时长（当以毫秒为单位读取不明确的键序列时，既可以使用目前读取的输入形成完整的键序列，又可以采用额外的输入来完成更长的键序列）。默认值：500。

    ¥escapeCodeTimeout <number> The duration readline will wait for a character (when reading an ambiguous key sequence in milliseconds one that can both form a complete key sequence using the input read so far and can take additional input to complete a longer key sequence). Default: 500.

  • tabSize <integer> 一个制表符等于的空格数（最小为 1）。默认值：8。

    ¥tabSize <integer> The number of spaces a tab is equal to (minimum 1). Default: 8.

  • signal <AbortSignal> 允许使用中止信号关闭接口。中止信号将在内部调用接口上的 close。

    ¥signal <AbortSignal> Allows closing the interface using an AbortSignal. Aborting the signal will internally call close on the interface.

• 返回：<readline.Interface>

  ¥Returns: <readline.Interface>

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

¥The readline.createInterface() method creates a new readline.Interface instance.

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

一旦创建了 readline.Interface 实例，则最常见的场景就是监听 'line' 事件：

¥Once the readline.Interface instance is created, the most common case is to listen for the 'line' event:

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

如果此实例的 terminal 是 true，则如果它定义了 output.columns 属性，并且如果或当列发生变化时（process.stdout 会当其是终端时自动执行此操作）在 output 上触发 'resize' 事件，则 output 流将获得最佳的兼容性。

¥If terminal is true for this instance then the output stream will get the best compatibility if it defines an output.columns property and emits a 'resize' event on the output if or when the columns ever change (process.stdout does this automatically when it is a TTY).

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

¥When creating a readline.Interface using stdin as input, the program will not terminate until it receives an EOF character. To exit without waiting for user input, call process.stdin.unref().

completer 函数的使用#

¥Use of the completer function

completer 函数将用户输入的当前行作为参数，并返回包含 2 个条目的 Array：

¥The completer function takes the current line entered by the user as an argument, and returns an Array with 2 entries:

• 使用匹配条目的 Array 补全。

  ¥An Array with matching entries for the completion.

• 用于匹配的子字符串。

  ¥The substring that was used for the matching.

例如：[[substr1, substr2, ...], originalsubstring]。

¥For instance: [[substr1, substr2, ...], originalsubstring].

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];
} 拷贝

如果 completer 函数接受两个参数，则可以异步地调用它：

¥The completer function can be called asynchronously if it accepts two arguments:

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

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

• stream <stream.Writable>

• x <number>

• y <number>

• callback <Function> 操作完成后调用。

  ¥callback <Function> Invoked once the operation completes.

• 返回：<boolean> false（如果 stream 希望调用代码在继续写入附加数据之前等待 'drain' 事件触发）；否则 true。

  ¥Returns: <boolean> false if stream wishes for the calling code to wait for the 'drain' event to be emitted before continuing to write additional data; otherwise true.

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

¥The readline.cursorTo() method moves cursor to the specified position in a given TTY stream.

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

• stream <stream.Writable>

• dx <number>

• dy <number>

• callback <Function> 操作完成后调用。

  ¥callback <Function> Invoked once the operation completes.

• 返回：<boolean> false（如果 stream 希望调用代码在继续写入附加数据之前等待 'drain' 事件触发）；否则 true。

  ¥Returns: <boolean> false if stream wishes for the calling code to wait for the 'drain' event to be emitted before continuing to write additional data; otherwise true.

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

¥The readline.moveCursor() method moves the cursor relative to its current position in a given TTY stream.

readline.emitKeypressEvents(stream[, interface])#

• stream <stream.Readable>

• interface <readline.InterfaceConstructor>

readline.emitKeypressEvents() 方法使给定的 可读 流开始触发与接收到的输入相对应的 'keypress' 事件。

¥The readline.emitKeypressEvents() method causes the given Readable stream to begin emitting 'keypress' events corresponding to received input.

可选地，interface 指定 readline.Interface 实例，当检测到复制粘贴输入时禁用自动补齐。

¥Optionally, interface specifies a readline.Interface instance for which autocompletion is disabled when copy-pasted input is detected.

如果 stream 是 TTY，则它必须处于原始模式。

¥If the stream is a TTY, then it must be in raw mode.

如果 input 是终端，则它会被其 input 上的任何逐行读取实例自动调用。关闭 readline 实例不会阻止 input 触发 'keypress' 事件。

¥This is automatically called by any readline instance on its input if the input is a terminal. Closing the readline instance does not stop the input from emitting 'keypress' events.

readline.emitKeypressEvents(process.stdin);
if (process.stdin.isTTY)
  process.stdin.setRawMode(true); 拷贝

示例：微型命令行接口#

¥Example: Tiny CLI

下面的例子说明了使用 readline.Interface 类来实现一个微型的命令行接口：

¥The following example illustrates the use of readline.Interface class to implement a small command-line interface:

const readline = require('node:readline');
const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  prompt: 'OHAI> ',
});

rl.prompt();

rl.on('line', (line) => {
  switch (line.trim()) {
    case 'hello':
      console.log('world!');
      break;
    default:
      console.log(`Say what? I might have heard '${line.trim()}'`);
      break;
  }
  rl.prompt();
}).on('close', () => {
  console.log('Have a great day!');
  process.exit(0);
}); 拷贝

示例：逐行读取文件流#

¥Example: Read file stream line-by-Line

readline 的一个常见用例是每次一行地消费输入文件。最简单的方式是利用 fs.ReadStream API 和 for await...of 循环：

¥A common use case for readline is to consume an input file one line at a time. The easiest way to do so is leveraging the fs.ReadStream API as well as a for await...of loop:

const fs = require('node:fs');
const readline = require('node:readline');

async function processLineByLine() {
  const fileStream = fs.createReadStream('input.txt');

  const rl = readline.createInterface({
    input: fileStream,
    crlfDelay: Infinity,
  });
  // Note: we use the crlfDelay option to recognize all instances of CR LF
  // ('\r\n') in input.txt as a single line break.

  for await (const line of rl) {
    // Each line in input.txt will be successively available here as `line`.
    console.log(`Line from file: ${line}`);
  }
}

processLineByLine(); 拷贝

或者，可以使用 'line' 事件：

¥Alternatively, one could use the 'line' event:

const fs = require('node:fs');
const readline = require('node:readline');

const rl = readline.createInterface({
  input: fs.createReadStream('sample.txt'),
  crlfDelay: Infinity,
});

rl.on('line', (line) => {
  console.log(`Line from file: ${line}`);
}); 拷贝

目前，for await...of 循环可能会慢一点。如果 async / await 流量和速度都必不可少，则可以应用混合方法：

¥Currently, for await...of loop can be a bit slower. If async / await flow and speed are both essential, a mixed approach can be applied:

const { once } = require('node:events');
const { createReadStream } = require('node:fs');
const { createInterface } = require('node:readline');

(async function processLineByLine() {
  try {
    const rl = createInterface({
      input: createReadStream('big-file.txt'),
      crlfDelay: Infinity,
    });

    rl.on('line', (line) => {
      // Process the line.
    });

    await once(rl, 'close');

    console.log('File processed.');
  } catch (err) {
    console.error(err);
  }
})(); 拷贝

TTY 键绑定#

¥TTY keybindings