Node.js v21.7.2 文件

類別：Immediate#

此物件在內部建立，並從 setImmediate() 傳回。它可以傳遞給 clearImmediate() 以取消已排程的動作。

預設情況下，當立即排程時，只要立即動作保持作用中，Node.js 事件迴圈就會持續執行。由 setImmediate() 傳回的 Immediate 物件會同時匯出 immediate.ref() 和 immediate.unref() 函式，可用來控制此預設行為。

immediate.hasRef()#

• 傳回：<boolean>

如果為 true，Immediate 物件會讓 Node.js 事件迴圈保持作用中。

immediate.ref()#

• 傳回：<Immediate> 對 immediate 的參考

呼叫時，要求 Node.js 事件迴圈在 Immediate 保持作用中時不會結束。多次呼叫 immediate.ref() 沒有作用。

預設情況下，所有 Immediate 物件都「已參考」，這表示通常不需要呼叫 immediate.ref()，除非先前已呼叫 immediate.unref()。

immediate.unref()#

• 傳回：<Immediate> 對 immediate 的參考

呼叫時，活動的 Immediate 物件不需要 Node.js 事件迴圈保持活動狀態。如果沒有其他活動讓事件迴圈繼續執行，則程序可能會在呼叫 Immediate 物件的 callback 之前結束。多次呼叫 immediate.unref() 沒有作用。

immediate[Symbol.dispose]()#

取消立即執行。這類似於呼叫 clearImmediate()。

類別：Timeout#

此物件會在內部建立，並從 setTimeout() 和 setInterval() 傳回。可以傳遞給 clearTimeout() 或 clearInterval() 以取消排定的動作。

預設情況下，當使用 setTimeout() 或 setInterval() 排定計時器時，只要計時器處於活動狀態，Node.js 事件迴圈就會持續執行。這些函式傳回的每個 Timeout 物件都匯出 timeout.ref() 和 timeout.unref() 函式，可用於控制此預設行為。

timeout.close()#

• 傳回：<Timeout> 參照 timeout

取消逾時。

timeout.hasRef()#

• 傳回：<boolean>

如果為 true，Timeout 物件會讓 Node.js 事件迴圈保持作用中。

timeout.ref()#

• 傳回：<Timeout> 參照 timeout

呼叫時，要求 Node.js 事件迴圈在 Timeout 保持作用中時不結束。多次呼叫 timeout.ref() 不會有任何效果。

預設上，所有 Timeout 物件都是「ref」，因此通常不需要呼叫 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]()#

取消逾時。

排程計時器#

Node.js 中的計時器是一種內部建構，會在特定時間後呼叫給定的函數。呼叫計時器函數的時間會根據用於建立計時器的方法以及 Node.js 事件迴圈執行的其他工作而有所不同。

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

• callback <函式> Node.js 事件迴圈 此回合結束時要呼叫的函式
• ...args <任何> 呼叫 callback 時要傳遞的選用引數。
• 傳回：<立即> 可與 clearImmediate() 搭配使用

排程在 I/O 事件的 callback 之後「立即」執行 callback。

如果多次呼叫 setImmediate()，則 callback 函式會依據建立順序排隊執行。每次事件迴圈反覆運算都會處理整個 callback 佇列。如果在執行 callback 時排程了立即計時器，則該計時器會等到下一次事件迴圈反覆運算才會觸發。

如果 callback 不是函式，則會擲回 TypeError。

此方法有一個自訂變體，可用於承諾，可透過 timersPromises.setImmediate() 使用。

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

• callback <函式> 計時器經過時要呼叫的函式。
• delay <數字> 在呼叫 callback 之前要等待的毫秒數。預設值：1。
• ...args <任何> 呼叫 callback 時要傳遞的選用引數。
• 傳回：<逾時> 可與 clearInterval() 搭配使用

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

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

如果 callback 不是函式，則會擲回 TypeError。

此方法有一個自訂的 Promise 變體，可使用 timersPromises.setInterval() 取得。

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

• callback <函式> 計時器經過時要呼叫的函式。
• delay <數字> 在呼叫 callback 之前要等待的毫秒數。預設值：1。
• ...args <任何> 呼叫 callback 時要傳遞的選用引數。
• 傳回：<Timeout>，可與 clearTimeout() 搭配使用

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

callback 很可能不會在恰好 delay 毫秒後被呼叫。Node.js 對於 callback 何時會被觸發，以及其順序，不提供任何保證。callback 將會在盡可能接近指定時間時被呼叫。

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

如果 callback 不是函式，則會擲回 TypeError。

此方法有一個自訂的 Promise 變體，可使用 timersPromises.setTimeout() 取得。

取消計時器#

setImmediate()、setInterval() 和 setTimeout() 方法各自傳回代表已排定計時器的物件。這些物件可用於取消計時器，並防止其觸發。

對於 setImmediate() 和 setTimeout() 的 Promise 變體，可以使用 AbortController 來取消計時器。當被取消時，傳回的 Promise 將會以 'AbortError' 被拒絕。

對於 setImmediate()

const { setImmediate: setImmediatePromise } = require('node:timers/promises');

const ac = new AbortController();
const signal = ac.signal;

setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('The immediate was aborted');
  });

ac.abort(); copy

對於 setTimeout()

const { setTimeout: setTimeoutPromise } = require('node:timers/promises');

const ac = new AbortController();
const signal = ac.signal;

setTimeoutPromise(1000, 'foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('The timeout was aborted');
  });

ac.abort(); copy

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 物件。

計時器 Promise API#

timers/promises API 提供另一組會傳回 Promise 物件的計時器函式。可透過 require('node:timers/promises') 存取 API。

import {
  setTimeout,
  setImmediate,
  setInterval,
} from 'timers/promises';const {
  setTimeout,
  setImmediate,
  setInterval,
} = require('node:timers/promises');copy

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

• delay <number> 在履行承諾前等待的毫秒數。預設：1。
• value <any> 履行承諾的值。
• options <Object>
  • ref <boolean> 設為 false 以表示排定的 Timeout 不需要 Node.js 事件迴圈保持作用中。預設：true。
  • signal <AbortSignal> 可用來取消排定的 Timeout 的選用 AbortSignal。

import {
  setTimeout,
} from '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> 履行承諾的值。
• options <Object>
  • ref <boolean> 設為 false 以表示排定的 Immediate 不需要 Node.js 事件迴圈保持作用中。預設：true。
  • signal <AbortSignal> 可用來取消排定的 Immediate 的選用 AbortSignal。

import {
  setImmediate,
} from '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 '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> 在解析承諾之前要等待的毫秒數。
• options <Object>
  • signal <AbortSignal> 可選的 AbortSignal，可用於取消等待。
• 傳回：<Promise>

由 Scheduling APIs 草案規範定義的實驗性 API，正在開發為標準 Web 平台 API。

呼叫 timersPromises.scheduler.wait(delay, options) 大致等於呼叫 timersPromises.setTimeout(delay, undefined, options)，但 ref 選項不受支援。

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

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

timersPromises.scheduler.yield()#

• 傳回：<Promise>

由 Scheduling APIs 草案規範定義的實驗性 API，正在開發為標準 Web 平台 API。

呼叫 timersPromises.scheduler.yield() 等於呼叫 timersPromises.setImmediate()，沒有參數。