通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Twin class

  • 参考
包:
azure-iot-device

设备孪生是描述 Azure IoT 中心存储的设备的状态的文档，即使设备处于脱机状态，也可用。 它大约构建了 3 个部分：

  • 标记：键/值对仅可从服务端访问
  • 所需属性：由服务更新并由设备接收
  • 报告的属性：由设备更新，并由服务接收。

请注意，尽管这是一种可能性，但所需属性和报告属性不必匹配，并且需要将这两个集合同步的逻辑留给 SDK 的用户。

有关详细信息，请参阅 了解设备孪生。

扩展

EventEmitter

属性

desiredPath
errorEvent
properties

所需的属性字典和报告的属性字典（分别在 properties.desired 和 properties.reported中）。
userRegisteredDesiredPropertiesListener

继承属性

captureRejections

值：布尔

更改所有新 captureRejections 对象的默认 EventEmitter 选项。
captureRejectionSymbol

值：Symbol.for('nodejs.rejection')

了解如何编写自定义 rejection handler。
defaultMaxListeners

默认情况下，可以为任何单个事件注册最多 10 侦听器。 可以使用 EventEmitter 方法更改单个 emitter.setMaxListeners(n) 实例的此限制。 若要更改 所有EventEmitter 实例的默认值，可以使用 events.defaultMaxListeners 属性。 如果此值不是正数，则会引发 RangeError。

设置 events.defaultMaxListeners 时请小心，因为更改会影响 所有EventEmitter 实例，包括更改之前创建的实例。 但是，调用 emitter.setMaxListeners(n) 仍优先于 events.defaultMaxListeners。

这不是硬性限制。 EventEmitter 实例将允许添加更多侦听器，但会输出跟踪警告，以指示检测到“可能的 EventEmitter 内存泄漏”。 对于任何单个 EventEmitter，可以使用 emitter.getMaxListeners() 和 emitter.setMaxListeners() 方法暂时避免出现此警告：

import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.setMaxListeners(emitter.getMaxListeners() + 1);
emitter.once('event', () => {
  // do stuff
  emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
});

--trace-warnings 命令行标志可用于显示此类警告的堆栈跟踪。

可以使用 process.on('warning') 检查发出的警告，并具有其他 emitter、type和 count 属性，分别引用事件发出器实例、事件的名称和附加侦听器数。 其 name 属性设置为 'MaxListenersExceededWarning'。
errorMonitor

此符号应用于安装仅监视 'error' 事件的侦听器。 在调用常规 'error' 侦听器之前调用使用此符号安装的侦听器。

发出 'error' 事件后，使用此符号安装侦听器不会更改行为。 因此，如果未安装任何常规 'error' 侦听器，该过程仍将崩溃。

方法

get()
get(Callback<Twin>)

从服务中获取整个孪生体。

继承的方法

addAbortListener(AbortSignal, (event: Event) => void)

在提供的 abort上侦听一次 signal 事件。

侦听中止信号上的 abort 事件不安全，并可能导致资源泄漏，因为另一个具有信号的第三方可以调用 e.stopImmediatePropagation()。 遗憾的是，Node.js 无法更改这一点，因为它违反了 Web 标准。 此外，原始 API 可以轻松忘记删除侦听器。

此 API 允许通过在 Node.js API 中安全地使用 AbortSignal，方法是通过侦听事件来解决这两个问题，以便 stopImmediatePropagation 不会阻止侦听器运行。

返回一个可释放项，以便它可以更轻松地取消订阅。

import { addAbortListener } from 'node:events';

function example(signal) {
  let disposable;
  try {
    signal.addEventListener('abort', (e) => e.stopImmediatePropagation());
    disposable = addAbortListener(signal, (e) => {
      // Do something when signal is aborted.
    });
  } finally {
    disposable?.[Symbol.dispose]();
  }
}
addListener<K>(string | symbol, (args: any[]) => void)

emitter.on(eventName, listener)的别名。
emit<K>(string | symbol, AnyRest)

同步调用为名为 eventName的事件注册的每个侦听器，按照注册的顺序，将提供的参数传递给每个侦听器。

如果事件具有侦听器，则返回 true，否则 false。

import { EventEmitter } from 'node:events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

console.log(myEmitter.listeners('event'));

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// [
//   [Function: firstListener],
//   [Function: secondListener],
//   [Function: thirdListener]
// ]
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
eventNames()

返回一个数组，其中列出发出器已注册侦听器的事件。 数组中的值为字符串或 Symbols。

import { EventEmitter } from 'node:events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
getEventListeners(EventEmitter<DefaultEventMap> | EventTarget, string | symbol)

返回名为 eventName的事件的侦听器数组的副本。

对于 EventEmitter，这与在发射器上调用 .listeners 的行为完全相同。

