共用方式為

Twin class

  • 參考
套件:
azure-iot-device

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

  • 標籤：金鑰/值群組只能從服務端存取
  • 所需屬性：由服務更新，並由裝置接收
  • 報告屬性：由裝置更新，並由服務接收。

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

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

Extends

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) 實例的限制。 若要變更所有 實例 的預設值，可以使用 屬性。 如果此值不是正數，則會擲回 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)

在提供的 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。 多個呼叫傳遞相同組合的 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) 實例的限制。 若要變更所有 實例 的預設值，可以使用 屬性。 如果此值不是正數，則會擲回 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)

在提供的 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。 多個呼叫傳遞相同組合的 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