Node.js v25.0.0 文件

immediate.hasRef()#

• 返回：<boolean>

如果為 true，Immediate 物件將保持 Node.js 事件迴圈處於活動狀態。

immediate.ref()#

• 返回: <Immediate> 對 immediate 的引用

當被呼叫時，只要 Immediate 處於活動狀態，就請求 Node.js 事件迴圈不要退出。多次呼叫 immediate.ref() 不會有任何效果。

預設情況下，所有 Immediate 物件都是“被引用”的 (ref'ed)，因此通常不需要呼叫 immediate.ref()，除非之前呼叫過 immediate.unref()。

immediate.unref()#

• 返回: <Immediate> 對 immediate 的引用

當被呼叫時，活動的 Immediate 物件將不再要求 Node.js 事件迴圈保持活動狀態。如果沒有其他活動使事件迴圈保持執行，程序可能會在 Immediate 物件的回撥函式被呼叫之前退出。多次呼叫 immediate.unref() 不會有任何效果。

immediate[Symbol.dispose]()#

取消 immediate。這類似於呼叫 clearImmediate()。

timeout.close()#

• 返回: <Timeout> 對 timeout 的引用

取消超時。

timeout.hasRef()#

• 返回：<boolean>

如果為 true，Timeout 物件將保持 Node.js 事件迴圈處於活動狀態。

timeout.ref()#

• 返回: <Timeout> 對 timeout 的引用

當被呼叫時，只要 Timeout 處於活動狀態，就請求 Node.js 事件迴圈不要退出。多次呼叫 timeout.ref() 不會有任何效果。

預設情況下，所有 Timeout 物件都是“被引用”的 (ref'ed)，因此通常不需要呼叫 timeout.ref()，除非之前呼叫過 timeout.unref()。

timeout.refresh()#

• 返回: <Timeout> 對 timeout 的引用

將定時器的開始時間設定為當前時間，並重新排程定時器，使其在先前指定的、根據當前時間調整後的持續時間後呼叫其回撥。這對於重新整理定時器而無需分配新的 JavaScript 物件很有用。

在已呼叫其回撥的定時器上使用此方法將重新啟用該定時器。

timeout.unref()#

• 返回: <Timeout> 對 timeout 的引用

當被呼叫時，活動的 Timeout 物件將不再要求 Node.js 事件迴圈保持活動狀態。如果沒有其他活動使事件迴圈保持執行，程序可能會在 Timeout 物件的回撥函式被呼叫之前退出。多次呼叫 timeout.unref() 不會有任何效果。

timeout[Symbol.toPrimitive]()#

• 返回: <integer> 一個可用於引用此 timeout 的數字

將 Timeout 強制轉換為原始值。該原始值可用於清除 Timeout。該原始值只能在建立超時的同一執行緒中使用。因此，要在 worker_threads 之間使用它，必須首先將其傳遞到正確的執行緒。這增強了與瀏覽器 setTimeout() 和 setInterval() 實現的相容性。

timeout[Symbol.dispose]()#

取消超時。

setImmediate(callback[, ...args])#

• callback <Function> 在 Node.js 事件迴圈的本次輪詢結束時要呼叫的函式
• ...args <any> 呼叫 callback 時要傳遞的可選引數。
• 返回: <Immediate> 用於 clearImmediate()

在 I/O 事件的回撥之後排程 callback 的“立即”執行。

當多次呼叫 setImmediate() 時，callback 函式會按照它們被建立的順序排隊等待執行。整個回撥佇列在每次事件迴圈迭代中都會被處理。如果在一個正在執行的回撥函式內部排隊了一個 immediate 定時器，該定時器直到下一次事件迴圈迭代時才會被觸發。

如果 callback 不是一個函式，將會丟擲 TypeError。

此方法有一個針對 promises 的自定義變體，可透過 timersPromises.setImmediate() 使用。

setInterval(callback[, delay[, ...args]])#

• callback <Function> 定時器到期時要呼叫的函式。
• delay <number> 呼叫 callback 之前要等待的毫秒數。預設值: 1。
• ...args <any> 呼叫 callback 時要傳遞的可選引數。
• 返回: <Timeout> 用於 clearInterval()

排程每隔 delay 毫秒重複執行 callback。

當 delay 大於 2147483647 或小於 1 或為 NaN 時，delay 將被設定為 1。非整數的延遲將被截斷為整數。

如果 callback 不是一個函式，將會丟擲 TypeError。

此方法有一個針對 promises 的自定義變體，可透過 timersPromises.setInterval() 使用。

setTimeout(callback[, delay[, ...args]])#

• callback <Function> 定時器到期時要呼叫的函式。
• delay <number> 呼叫 callback 之前要等待的毫秒數。預設值: 1。
• ...args <any> 呼叫 callback 時要傳遞的可選引數。
• 返回: <Timeout> 用於 clearTimeout()

在 delay 毫秒後排程一次性 callback 的執行。

callback 很可能不會在精確的 delay 毫秒後被呼叫。Node.js 不對回撥觸發的確切時間或其順序做任何保證。回撥將在儘可能接近指定時間時被呼叫。

當 delay 大於 2147483647 或小於 1 或為 NaN 時，delay 將被設定為 1。非整數的延遲將被截斷為整數。

如果 callback 不是一個函式，將會丟擲 TypeError。

此方法有一個針對 promises 的自定義變體，可透過 timersPromises.setTimeout() 使用。

clearImmediate(immediate)#

• immediate <Immediate> 一個由 setImmediate() 返回的 Immediate 物件。

取消由 setImmediate() 建立的 Immediate 物件。

clearInterval(timeout)#

• timeout <Timeout> | <string> | <number> 一個由 setInterval() 返回的 Timeout 物件，或者是該 Timeout 物件的原始值（字串或數字）。

取消由 setInterval() 建立的 Timeout 物件。

clearTimeout(timeout)#

• timeout <Timeout> | <string> | <number> 一個由 setTimeout() 返回的 Timeout 物件，或者是該 Timeout 物件的原始值（字串或數字）。

取消由 setTimeout() 建立的 Timeout 物件。

timersPromises.setTimeout([delay[, value[, options]]])#

• delay <number> 在兌現 promise 之前等待的毫秒數。預設值: 1。
• value <any> promise 被兌現時使用的值。
• options <Object>
  • ref <boolean> 設定為 false 表示已排程的 Timeout 不應要求 Node.js 事件迴圈保持活動狀態。預設值: true。
  • signal <AbortSignal> 一個可選的 AbortSignal，可用於取消已排程的 Timeout。

import {
  setTimeout,
} from 'node:timers/promises';

const res = await setTimeout(100, 'result');

console.log(res);  // Prints 'result'const {
  setTimeout,
} = require('node:timers/promises');

setTimeout(100, 'result').then((res) => {
  console.log(res);  // Prints 'result'
});copy

timersPromises.setImmediate([value[, options]])#

• value <any> promise 被兌現時使用的值。
• options <Object>
  • ref <boolean> 設定為 false 表示已排程的 Immediate 不應要求 Node.js 事件迴圈保持活動狀態。預設值: true。
  • signal <AbortSignal> 一個可選的 AbortSignal，可用於取消已排程的 Immediate。

import {
  setImmediate,
} from 'node:timers/promises';

const res = await setImmediate('result');

console.log(res);  // Prints 'result'const {
  setImmediate,
} = require('node:timers/promises');

