Node.js v25.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'#

當一個 Node.js 程序先前使用 Ctrl+Z（即 SIGTSTP）移至後臺，然後使用 fg(1p) 重新帶回前臺時，會觸發 'SIGCONT' 事件。

如果在 SIGTSTP 請求之前 input 流被暫停，則不會觸發此事件。

呼叫監聽器函式時不傳遞任何引數。

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

'SIGCONT' 事件在 Windows 上不支援。

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

'SIGTSTP' 事件在 Windows 上不支援。

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() 將恢復它。

如果建立 InterfaceConstructor 時將 output 設定為 null 或 undefined，則不會寫入提示。

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() 將恢復它。

如果建立 InterfaceConstructor 時將 output 設定為 null 或 undefined，則不會寫入 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 可讀流和一個 output 可寫流相關聯。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> 要監聽的可讀流。此選項是必需的。
  • output <stream.Writable> 要寫入 readline 資料的可寫流。
  • 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。
  • signal <AbortSignal> 允許使用 AbortSignal 關閉介面。
• 返回：<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 時會自動執行此操作），則 output 流將獲得最佳相容性。

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 可讀流和一個 output 可寫流相關聯。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() 方法以 dir 標識的指定方向清除給定的 TTY 流的當前行。

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> 要監聽的可讀流。此選項是必需的。
  • output <stream.Writable> 要寫入 readline 資料的可寫流。
  • 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 時會自動執行此操作），則 output 流將獲得最佳相容性。

當使用 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 中的當前位置進行移動。