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()。