对于 EventTarget，这是获取事件目标的事件侦听器的唯一方法。 这对于调试和诊断目的非常有用。

import { getEventListeners, EventEmitter } from 'node:events';

{
  const ee = new EventEmitter();
  const listener = () => console.log('Events are fun');
  ee.on('foo', listener);
  console.log(getEventListeners(ee, 'foo')); // [ [Function: listener] ]
}
{
  const et = new EventTarget();
  const listener = () => console.log('Events are fun');
  et.addEventListener('foo', listener);
  console.log(getEventListeners(et, 'foo')); // [ [Function: listener] ]
}
getMaxListeners()

返回由 EventEmitter 设置的 emitter.setMaxListeners(n) 的当前最大侦听器值，或默认值为 defaultMaxListeners。
getMaxListeners(EventEmitter<DefaultEventMap> | EventTarget)

返回当前设置的最大侦听器量。

对于 EventEmitter，这与在发射器上调用 .getMaxListeners 的行为完全相同。

对于 EventTarget，这是获取事件目标的最大事件侦听器的唯一方法。 如果单个 EventTarget 上的事件处理程序数超过最大集，EventTarget 将输出警告。

import { getMaxListeners, setMaxListeners, EventEmitter } from 'node:events';

{
  const ee = new EventEmitter();
  console.log(getMaxListeners(ee)); // 10
  setMaxListeners(11, ee);
  console.log(getMaxListeners(ee)); // 11
}
{
  const et = new EventTarget();
  console.log(getMaxListeners(et)); // 10
  setMaxListeners(11, et);
  console.log(getMaxListeners(et)); // 11
}
listenerCount(EventEmitter<DefaultEventMap>, string | symbol)

一个类方法，返回在给定 eventName上注册的给定 emitter 的侦听器数。

import { EventEmitter, listenerCount } from 'node:events';

const myEmitter = new EventEmitter();
myEmitter.on('event', () => {});
myEmitter.on('event', () => {});
console.log(listenerCount(myEmitter, 'event'));
// Prints: 2
listenerCount<K>(string | symbol, Function)

返回侦听名为 eventName的事件的侦听器数。 如果提供了 listener，它将返回在事件的侦听器列表中找到的侦听器的次数。
listeners<K>(string | symbol)

返回名为 eventName的事件的侦听器数组的副本。

server.on('connection', (stream) => {
  console.log('someone connected!');
});
console.log(util.inspect(server.listeners('connection')));
// Prints: [ [Function] ]
off<K>(string | symbol, (args: any[]) => void)

emitter.removeListener()的别名。
on(EventEmitter<DefaultEventMap>, string | symbol, StaticEventEmitterIteratorOptions) 
import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

// Emit later on
process.nextTick(() => {
  ee.emit('foo', 'bar');
  ee.emit('foo', 42);
});

for await (const event of on(ee, 'foo')) {
  // The execution of this inner block is synchronous and it
  // processes one event at a time (even with await). Do not use
  // if concurrent execution is required.
  console.log(event); // prints ['bar'] [42]
}
// Unreachable here

返回循环访问 AsyncIterator 事件的 eventName。 如果 EventEmitter 发出 'error'，则会引发它。 退出循环时，它会删除所有侦听器。 每次迭代返回的 value 是由发出的事件参数组成的数组。

可以使用 AbortSignal 来取消等待事件：

import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ac = new AbortController();

(async () => {
  const ee = new EventEmitter();

  // Emit later on
  process.nextTick(() => {
    ee.emit('foo', 'bar');
    ee.emit('foo', 42);
  });

  for await (const event of on(ee, 'foo', { signal: ac.signal })) {
    // The execution of this inner block is synchronous and it
    // processes one event at a time (even with await). Do not use
    // if concurrent execution is required.
    console.log(event); // prints ['bar'] [42]
  }
  // Unreachable here
})();

process.nextTick(() => ac.abort());

使用 close 选项指定将结束迭代的事件名称数组：

import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

// Emit later on
process.nextTick(() => {
  ee.emit('foo', 'bar');
  ee.emit('foo', 42);
  ee.emit('close');
});

for await (const event of on(ee, 'foo', { close: ['close'] })) {
  console.log(event); // prints ['bar'] [42]
}
// the loop will exit after 'close' is emitted
console.log('done'); // prints 'done'
on(EventTarget, string, StaticEventEmitterIteratorOptions)
on<K>(string | symbol, (args: any[]) => void)

将 listener 函数添加到名为 eventName的事件的侦听器数组的末尾。 不会进行检查，以查看是否已添加 listener。 传递 eventName 和 listener 相同组合的多个调用将导致添加 listener 并多次调用。

server.on('connection', (stream) => {
  console.log('someone connected!');
});

返回对 EventEmitter的引用，以便可以链接调用。

