Node.js v26.0.0 說明文件

TTY#

node:tty 模組提供了 tty.ReadStream 與 tty.WriteStream 類別。在大多數情況下，不需要也不可能直接使用此模組。不過，可以透過以下方式存取：

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

當 Node.js 偵測到執行時附加了文字終端機 ("TTY")，process.stdin 預設會被初始化為 tty.ReadStream 的執行個體，而 process.stdout 與 process.stderr 預設會是 tty.WriteStream 的執行個體。判斷 Node.js 是否在 TTY 環境中執行的偏好方法是檢查 process.stdout.isTTY 屬性的值是否為 true

$ node -p -e "Boolean(process.stdout.isTTY)"
true
$ node -p -e "Boolean(process.stdout.isTTY)" | cat
false
copy

在大多數情況下，應用程式幾乎沒有理由手動建立 tty.ReadStream 和 tty.WriteStream 類別的執行個體。

類別：tty.ReadStream#

• 繼承自：<net.Socket>

代表 TTY 的可讀取端。在一般情況下，process.stdin 將是 Node.js 程序中唯一的 tty.ReadStream 執行個體，且應該沒有理由建立額外的執行個體。

readStream.isRaw#

一個 boolean 值，如果 TTY 目前設定為以原始模式 (raw device) 運作，則為 true。

程序啟動時，此標記一律為 false，即使終端機正以原始模式運作。其值將隨後續對 setRawMode 的呼叫而改變。

readStream.isTTY#

一個 boolean 值，對於 tty.ReadStream 執行個體，其值一律為 true。

readStream.setRawMode(mode)#

• mode <boolean> 如果為 true，將 tty.ReadStream 設定為原始模式運作。如果為 false，則將 tty.ReadStream 設定為預設模式運作。readStream.isRaw 屬性將會被設定為產生的模式。
• 傳回：<this> 讀取串流執行個體。

允許設定 tty.ReadStream，使其以原始模式運作。

在原始模式下，輸入始終按字元提供，不包括修飾鍵。此外，終端機對字元的所有特殊處理都會被停用，包括回顯 (echoing) 輸入字元。在此模式下，Ctrl+C 將不再觸發 SIGINT。

類別：tty.WriteStream#

• 繼承自：<net.Socket>

代表 TTY 的可寫入端。在一般情況下，process.stdout 和 process.stderr 將是 Node.js 程序建立的僅有的 tty.WriteStream 執行個體，且應該沒有理由建立額外的執行個體。

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

• fd <number> 與 TTY 關聯的檔案描述子 (file descriptor)。
• options <Object> 傳遞給父類別 net.Socket 的選項，請參閱 net.Socket 建構函式 的 options。
• 傳回：<tty.ReadStream>

為與 TTY 關聯的 fd 建立一個 ReadStream。

new tty.WriteStream(fd)#

• fd <number> 與 TTY 關聯的檔案描述子 (file descriptor)。
• 傳回：<tty.WriteStream>

為與 TTY 關聯的 fd 建立一個 WriteStream。

事件：'resize'#

每當 writeStream.columns 或 writeStream.rows 屬性發生變化時，就會觸發 'resize' 事件。呼叫接聽程式回呼時不會傳遞任何引數。

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

writeStream.clearLine(dir[, callback])#

• dir <number>
  • -1：游標以左
  • 1：游標以右
  • 0：整行
• callback <Function> 操作完成後調用。
• 回傳：<boolean> 如果串流希望呼叫端程式碼在繼續寫入額外資料前等待 'drain' 事件發出，則回傳 false；否則回傳 true。

writeStream.clearLine() 根據 dir 指定的方向清除此 WriteStream 的目前行。

writeStream.clearScreenDown([callback])#

• callback <Function> 操作完成後調用。
• 回傳：<boolean> 如果串流希望呼叫端程式碼在繼續寫入額外資料前等待 'drain' 事件發出，則回傳 false；否則回傳 true。

writeStream.clearScreenDown() 從目前游標位置向下清除此 WriteStream。

writeStream.columns#

一個 number，指定 TTY 目前擁有的欄數 (columns)。每當觸發 'resize' 事件時，此屬性就會更新。

writeStream.cursorTo(x[, y][, callback])#

• x <number>
• y <number>
• callback <Function> 操作完成後調用。
• 回傳：<boolean> 如果串流希望呼叫端程式碼在繼續寫入額外資料前等待 'drain' 事件發出，則回傳 false；否則回傳 true。

writeStream.cursorTo() 將此 WriteStream 的游標移動到指定位置。

writeStream.getColorDepth([env])#

• env <Object> 包含要檢查的環境變數的物件。這可用於模擬特定終端機的使用。 預設值： process.env。
• 回傳：<number>

傳回：

• 支援 2 色為 1，
• 支援 16 色為 4，
• 支援 256 色為 8，
• 支援 16,777,216 色為 24。

使用此方法來判斷終端機支援哪些顏色。由於終端機顏色的特性，可能會出現偽陽性或偽陰性。這取決於程序資訊與可能對所用終端機說謊的環境變數。可以傳入 env 物件來模擬特定終端機的使用。這對於檢查特定環境設定的行為很有用。

若要強制使用特定的顏色支援，請使用下列其中一種環境設定。

• 2 色：FORCE_COLOR = 0 (停用顏色)
• 16 色：FORCE_COLOR = 1
• 256 色：FORCE_COLOR = 2
• 16,777,216 色：FORCE_COLOR = 3

也可以透過使用 NO_COLOR 與 NODE_DISABLE_COLORS 環境變數來停用顏色支援。

writeStream.getWindowSize()#

• 傳回：<number[]>

writeStream.getWindowSize() 傳回與此 WriteStream 對應的 TTY 大小。陣列的格式為 [numColumns, numRows]，其中 numColumns 與 numRows 分別代表對應 TTY 的欄數與列數。

writeStream.hasColors([count][, env])#

• count <integer> 請求的顏色數量 (最小為 2)。 預設值： 16。
• env <Object> 包含要檢查的環境變數的物件。這可用於模擬特定終端機的使用。 預設值： process.env。
• 傳回：<boolean>

如果 writeStream 支援至少與 count 中提供的顏色一樣多，則傳回 true。最低支援為 2（黑白）。

這與 writeStream.getColorDepth() 中描述的偽陽性與偽陰性情況相同。

process.stdout.hasColors();
// Returns true or false depending on if `stdout` supports at least 16 colors.
process.stdout.hasColors(256);
// Returns true or false depending on if `stdout` supports at least 256 colors.
process.stdout.hasColors({ TMUX: '1' });
// Returns true.
process.stdout.hasColors(2 ** 24, { TMUX: '1' });
// Returns false (the environment setting pretends to support 2 ** 8 colors).
copy

writeStream.isTTY#

一個 boolean 值，其值一律為 true。

writeStream.moveCursor(dx, dy[, callback])#

• dx <number>
• dy <number>
• callback <Function> 操作完成後調用。
• 回傳：<boolean> 如果串流希望呼叫端程式碼在繼續寫入額外資料前等待 'drain' 事件發出，則回傳 false；否則回傳 true。

writeStream.moveCursor() 將此 WriteStream 的游標 *相對於* 其目前位置移動。

writeStream.rows#

一個 number，指定 TTY 目前擁有的列數 (rows)。每當觸發 'resize' 事件時，此屬性就會更新。

tty.isatty(fd)#

• fd <number> 數字形式的檔案描述子
• 傳回：<boolean>

如果給定的 fd 與 TTY 關聯，tty.isatty() 方法會傳回 true，否則傳回 false（包括 fd 不是非負整數的情況）。