Node.js v18.18.0 文档

类：InterfaceConstructor#

• 继承： <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'#

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

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

• rl.close() 方法被调用，InterfaceConstructor 实例放弃了对 input 和 output 流的控制；
• input 流接收到它的 'end' 事件；
• input 流接收控制键+D 触发传输结束信号 (EOT)；
• input 流接收控制键+C 向 SIGINT 触发信号，并且没有在 InterfaceConstructor 实例上注册 'SIGINT' 事件监听器。

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

英The listener function is called without passing any arguments.

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

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

事件：'line'#

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

英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'#

每当历史数组发生更改时，则会触发 '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'#

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

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

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

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

英The listener function is called without passing any arguments.

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

事件：'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'#

'SIGCONT' 事件在 Node.js 进程先前使用移动到后台时触发控制键+Z 然后使用 fg(1p) 将（即 SIGTSTP）带回前台。

英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'#

每当 input 流接收到一个Ctrl+C 输入，通常称为 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'#

'SIGTSTP' 事件在 input 流接收到控制键+Z 输入，通常称为 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。

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.question(query[, options], callback)#

• query <string> 要写入 output 的语句或查询，位于提示之前。
• options <Object>
  • signal <AbortSignal> 可选择允许使用 AbortController 取消 question()。
• callback <Function> 使用用户输入调用的回调函数以响应 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.

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

英If the InterfaceConstructor 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); 拷贝

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> 当前的提示字符串

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 表示控制键 键。
  • meta <boolean> true 表示Meta 键。
  • shift <boolean> true 表示转移 键。
  • name <string> 键的名称。

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>

创建 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>
  • rows <number> 光标当前所在的提示行
  • cols <number> 光标当前所在的屏幕列

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

英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.

Promises API#

类：readlinePromises.Interface#

• 继承： <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 的语句或查询，位于提示之前。
• options <Object>
  • signal <AbortSignal> 可选择允许使用 AbortSignal 取消 question()。
• 返回： <Promise> 使用用户响应 query 的输入履行的 promise。

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#

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

• stream <stream.Writable> TTY 流。
• options <Object>
  • autoCommit <boolean> 如果是 true，则不需要调用 rl.commit()。

rl.clearLine(dir)#

• dir <integer>
  • -1: 从光标向左
  • 1: 从光标向右
  • 0: 整行
• 返回： 自身

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()#

• 返回： 自身

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>

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>
• 返回： 自身

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>
• 返回： 自身

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()#

• 返回： 自身

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> 要收听的 可读 流。 此选项是必需的。
  • output <stream.Writable> 要写入 readline 数据的 可写 流。
  • completer <Function> 可选的用于制表符自动补全的函数。
  • terminal <boolean> 如果 input 和 output 流应该被视为终端，并且写入了 ANSI/VT100 转义码，则为 true。 默认值： 在实例化时检查 output 流上的 isTTY。
  • history <string[]> 历史行的初始列表。 仅当 terminal 由用户或内部的 output 检查设置为 true 时，此选项才有意义，否则历史缓存机制根本不会初始化。 默认值： []。
  • historySize <number> 保留的最大历史行数。 要禁用历史记录，则将此值设置为 0。 仅当 terminal 由用户或内部的 output 检查设置为 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 实例。

英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 函数的使用#

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 补全。
• 用于匹配的子字符串。

例如： [[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];
} 拷贝

回调接口#

类：readline.Interface#

• 继承： <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 的语句或查询，位于提示之前。
• options <Object>
  • signal <AbortSignal> 可选择允许使用 AbortController 取消 question()。
• callback <Function> 使用用户输入调用的回调函数以响应 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: 从光标向右
  • 0: 整行
• callback <Function> 操作完成后调用。
• 返回： <boolean> false 如果 stream 希望调用代码在继续写入额外数据之前等待 'drain' 事件触发； 否则 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> 操作完成后调用。
• 返回： <boolean> false 如果 stream 希望调用代码在继续写入额外数据之前等待 'drain' 事件触发； 否则 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> 要收听的 可读 流。 此选项是必需的。
  • output <stream.Writable> 要写入 readline 数据的 可写 流。
  • completer <Function> 可选的用于制表符自动补全的函数。
  • terminal <boolean> 如果 input 和 output 流应该被视为终端，并且写入了 ANSI/VT100 转义码，则为 true。 默认值： 在实例化时检查 output 流上的 isTTY。
  • history <string[]> 历史行的初始列表。 仅当 terminal 由用户或内部的 output 检查设置为 true 时，此选项才有意义，否则历史缓存机制根本不会初始化。 默认值： []。
  • historySize <number> 保留的最大历史行数。 要禁用历史记录，则将此值设置为 0。 仅当 terminal 由用户或内部的 output 检查设置为 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> 允许使用中止信号关闭接口。 中止信号将在内部调用接口上的 close。
• 返回： <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 函数的使用#

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 补全。
• 用于匹配的子字符串。

例如： [[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> 操作完成后调用。
• 返回： <boolean> false 如果 stream 希望调用代码在继续写入额外数据之前等待 'drain' 事件触发； 否则 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> 操作完成后调用。
• 返回： <boolean> false 如果 stream 希望调用代码在继续写入额外数据之前等待 'drain' 事件触发； 否则 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); 拷贝

示例：微型 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);
}); 拷贝

示例：逐行读取文件流#

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 键绑定#