默认情况下，以添加事件侦听器的顺序调用事件侦听器。 emitter.prependListener() 方法可用作将事件侦听器添加到侦听器数组开头的替代方法。

import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
once(EventEmitter<DefaultEventMap>, string | symbol, StaticEventEmitterOptions)

创建在 Promise 发出给定事件时或当 EventEmitter 在等待时发出 EventEmitter 时被拒绝的 'error'。 Promise 将使用发送到给定事件的所有参数的数组进行解析。

此方法是有意通用的，适用于 Web 平台 EventTarget 接口，该接口没有特殊的'error' 事件语义，并且不侦听 'error' 事件。

import { once, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

process.nextTick(() => {
  ee.emit('myevent', 42);
});

const [value] = await once(ee, 'myevent');
console.log(value);

const err = new Error('kaboom');
process.nextTick(() => {
  ee.emit('error', err);
});

try {
  await once(ee, 'myevent');
} catch (err) {
  console.error('error happened', err);
}

仅当 'error' 用于等待另一个事件时，才会使用 events.once() 事件的特殊处理。 如果 events.once() 用于等待“error' 事件本身”，则会将其视为任何其他事件，而无需特殊处理：

import { EventEmitter, once } from 'node:events';

const ee = new EventEmitter();

once(ee, 'error')
  .then(([err]) => console.log('ok', err.message))
  .catch((err) => console.error('error', err.message));

ee.emit('error', new Error('boom'));

// Prints: ok boom

可以使用 AbortSignal 取消等待事件：

import { EventEmitter, once } from 'node:events';

const ee = new EventEmitter();
const ac = new AbortController();

async function foo(emitter, event, signal) {
  try {
    await once(emitter, event, { signal });
    console.log('event emitted!');
  } catch (error) {
    if (error.name === 'AbortError') {
      console.error('Waiting for the event was canceled!');
    } else {
      console.error('There was an error', error.message);
    }
  }
}

foo(ee, 'foo', ac.signal);
ac.abort(); // Abort waiting for the event
ee.emit('foo'); // Prints: Waiting for the event was canceled!
once(EventTarget, string, StaticEventEmitterOptions)
once<K>(string | symbol, (args: any[]) => void)

为名为 的事件添加 listenereventName 函数。 下次触发 eventName 时，将删除此侦听器，然后调用。

server.once('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

返回对 EventEmitter的引用，以便可以链接调用。

默认情况下，以添加事件侦听器的顺序调用事件侦听器。 emitter.prependOnceListener() 方法可用作将事件侦听器添加到侦听器数组开头的替代方法。

import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
prependListener<K>(string | symbol, (args: any[]) => void)

将 函数添加到名为 的事件的侦听器数组的开始 。 不会进行检查，以查看是否已添加 listener。 传递 eventName 和 listener 相同组合的多个调用将导致添加 listener 并多次调用。

server.prependListener('connection', (stream) => {
  console.log('someone connected!');
});

返回对 EventEmitter的引用，以便可以链接调用。
prependOnceListener<K>(string | symbol, (args: any[]) => void)

将名为 的事件 一次性 函数添加到侦听器数组 开始 。 下次触发 eventName 时，将删除此侦听器，然后调用。

server.prependOnceListener('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

返回对 EventEmitter的引用，以便可以链接调用。
rawListeners<K>(string | symbol)

返回名为 eventName的事件的侦听器数组的副本，包括任何包装器（如由 .once()创建的包装器）。

import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.once('log', () => console.log('log once'));

// Returns a new Array with a function `onceWrapper` which has a property
// `listener` which contains the original listener bound above
const listeners = emitter.rawListeners('log');
const logFnWrapper = listeners[0];

// Logs "log once" to the console and does not unbind the `once` event
logFnWrapper.listener();

// Logs "log once" to the console and removes the listener
logFnWrapper();

emitter.on('log', () => console.log('log persistently'));
// Will return a new Array with a single function bound by `.on()` above
const newListeners = emitter.rawListeners('log');

// Logs "log persistently" twice
newListeners[0]();
emitter.emit('log');
removeAllListeners(string | symbol)

删除所有侦听器或指定 eventName的侦听器。

删除代码中的其他位置添加的侦听器是错误的做法，尤其是在由其他组件或模块（例如套接字或文件流）创建 EventEmitter 实例时。

返回对 EventEmitter的引用，以便可以链接调用。
removeListener<K>(string | symbol, (args: any[]) => void)

从名为 listener的事件的侦听器数组中删除指定的 eventName。

const callback = (stream) => {
  console.log('someone connected!');
};
server.on('connection', callback);
// ...
server.removeListener('connection', callback);

removeListener() 最多会从侦听器数组中删除侦听器的一个实例。 如果为指定的 eventName向侦听器数组添加了多次单个侦听器，则必须多次调用 removeListener() 才能删除每个实例。

发出事件后，在发出时附加到该事件的所有侦听器将按顺序调用。 这意味着在 发出和 之后，任何 或 调用 ， 最后一个侦听器完成执行不会将其从正在进行的 中删除。 后续事件的行为与预期相同。

import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A

由于侦听器是使用内部数组管理的，因此调用这将更改 删除侦听器后注册 的任何侦听器的位置索引。 这不会影响调用侦听器的顺序，但这意味着需要重新创建 emitter.listeners() 方法返回的侦听器数组的任何副本。

将单个函数添加为单个事件的处理程序多次（如以下示例所示），removeListener() 将删除最近添加的实例。 在示例中，删除 once('ping') 侦听器：

import { EventEmitter } from 'node:events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');

返回对 EventEmitter的引用，以便可以链接调用。
setMaxListeners(number)

默认情况下，如果为特定事件添加了多个 EventEmitter 侦听器，10将打印警告。 这是一个有用的默认值，可帮助查找内存泄漏。 emitter.setMaxListeners() 方法允许修改此特定 EventEmitter 实例的限制。 该值可以设置为 Infinity（或 0），以指示无限数量的侦听器。

返回对 EventEmitter的引用，以便可以链接调用。
setMaxListeners(number, (EventEmitter<DefaultEventMap> | EventTarget)[]) 
import { setMaxListeners, EventEmitter } from 'node:events';

const target = new EventTarget();
const emitter = new EventEmitter();

setMaxListeners(5, target, emitter);
[captureRejectionSymbol]<K>(Error, string | symbol, AnyRest)

属性详细信息

desiredPath 

static desiredPath: string

属性值

string

errorEvent 

static errorEvent: string

属性值

string

properties

所需的属性字典和报告的属性字典（分别在 properties.desired 和 properties.reported中）。

properties: TwinProperties

属性值

TwinProperties

userRegisteredDesiredPropertiesListener 

userRegisteredDesiredPropertiesListener: boolean

属性值

boolean

继承属性详细信息

captureRejections

值：布尔

更改所有新 captureRejections 对象的默认 EventEmitter 选项。

static captureRejections: boolean

属性值

boolean

继承自 EventEmitter.captureRejections

captureRejectionSymbol

值：Symbol.for('nodejs.rejection')

了解如何编写自定义 rejection handler。

static captureRejectionSymbol: typeof captureRejectionSymbol

属性值

typeof captureRejectionSymbol

继承自 EventEmitter.captureRejectionSymbol

defaultMaxListeners

默认情况下，可以为任何单个事件注册最多 10 侦听器。 可以使用 EventEmitter 方法更改单个 emitter.setMaxListeners(n) 实例的此限制。 若要更改 所有EventEmitter 实例的默认值，可以使用 events.defaultMaxListeners 属性。 如果此值不是正数，则会引发 RangeError。

设置 events.defaultMaxListeners 时请小心，因为更改会影响 所有EventEmitter 实例，包括更改之前创建的实例。 但是，调用 emitter.setMaxListeners(n) 仍优先于 events.defaultMaxListeners。

这不是硬性限制。 EventEmitter 实例将允许添加更多侦听器，但会输出跟踪警告，以指示检测到“可能的 EventEmitter 内存泄漏”。 对于任何单个 EventEmitter，可以使用 emitter.getMaxListeners() 和 emitter.setMaxListeners() 方法暂时避免出现此警告：

import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.setMaxListeners(emitter.getMaxListeners() + 1);
emitter.once('event', () => {
  // do stuff
  emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
});

--trace-warnings 命令行标志可用于显示此类警告的堆栈跟踪。

可以使用 process.on('warning') 检查发出的警告，并具有其他 emitter、type和 count 属性，分别引用事件发出器实例、事件的名称和附加侦听器数。 其 name 属性设置为 'MaxListenersExceededWarning'。

static defaultMaxListeners: number

属性值

number

继承自 EventEmitter.defaultMaxListeners

errorMonitor

此符号应用于安装仅监视 'error' 事件的侦听器。 在调用常规 'error' 侦听器之前调用使用此符号安装的侦听器。

发出 'error' 事件后，使用此符号安装侦听器不会更改行为。 因此，如果未安装任何常规 'error' 侦听器，该过程仍将崩溃。

static errorMonitor: typeof errorMonitor

属性值

typeof errorMonitor

继承自 EventEmitter.errorMonitor

方法详细信息

get() 

function get(): Promise<Twin>

返回

Promise<Twin>

get(Callback<Twin>)

从服务中获取整个孪生体。

function get(callback?: Callback<Twin>)

参数

callback

Callback<Twin>

如果传输无法检索孪生体，则应使用孪生体调用回的可选函数或错误。

继承的方法详细信息

addAbortListener(AbortSignal, (event: Event) => void)

在提供的 abort上侦听一次 signal 事件。

侦听中止信号上的 abort 事件不安全，并可能导致资源泄漏，因为另一个具有信号的第三方可以调用 e.stopImmediatePropagation()。 遗憾的是，Node.js 无法更改这一点，因为它违反了 Web 标准。 此外，原始 API 可以轻松忘记删除侦听器。

此 API 允许通过在 Node.js API 中安全地使用 AbortSignal，方法是通过侦听事件来解决这两个问题，以便 stopImmediatePropagation 不会阻止侦听器运行。

返回一个可释放项，以便它可以更轻松地取消订阅。

import { addAbortListener } from 'node:events';

function example(signal) {
  let disposable;
  try {
    signal.addEventListener('abort', (e) => e.stopImmediatePropagation());
    disposable = addAbortListener(signal, (e) => {
      // Do something when signal is aborted.
    });
  } finally {
    disposable?.[Symbol.dispose]();
  }
}

static function addAbortListener(signal: AbortSignal, resource: (event: Event) => void): Disposable

参数

signal

AbortSignal

resource

(event: Event) => void

返回

Disposable

一次性删除 abort 侦听器。

继承自 EventEmitter.addAbortListener

addListener<K>(string | symbol, (args: any[]) => void)

emitter.on(eventName, listener)的别名。

function addListener<K>(eventName: string | symbol, listener: (args: any[]) => void): Twin

参数

eventName

string | symbol

listener

(args: any[]) => void

返回

Twin

继承自 EventEmitter.addListener

emit<K>(string | symbol, AnyRest)

同步调用为名为 eventName的事件注册的每个侦听器，按照注册的顺序，将提供的参数传递给每个侦听器。

如果事件具有侦听器，则返回 true，否则 false。

import { EventEmitter } from 'node:events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

console.log(myEmitter.listeners('event'));

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// [
//   [Function: firstListener],
//   [Function: secondListener],
//   [Function: thirdListener]
// ]
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener

function emit<K>(eventName: string | symbol, args: AnyRest): boolean

参数

eventName

string | symbol

args

AnyRest

返回

boolean

继承自 EventEmitter.emit

eventNames()

返回一个数组，其中列出发出器已注册侦听器的事件。 数组中的值为字符串或 Symbols。

import { EventEmitter } from 'node:events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]

function eventNames(): (string | symbol)[]

返回

(string | symbol)[]

继承自 EventEmitter.eventNames

getEventListeners(EventEmitter<DefaultEventMap> | EventTarget, string | symbol)

返回名为 eventName的事件的侦听器数组的副本。

对于 EventEmitter，这与在发射器上调用 .listeners 的行为完全相同。

对于 EventTarget，这是获取事件目标的事件侦听器的唯一方法。 这对于调试和诊断目的非常有用。

import { getEventListeners, EventEmitter } from 'node:events';

{
  const ee = new EventEmitter();
  const listener = () => console.log('Events are fun');
  ee.on('foo', listener);
  console.log(getEventListeners(ee, 'foo')); // [ [Function: listener] ]
}
{
  const et = new EventTarget();
  const listener = () => console.log('Events are fun');
  et.addEventListener('foo', listener);
  console.log(getEventListeners(et, 'foo')); // [ [Function: listener] ]
}

static function getEventListeners(emitter: EventEmitter<DefaultEventMap> | EventTarget, name: string | symbol): Function[]

参数

emitter

EventEmitter<DefaultEventMap> | EventTarget

name

string | symbol

返回

Function[]

继承自 EventEmitter.getEventListeners 的

getMaxListeners()

返回由 EventEmitter 设置的 emitter.setMaxListeners(n) 的当前最大侦听器值，或默认值为 defaultMaxListeners。

function getMaxListeners(): number

返回

number

继承自 EventEmitter.getMaxListeners

getMaxListeners(EventEmitter<DefaultEventMap> | EventTarget)

返回当前设置的最大侦听器量。

对于 EventEmitter，这与在发射器上调用 .getMaxListeners 的行为完全相同。

对于 EventTarget，这是获取事件目标的最大事件侦听器的唯一方法。 如果单个 EventTarget 上的事件处理程序数超过最大集，EventTarget 将输出警告。

import { getMaxListeners, setMaxListeners, EventEmitter } from 'node:events';

{
  const ee = new EventEmitter();
  console.log(getMaxListeners(ee)); // 10
  setMaxListeners(11, ee);
  console.log(getMaxListeners(ee)); // 11
}
{
  const et = new EventTarget();
  console.log(getMaxListeners(et)); // 10
  setMaxListeners(11, et);
  console.log(getMaxListeners(et)); // 11
}

static function getMaxListeners(emitter: EventEmitter<DefaultEventMap> | EventTarget): number

参数

emitter

EventEmitter<DefaultEventMap> | EventTarget

返回

number

继承自 EventEmitter.getMaxListeners

listenerCount(EventEmitter<DefaultEventMap>, string | symbol)

警告

现已弃用此 API。

Since v3.2.0 - Use listenerCount instead.

一个类方法，返回在给定 eventName上注册的给定 emitter 的侦听器数。

import { EventEmitter, listenerCount } from 'node:events';

const myEmitter = new EventEmitter();
myEmitter.on('event', () => {});
myEmitter.on('event', () => {});
console.log(listenerCount(myEmitter, 'event'));
// Prints: 2

static function listenerCount(emitter: EventEmitter<DefaultEventMap>, eventName: string | symbol): number

参数

emitter

EventEmitter<DefaultEventMap>

要查询的发出器

eventName

string | symbol

事件名称

返回

number

继承自 EventEmitter.listenerCount

listenerCount<K>(string | symbol, Function)

返回侦听名为 eventName的事件的侦听器数。 如果提供了 listener，它将返回在事件的侦听器列表中找到的侦听器的次数。

function listenerCount<K>(eventName: string | symbol, listener?: Function): number

参数

eventName

string | symbol

正在侦听的事件的名称

listener

Function

事件处理程序函数

返回

number

继承自 EventEmitter.listenerCount

listeners<K>(string | symbol)

返回名为 eventName的事件的侦听器数组的副本。

server.on('connection', (stream) => {
  console.log('someone connected!');
});
console.log(util.inspect(server.listeners('connection')));
// Prints: [ [Function] ]

function listeners<K>(eventName: string | symbol): Function[]

参数

eventName

string | symbol

返回

Function[]

继承自 EventEmitter.listeners

off<K>(string | symbol, (args: any[]) => void)

emitter.removeListener()的别名。

function off<K>(eventName: string | symbol, listener: (args: any[]) => void): Twin

参数

eventName

string | symbol

listener

(args: any[]) => void

返回

Twin

继承自 EventEmitter.off

on(EventEmitter<DefaultEventMap>, string | symbol, StaticEventEmitterIteratorOptions) 

import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

// Emit later on
process.nextTick(() => {
  ee.emit('foo', 'bar');
  ee.emit('foo', 42);
});

for await (const event of on(ee, 'foo')) {
  // The execution of this inner block is synchronous and it
  // processes one event at a time (even with await). Do not use
  // if concurrent execution is required.
  console.log(event); // prints ['bar'] [42]
}
// Unreachable here

返回循环访问 AsyncIterator 事件的 eventName。 如果 EventEmitter 发出 'error'，则会引发它。 退出循环时，它会删除所有侦听器。 每次迭代返回的 value 是由发出的事件参数组成的数组。

可以使用 AbortSignal 来取消等待事件：

import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ac = new AbortController();

(async () => {
  const ee = new EventEmitter();

  // Emit later on
  process.nextTick(() => {
    ee.emit('foo', 'bar');
    ee.emit('foo', 42);
  });

  for await (const event of on(ee, 'foo', { signal: ac.signal })) {
    // The execution of this inner block is synchronous and it
    // processes one event at a time (even with await). Do not use
    // if concurrent execution is required.
    console.log(event); // prints ['bar'] [42]
  }
  // Unreachable here
})();

process.nextTick(() => ac.abort());

使用 close 选项指定将结束迭代的事件名称数组：

import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

// Emit later on
process.nextTick(() => {
  ee.emit('foo', 'bar');
  ee.emit('foo', 42);
  ee.emit('close');
});

for await (const event of on(ee, 'foo', { close: ['close'] })) {
  console.log(event); // prints ['bar'] [42]
}
// the loop will exit after 'close' is emitted
console.log('done'); // prints 'done'

static function on(emitter: EventEmitter<DefaultEventMap>, eventName: string | symbol, options?: StaticEventEmitterIteratorOptions): AsyncIterator<any[], any, any>

参数

emitter

EventEmitter<DefaultEventMap>

eventName

string | symbol

options

StaticEventEmitterIteratorOptions

返回

AsyncIterator<any[], any, any>

循环访问 AsyncIterator 发出的 eventName 事件的 emitter

继承自 EventEmitter.on

on(EventTarget, string, StaticEventEmitterIteratorOptions) 

static function on(emitter: EventTarget, eventName: string, options?: StaticEventEmitterIteratorOptions): AsyncIterator<any[], any, any>

参数

emitter

EventTarget

eventName

string

options

StaticEventEmitterIteratorOptions

返回

AsyncIterator<any[], any, any>

继承自 EventEmitter.on

on<K>(string | symbol, (args: any[]) => void)

将 listener 函数添加到名为 eventName的事件的侦听器数组的末尾。 不会进行检查，以查看是否已添加 listener。 传递 eventName 和 listener 相同组合的多个调用将导致添加 listener 并多次调用。

server.on('connection', (stream) => {
  console.log('someone connected!');
});

返回对 EventEmitter的引用，以便可以链接调用。

默认情况下，以添加事件侦听器的顺序调用事件侦听器。 emitter.prependListener() 方法可用作将事件侦听器添加到侦听器数组开头的替代方法。

import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a

function on<K>(eventName: string | symbol, listener: (args: any[]) => void): Twin

参数

eventName

string | symbol

事件的名称。

listener

(args: any[]) => void

回调函数

返回

Twin

继承自 EventEmitter.on

once(EventEmitter<DefaultEventMap>, string | symbol, StaticEventEmitterOptions)

创建在 Promise 发出给定事件时或当 EventEmitter 在等待时发出 EventEmitter 时被拒绝的 'error'。 Promise 将使用发送到给定事件的所有参数的数组进行解析。

此方法是有意通用的，适用于 Web 平台 EventTarget 接口，该接口没有特殊的'error' 事件语义，并且不侦听 'error' 事件。

import { once, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

process.nextTick(() => {
  ee.emit('myevent', 42);
});

const [value] = await once(ee, 'myevent');
console.log(value);

const err = new Error('kaboom');
process.nextTick(() => {
  ee.emit('error', err);
});

try {
  await once(ee, 'myevent');
} catch (err) {
  console.error('error happened', err);
}

仅当 'error' 用于等待另一个事件时，才会使用 events.once() 事件的特殊处理。 如果 events.once() 用于等待“error' 事件本身”，则会将其视为任何其他事件，而无需特殊处理：

import { EventEmitter, once } from 'node:events';

const ee = new EventEmitter();

once(ee, 'error')
  .then(([err]) => console.log('ok', err.message))
  .catch((err) => console.error('error', err.message));

ee.emit('error', new Error('boom'));

// Prints: ok boom

可以使用 AbortSignal 取消等待事件：

import { EventEmitter, once } from 'node:events';

const ee = new EventEmitter();
const ac = new AbortController();

async function foo(emitter, event, signal) {
  try {
    await once(emitter, event, { signal });
    console.log('event emitted!');
  } catch (error) {
    if (error.name === 'AbortError') {
      console.error('Waiting for the event was canceled!');
    } else {
      console.error('There was an error', error.message);
    }
  }
}

foo(ee, 'foo', ac.signal);
ac.abort(); // Abort waiting for the event
ee.emit('foo'); // Prints: Waiting for the event was canceled!

static function once(emitter: EventEmitter<DefaultEventMap>, eventName: string | symbol, options?: StaticEventEmitterOptions): Promise<any[]>

参数

emitter

EventEmitter<DefaultEventMap>

eventName

string | symbol

options

StaticEventEmitterOptions

返回

Promise<any[]>

继承自 EventEmitter.once

once(EventTarget, string, StaticEventEmitterOptions) 

static function once(emitter: EventTarget, eventName: string, options?: StaticEventEmitterOptions): Promise<any[]>

参数

emitter

EventTarget

eventName

string

options

StaticEventEmitterOptions

返回

Promise<any[]>

继承自 EventEmitter.once

once<K>(string | symbol, (args: any[]) => void)

为名为 的事件添加 listenereventName 函数。 下次触发 eventName 时，将删除此侦听器，然后调用。

server.once('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

返回对 EventEmitter的引用，以便可以链接调用。

默认情况下，以添加事件侦听器的顺序调用事件侦听器。 emitter.prependOnceListener() 方法可用作将事件侦听器添加到侦听器数组开头的替代方法。

import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a

function once<K>(eventName: string | symbol, listener: (args: any[]) => void): Twin

参数

eventName

string | symbol

事件的名称。

listener

(args: any[]) => void

回调函数

返回

Twin

继承自 EventEmitter.once

prependListener<K>(string | symbol, (args: any[]) => void)

将 函数添加到名为 的事件的侦听器数组的开始 。 不会进行检查，以查看是否已添加 listener。 传递 eventName 和 listener 相同组合的多个调用将导致添加 listener 并多次调用。

server.prependListener('connection', (stream) => {
  console.log('someone connected!');
});

返回对 EventEmitter的引用，以便可以链接调用。

function prependListener<K>(eventName: string | symbol, listener: (args: any[]) => void): Twin

参数

eventName

string | symbol

事件的名称。

listener

(args: any[]) => void

回调函数

返回

Twin

继承自 EventEmitter.prependListener

prependOnceListener<K>(string | symbol, (args: any[]) => void)

将名为 的事件 一次性 函数添加到侦听器数组 开始 。 下次触发 eventName 时，将删除此侦听器，然后调用。

server.prependOnceListener('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

返回对 EventEmitter的引用，以便可以链接调用。

function prependOnceListener<K>(eventName: string | symbol, listener: (args: any[]) => void): Twin

参数

eventName

string | symbol

事件的名称。

listener

(args: any[]) => void

回调函数

返回

Twin

继承自 EventEmitter.prependOnceListener

rawListeners<K>(string | symbol)

返回名为 eventName的事件的侦听器数组的副本，包括任何包装器（如由 .once()创建的包装器）。

import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.once('log', () => console.log('log once'));

// Returns a new Array with a function `onceWrapper` which has a property
// `listener` which contains the original listener bound above
const listeners = emitter.rawListeners('log');
const logFnWrapper = listeners[0];

// Logs "log once" to the console and does not unbind the `once` event
logFnWrapper.listener();

// Logs "log once" to the console and removes the listener
logFnWrapper();

emitter.on('log', () => console.log('log persistently'));
// Will return a new Array with a single function bound by `.on()` above
const newListeners = emitter.rawListeners('log');

// Logs "log persistently" twice
newListeners[0]();
emitter.emit('log');

function rawListeners<K>(eventName: string | symbol): Function[]

参数

eventName

string | symbol

返回

Function[]

继承自 EventEmitter.rawListeners

removeAllListeners(string | symbol)

删除所有侦听器或指定 eventName的侦听器。

删除代码中的其他位置添加的侦听器是错误的做法，尤其是在由其他组件或模块（例如套接字或文件流）创建 EventEmitter 实例时。

返回对 EventEmitter的引用，以便可以链接调用。

function removeAllListeners(eventName?: string | symbol): Twin

参数

eventName

string | symbol

返回

Twin

继承自 EventEmitter.removeAllListeners

removeListener<K>(string | symbol, (args: any[]) => void)

从名为 listener的事件的侦听器数组中删除指定的 eventName。

const callback = (stream) => {
  console.log('someone connected!');
};
server.on('connection', callback);
// ...
server.removeListener('connection', callback);

removeListener() 最多会从侦听器数组中删除侦听器的一个实例。 如果为指定的 eventName向侦听器数组添加了多次单个侦听器，则必须多次调用 removeListener() 才能删除每个实例。

发出事件后，在发出时附加到该事件的所有侦听器将按顺序调用。 这意味着在 发出和 之后，任何 或 调用 ， 最后一个侦听器完成执行不会将其从正在进行的 中删除。 后续事件的行为与预期相同。

import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A

由于侦听器是使用内部数组管理的，因此调用这将更改 删除侦听器后注册 的任何侦听器的位置索引。 这不会影响调用侦听器的顺序，但这意味着需要重新创建 emitter.listeners() 方法返回的侦听器数组的任何副本。

将单个函数添加为单个事件的处理程序多次（如以下示例所示），removeListener() 将删除最近添加的实例。 在示例中，删除 once('ping') 侦听器：

import { EventEmitter } from 'node:events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');

返回对 EventEmitter的引用，以便可以链接调用。

function removeListener<K>(eventName: string | symbol, listener: (args: any[]) => void): Twin

参数

eventName

string | symbol

listener

(args: any[]) => void

返回

Twin

继承自 EventEmitter.removeListener

setMaxListeners(number)

默认情况下，如果为特定事件添加了多个 EventEmitter 侦听器，10将打印警告。 这是一个有用的默认值，可帮助查找内存泄漏。 emitter.setMaxListeners() 方法允许修改此特定 EventEmitter 实例的限制。 该值可以设置为 Infinity（或 0），以指示无限数量的侦听器。

返回对 EventEmitter的引用，以便可以链接调用。

function setMaxListeners(n: number): Twin

参数

n

number

返回

Twin

继承自 EventEmitter.setMaxListeners

setMaxListeners(number, (EventEmitter<DefaultEventMap> | EventTarget)[]) 

import { setMaxListeners, EventEmitter } from 'node:events';

const target = new EventTarget();
const emitter = new EventEmitter();

setMaxListeners(5, target, emitter);

static function setMaxListeners(n?: number, eventTargets: (EventEmitter<DefaultEventMap> | EventTarget)[])

参数

n

number

非负数。 每个 EventTarget 事件的最大侦听器数。

eventTargets

(EventEmitter<DefaultEventMap> | EventTarget)[]

零个或多个 {EventTarget} 或 {EventEmitter} 实例。 如果未指定任何值，则 n 设置为所有新创建的 {EventTarget} 和 {EventEmitter} 对象的默认最大值。

继承自 EventEmitter.setMaxListeners

[captureRejectionSymbol]<K>(Error, string | symbol, AnyRest) 

function [captureRejectionSymbol]<K>(error: Error, event: string | symbol, args: AnyRest)

参数

error

Error

event

string | symbol

args

AnyRest

继承自 EventEmitter.__@captureRejectionSymbol@141 的