共用方式為

Twin class

  • 參考
套件:
azure-iot-device

裝置對應項檔描述 Azure IoT 中樞所儲存的裝置狀態，即使裝置已離線，仍可供使用。 其建置約3個區段：

  • 標記：索引鍵/值組只能從服務端存取
  • 所需屬性：由服務更新，並由裝置接收
  • 報告屬性：由裝置更新，並由服務接收。

請注意，雖然有可能，但所需和報告的屬性不需要相符，而且視需要同步處理這兩個集合的邏輯會保留給 SDK 的使用者。

如需詳細資訊，請參閱 瞭解裝置對應項。

Extends

EventEmitter

屬性

desiredPath
errorEvent
properties

所需和報告的屬性字典分別在 和 properties.reported) 中 properties.desired (。
userRegisteredDesiredPropertiesListener

繼承的屬性

captureRejections

值： 布爾值

captureRejections變更所有新EventEmitter對象的預設選項。
captureRejectionSymbol

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

瞭解如何撰寫自訂 rejection handler。
defaultMaxListeners

根據預設，可以註冊任何單一事件的接聽程式數目上限 10 。 您可以使用 emitter.setMaxListeners(n) 方法，針對個別EventEmitter實例變更此限制。 若要變更 所有EventEmitter 實例的預設值， events.defaultMaxListeners 可以使用 屬性。 如果此值不是正數， RangeError 則會擲回 。

設定 events.defaultMaxListeners 時請小心，因為變更會影響 所有EventEmitter 實例，包括在進行變更之前建立的實例。 不過，呼叫 emitter.setMaxListeners(n) 的優先順序仍然高於 events.defaultMaxListeners。

這不是硬性限制。 實例 EventEmitter 將允許新增更多接聽程式，但會將追蹤警告輸出至 stderr，指出偵測到「可能的 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)

在提供的 signal上接abort聽事件一次。

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

傳回數位，其中列出發出器已註冊接聽程式的事件。 陣列中的值是字串或 Symbol。

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

傳回預設為 defaultMaxListeners 所設定emitter.setMaxListeners(n)之 的目前 max 接聽程式值EventEmitter。
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)

類別方法，傳回在指定 上註冊之指定 eventNameemitter之接聽程序的數目。

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, StaticEventEmitterOptions) 
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());
on<K>(string | symbol, (args: any[]) => void)

將函 listener 式加入至名為 eventName之事件的接聽程式陣列結尾。 不會進行任何檢查，以檢視 是否已 listener 新增 。 多個呼叫會傳遞和 listener 的相同組合eventName，將會導致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，或在等候時發出'error'時EventEmitter遭到拒絕。 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);
}

只有在用來等候另一個事件時events.once()，才會使用事件的特殊處理'error'。 如果使用 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)

為名為eventName的事件加入一次性listener函式。 下次觸發時 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 的相同組合eventName，將會導致listener新增和呼叫多次。

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

傳回 的 EventEmitter參考，以便鏈結呼叫。
prependOnceListener<K>(string | symbol, (args: any[]) => void)

將名為 eventName 之事件的一次性listener函式新增至接聽程式陣列的開頭。 下次觸發時 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)

從名為 eventName之事件的接聽程式陣列中移除指定的 listener 。

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

removeListener() 最多會從接聽程式陣列中移除一個接聽程序的實例。 如果任何單一接聽程式已針對指定的 eventName新增多次至接聽程式數位， removeListener() 則必須多次呼叫 ，才能移除每個實例。

一旦發出事件，在發出時附加至它的所有接聽程式都會依序呼叫。 這表示在發出 之後和最後一個接聽程序執行之前的任何 removeListener() 或 removeAllListeners() 呼叫都不會從emit()進行中移除它們。 後續事件的行為會如預期般運作。

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.reported) 中 properties.desired (。

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 。 您可以使用 emitter.setMaxListeners(n) 方法，針對個別EventEmitter實例變更此限制。 若要變更 所有EventEmitter 實例的預設值， events.defaultMaxListeners 可以使用 屬性。 如果此值不是正數， RangeError 則會擲回 。

設定 events.defaultMaxListeners 時請小心，因為變更會影響 所有EventEmitter 實例，包括在進行變更之前建立的實例。 不過，呼叫 emitter.setMaxListeners(n) 的優先順序仍然高於 events.defaultMaxListeners。

這不是硬性限制。 實例 EventEmitter 將允許新增更多接聽程式，但會將追蹤警告輸出至 stderr，指出偵測到「可能的 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)

在提供的 signal上接abort聽事件一次。

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

傳回數位，其中列出發出器已註冊接聽程式的事件。 陣列中的值是字串或 Symbol。

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

傳回預設為 defaultMaxListeners 所設定emitter.setMaxListeners(n)之 的目前 max 接聽程式值EventEmitter。

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.

類別方法，傳回在指定 上註冊之指定 eventNameemitter之接聽程序的數目。

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, StaticEventEmitterOptions) 

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

static function on(emitter: EventEmitter<DefaultEventMap>, eventName: string, options?: StaticEventEmitterOptions): AsyncIterableIterator<any>

參數

emitter

EventEmitter<DefaultEventMap>

eventName

string

正在接聽的事件名稱

options

StaticEventEmitterOptions

傳回

AsyncIterableIterator<any>

， AsyncIterator 逐一查看 eventName 所發出的事件 emitter

繼承自 EventEmitter.on

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

將函 listener 式加入至名為 eventName之事件的接聽程式陣列結尾。 不會進行任何檢查，以檢視 是否已 listener 新增 。 多個呼叫會傳遞和 listener 的相同組合eventName，將會導致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，或在等候時發出'error'時EventEmitter遭到拒絕。 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);
}

只有在用來等候另一個事件時events.once()，才會使用事件的特殊處理'error'。 如果使用 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)

為名為eventName的事件加入一次性listener函式。 下次觸發時 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 的相同組合eventName，將會導致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 之事件的一次性listener函式新增至接聽程式陣列的開頭。 下次觸發時 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)

從名為 eventName之事件的接聽程式陣列中移除指定的 listener 。

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

removeListener() 最多會從接聽程式陣列中移除一個接聽程序的實例。 如果任何單一接聽程式已針對指定的 eventName新增多次至接聽程式數位， removeListener() 則必須多次呼叫 ，才能移除每個實例。

一旦發出事件，在發出時附加至它的所有接聽程式都會依序呼叫。 這表示在發出 之後和最後一個接聽程序執行之前的任何 removeListener() 或 removeAllListeners() 呼叫都不會從emit()進行中移除它們。 後續事件的行為會如預期般運作。

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)[]

繼承自 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@138