Node.js v18.18.2 文档

类：Immediate#

该对象是内部创建的，并从setImmediate()返回。可以将其传递给clearImmediate()以取消计划的操作。

默认情况下，当立即事件被调度时，只要立即事件处于事件状态，Node.js 事件循环就会继续运行。setImmediate()返回的 Immediate对象导出 可用于控制此默认行为的 immediate.ref()和immediate.unref()函数。

immediate.hasRef()#

• 返回：<布尔值>

如果为 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]()#

取消即时。这类似于调用clearImmediate()。

类：Timeout#

该对象是内部创建的，并从setTimeout()和 setInterval()返回。可以将其传递给clearTimeout()或 clearInterval()以取消计划的操作。

默认情况下，当使用setTimeout()或 setInterval()调度计时器时，只要计时器处于事件状态，Node.js 事件循环就会继续运行。这些函数返回的每个Timeout对象都会导出可用于控制此默认行为的timeout.ref()和timeout.unref()函数。

timeout.close()#

• 返回：<Timeout>对timeout的引用

取消超时。

timeout.hasRef()#

• 返回：<布尔值>

如果为 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]()#

取消超时。

调度定时器#

Node.js 中的计时器是一个内部构造，它会在一段时间后调用给定的函数。调用计时器函数的时间会有所不同，具体取决于创建计时器所使用的方法以及 Node.js 事件循环正在执行的其他工作。

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

• callback <Function>在本轮 Node.js事件循环结束时调用的函数
• ...args <any>调用callback时传递的可选参数。
• 返回：<Immediate>与clearImmediate()一起使用

安排在 I/O 事件回调后“立即”执行callback 。

当多次调用setImmediate()时，callback函数会按照创建顺序排队等待执行。每次事件循环迭代都会处理整个回调队列。如果立即计时器从正在执行的回调内部排队，则该计时器在下一次事件循环迭代之前不会被触发。

如果callback不是函数，则会抛出TypeError 。

此方法有一个自定义的 Promise 变体，可以使用 timersPromises.setImmediate()来使用。

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

• callback <Function>计时器到时调用的函数。
• delay <number>调用callback之前等待的毫秒数 。默认值： 1。
• ...args <any>调用callback时传递的可选参数。
• 返回：<Timeout>与clearInterval()一起使用

安排每delay毫秒重复执行callback。

当delay大于2147483647或小于1时，delay将设置为1。非整数延迟被截断为整数。

如果callback不是函数，则会抛出TypeError 。

此方法有一个自定义的 Promise 变体，可以使用 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时，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 <超时> | <字符串> | <number>由setInterval()返回的Timeout对象 或Timeout对象的基元作为字符串或数字。

取消由setInterval()创建的Timeout对象。

clearTimeout(timeout)#

• timeout <超时> | <字符串> | <number>由setTimeout()返回的Timeout对象 或Timeout对象的基元作为字符串或数字。

取消由setTimeout()创建的Timeout对象。

定时器 Promise API#

timers/promises API提供了一组替代的计时器函数，它们返回Promise对象。该 API 可通过 require('node:timers/promises')访问。

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

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

• delay <number>履行 Promise 之前等待的毫秒数。默认值： 1。
• value <any>履行 Promise 的值。
• options <对象>
  • ref <boolean>设置为false以指示计划的Timeout 不应要求 Node.js 事件循环保持事件状态。 默认值： true。
  • signal <AbortSignal>可选的AbortSignal，可用于取消计划的Timeout。

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>履行 Promise 的值。
• options <对象>
  • ref <boolean>设置为false以指示计划的Immediate 不应要求 Node.js 事件循环保持事件状态。 默认值： true。
  • signal <AbortSignal>可选的AbortSignal，可用于取消计划的Immediate。

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 <对象>
  • 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>解决 Promise 之前等待的毫秒数。
• options <对象>
  • signal <AbortSignal>可选的AbortSignal，可用于取消等待。
• 返回：< Promise >

由调度 API 草案规范定义的实验性 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 >

由调度 API 草案规范定义的实验性 API，正在开发为标准 Web 平台 API。

调用timersPromises.scheduler.yield()相当于调用 不带参数的timersPromises.setImmediate() 。