setImmediate('result').then((res) => {
  console.log(res);  // Prints 'result'
});copy

timersPromises.setInterval([delay[, value[, options]]])#

返回一個非同步迭代器，該迭代器以 delay 毫秒的間隔生成值。如果 ref 是 true，你需要顯式或隱式地呼叫非同步迭代器的 next() 來保持事件迴圈的活動狀態。

• delay <number> 兩次迭代之間等待的毫秒數。預設值: 1。
• value <any> 迭代器返回的值。
• options <Object>
  • ref <boolean> 設定為 false 表示兩次迭代之間已排程的 Timeout 不應要求 Node.js 事件迴圈保持活動狀態。預設值: true。
  • signal <AbortSignal> 一個可選的 AbortSignal，可用於取消操作之間已排程的 Timeout。

import {
  setInterval,
} from 'node:timers/promises';

const interval = 100;
for await (const startTime of setInterval(interval, Date.now())) {
  const now = Date.now();
  console.log(now);
  if ((now - startTime) > 1000)
    break;
}
console.log(Date.now());const {
  setInterval,
} = require('node:timers/promises');
const interval = 100;

(async function() {
  for await (const startTime of setInterval(interval, Date.now())) {
    const now = Date.now();
    console.log(now);
    if ((now - startTime) > 1000)
      break;
  }
  console.log(Date.now());
})();copy

timersPromises.scheduler.wait(delay[, options])#

• delay <number> 在解析 promise 之前等待的毫秒數。
• options <Object>
  • ref <boolean> 設定為 false 表示已排程的 Timeout 不應要求 Node.js 事件迴圈保持活動狀態。預設值: true。
  • signal <AbortSignal> 一個可選的 AbortSignal，可用於取消等待。
• 返回：<Promise>

一個由 排程 API 草案規範定義的實驗性 API，該規範正在作為標準的 Web 平臺 API 進行開發。

呼叫 timersPromises.scheduler.wait(delay, options) 等同於呼叫 timersPromises.setTimeout(delay, undefined, options)。

import { scheduler } from 'node:timers/promises';

await scheduler.wait(1000); // Wait one second before continuing copy

timersPromises.scheduler.yield()#

• 返回：<Promise>

一個由 排程 API 草案規範定義的實驗性 API，該規範正在作為標準的 Web 平臺 API 進行開發。

呼叫 timersPromises.scheduler.yield() 等同於不帶引數呼叫 timersPromises.setImmediate()。