Share via

Twin class

  • Reference
Balíček:
azure-iot-device

Dvojče zařízení je dokument popisující stav zařízení, které je uložené ve službě Azure IoT Hub a je dostupné, i když je zařízení offline. Je postaven kolem 3 sekcí:

  • Značky: Páry klíč-hodnota přístupné pouze ze strany služby
  • Požadované vlastnosti: aktualizovány službou a přijaty zařízením
  • Ohlášené vlastnosti: Aktualizováno zařízením a přijímá je služba.

Mějte na paměti, že i když je to možné, požadované a hlášené vlastnosti se nemusí shodovat a že logika synchronizace těchto dvou kolekcí je v případě potřeby ponechána na uživateli sady SDK.

Další informace najdete v tématu Principy dvojčat zařízení.

Extends

EventEmitter

Vlastnosti

desiredPath
errorEvent
properties

Slovníky požadovaných a hlášených vlastností (v properties.desired a properties.reported).
userRegisteredDesiredPropertiesListener

Zděděné vlastnosti

captureRejections

Hodnota: logická hodnota

Změňte výchozí captureRejections možnost u všech nových EventEmitter objektů.
captureRejectionSymbol

Hodnota: Symbol.for('nodejs.rejection')

Podívejte se, jak napsat vlastní rejection handler.
defaultMaxListeners

Ve výchozím nastavení je možné pro libovolnou událost zaregistrovat maximálně naslouchací 10 procesy. Tento limit je možné změnit pro jednotlivé EventEmitter instance pomocí emitter.setMaxListeners(n) metody . Pokud chcete změnit výchozí nastavení pro všechnyEventEmitter instance, events.defaultMaxListeners můžete použít vlastnost . Pokud tato hodnota není kladné číslo, vyvolá se RangeError hodnota .

Při nastavování events.defaultMaxListeners hodnoty buďte opatrní, protože změna ovlivní všechnyEventEmitter instance, včetně těch vytvořených před provedením změny. Volání emitter.setMaxListeners(n) má ale stále přednost před voláním events.defaultMaxListeners.

Toto není pevný limit. Instance EventEmitter umožní přidání dalších naslouchacích procesů, ale výstupem bude výstupu upozornění trasování stderr, které bude indikovat, že byla zjištěna "možná nevracení paměti EventEmitter". EventEmitteremitter.getMaxListeners() K dočasnému zabránění tomuto upozornění můžete použít metody a 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));
});

Příznak --trace-warnings příkazového řádku lze použít k zobrazení trasování zásobníku pro taková upozornění.

Vygenerované upozornění lze zkontrolovat pomocí process.on('warning') a bude mít další emittervlastnosti , typea count odkazující na instanci emitoru událostí, název události a počet připojených naslouchacích procesů. Jeho name vlastnost je nastavená na 'MaxListenersExceededWarning'.
errorMonitor

Tento symbol se používá k instalaci naslouchacího procesu pouze pro monitorování 'error' událostí. Naslouchací procesy nainstalované pomocí tohoto symbolu se volají před zavolání běžných 'error' naslouchacích procesů.

Instalace naslouchacího procesu pomocí tohoto symbolu nezmění chování po 'error' vygenerování události. Pokud tedy není nainstalovaný žádný běžný 'error' naslouchací proces, proces se stále chybově ukončí.

Metody

get()
get(Callback<Twin>)

Získá ze služby celé dvojče.

Zděděné metody

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

Naslouchá jednou abort události na zadaném signal.

Naslouchání události při abort signálech přerušení je nebezpečné a může vést k úniku prostředků, protože jiná třetí strana se signálem může volat e.stopImmediatePropagation(). Bohužel Node.js nemůže toto nastavení změnit, protože by to porušilo webový standard. Původní rozhraní API navíc umožňuje snadno zapomenout odebrat naslouchací procesy.

Toto rozhraní API umožňuje bezpečně používat AbortSignals v rozhraních api Node.js tím, že tyto dva problémy řeší nasloucháním události tak, aby stopImmediatePropagation nezabránily spuštění naslouchacího procesu.

Vrátí jednorázové předplatné, aby bylo možné ho snadněji odhlásit z odběru.

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)

Alias pro emitter.on(eventName, listener).
emit<K>(string | symbol, AnyRest)

Synchronně volá každý z naslouchacích procesů zaregistrovaných pro událost s názvem eventNamev pořadí, v jakém byly registrovány, a předává každému z nich zadané argumenty.

Vrátí hodnotu, true pokud událost měla naslouchací procesy, false jinak.

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

Vrátí pole se seznamem událostí, pro které má emitor zaregistrované naslouchací procesy. Hodnoty v poli jsou řetězce nebo 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)

Vrátí kopii pole naslouchacích procesů pro událost s názvem eventName.

Pro EventEmitters se to chová úplně stejně jako volání .listeners na emitoru.

Pro EventTargets je to jediný způsob, jak získat naslouchací procesy událostí pro cíl události. To je užitečné pro účely ladění a diagnostiky.

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

Vrátí aktuální maximální hodnotu naslouchacího EventEmitter procesu, která je buď nastavena hodnotou emitter.setMaxListeners(n)defaultMaxListeners, nebo na hodnotu defaultMaxListeners.
getMaxListeners(EventEmitter<DefaultEventMap> | EventTarget)

Vrátí aktuálně nastavený maximální počet naslouchacích procesů.

Pro EventEmitters se to chová úplně stejně jako volání .getMaxListeners na emitoru.

Pro EventTargets je to jediný způsob, jak získat maximální počet naslouchacích procesů událostí pro cíl události. Pokud počet obslužných rutin událostí v jednom EventTarget překročí maximální sadu, EventTarget zobrazí upozornění.

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)

Metoda třídy, která vrací počet naslouchacích procesů pro dané eventName registrované na daném emitterobjektu .

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)

Vrátí počet naslouchacích procesů pro událost s názvem eventName. Pokud listener je zadaný, vrátí počet nalezených naslouchacích procesů v seznamu naslouchacích procesů události.
listeners<K>(string | symbol)

Vrátí kopii pole naslouchacích procesů pro událost s názvem 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)

Alias pro 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

Vrátí hodnotu , AsyncIterator která iteruje eventName události. Vyvolá se, pokud vygeneruje EventEmitter'error'. Při ukončení smyčky se odeberou všechny naslouchací procesy. Každá value iterace vrací pole složené z vygenerovaných argumentů události.

Pomocí parametru AbortSignal můžete zrušit čekání na události:

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 Přidá funkci na konec pole naslouchacích procesů pro událost s názvem eventName. Neprovedou se žádné kontroly, které by zjistily listener , jestli už není přidaný. Více volání předávajících stejnou kombinaci eventName a listener způsobí listener , že se bude vícenásobně přidávat a volat.

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

Vrátí odkaz na EventEmitter, aby bylo možné volání zřetězený.

Ve výchozím nastavení se naslouchací procesy událostí volají v pořadí, v jakém jsou přidány. Metodu emitter.prependListener() lze použít jako alternativu k přidání naslouchacího procesu událostí na začátek pole naslouchacích procesů.

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)

Vytvoří , Promise která je splněna, když EventEmitter vygeneruje danou událost nebo která je odmítnuta, pokud EventEmitter vygeneruje 'error' během čekání. Přeloží Promise se polem všech argumentů vygenerovaných do dané události.

Tato metoda je záměrně obecná a funguje s rozhraním EventTarget webové platformy, které nemá žádnou zvláštní'error' sémantiku událostí a nenaslouchá 'error' události.

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

Zvláštní zpracování 'error' události se používá pouze v případě, že events.once() se používá k čekání na jinou událost. Pokud events.once() se používá k čekání naerror' samotnou událost, považuje se za jakýkoli jiný druh události bez speciálního zpracování:

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

Můžete AbortSignal použít ke zrušení čekání na událost:

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)

Přidá jednorázovoulistener funkci pro událost s názvem eventName. Při příští eventName aktivaci se tento naslouchací proces odebere a pak vyvolá.

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

Vrátí odkaz na EventEmitter, aby bylo možné volání zřetězený.

Ve výchozím nastavení se naslouchací procesy událostí volají v pořadí, v jakém jsou přidány. Metodu emitter.prependOnceListener() lze použít jako alternativu k přidání naslouchacího procesu událostí na začátek pole naslouchacích procesů.

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 Přidá funkci na začátek pole naslouchacích procesů pro událost s názvem eventName. Neprovedou se žádné kontroly, které by zjistily listener , jestli už není přidaný. Více volání předávajících stejnou kombinaci eventName a listener způsobí listener , že se bude vícenásobně přidávat a volat.

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

Vrátí odkaz na EventEmitter, aby bylo možné volání zřetězený.
prependOnceListener<K>(string | symbol, (args: any[]) => void)

Přidá jednorázovoulistener funkci pro událost s názvem eventName na začátek pole naslouchacích procesů. Při příští eventName aktivaci se tento naslouchací proces odebere a pak se vyvolá.

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

Vrátí odkaz na EventEmitter, aby bylo možné volání zřetězený.
rawListeners<K>(string | symbol)

Vrátí kopii pole naslouchacích procesů pro událost s názvem eventName, včetně všech obálky (například těch, které vytvořil )..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)

Odebere všechny naslouchací procesy nebo naslouchací procesy zadaného eventNameobjektu .

Není vhodné odebrat naslouchací procesy přidané jinde v kódu, zejména v případě, že EventEmitter instanci vytvořila jiná komponenta nebo modul (např. sokety nebo datové proudy souborů).

Vrátí odkaz na EventEmitter, aby bylo možné volání zřetězený.
removeListener<K>(string | symbol, (args: any[]) => void)

Odebere zadaný listener objekt z pole naslouchacího procesu pro událost s názvem eventName.

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

removeListener() odebere z pole naslouchacího procesu maximálně jednu instanci naslouchacího procesu. Pokud byl některý jeden naslouchací proces vícekrát přidán do pole naslouchacího procesu pro zadaný eventName, musí removeListener() být volána vícekrát, aby se každá instance odebrala.

Jakmile je událost vygenerovaná, všechny naslouchací procesy, které jsou k ní v době generování připojeny, jsou volány v pořadí. To znamená, že všechna removeListener() volání nebo removeAllListeners()po vygenerování a před dokončením posledního naslouchacího procesu neodeberou probíhající.emit() Následné události se chovají podle očekávání.

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

Vzhledem k tomu, že naslouchací procesy jsou spravovány pomocí interního pole, toto volání změní indexy pozice libovolného naslouchacího procesu zaregistrovaného po odebrání naslouchacího procesu. To nebude mít vliv na pořadí, ve kterém jsou naslouchací procesy volána, ale znamená to, že všechny kopie pole naslouchacího procesu vrácené metodou emitter.listeners() bude nutné znovu vytvořit.

Pokud byla jedna funkce přidána jako obslužná rutina vícekrát pro jednu událost (jako v následujícím příkladu), removeListener() odebere se naposledy přidaná instance. V příkladu once('ping') je naslouchací proces odebrán:

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

Vrátí odkaz na EventEmitter, aby bylo možné volání zřetězený.
setMaxListeners(number)

Ve výchozím nastavení EventEmitterse upozornění zobrazí, pokud je pro určitou událost přidáno více naslouchacích 10 procesů. Toto je užitečné výchozí nastavení, které pomáhá najít nevrácenou paměť. Metoda emitter.setMaxListeners() umožňuje úpravu limitu pro tuto konkrétní EventEmitter instanci. Hodnota se dá nastavit na Infinity (nebo 0) a označit tak neomezený počet naslouchacích procesů.

Vrátí odkaz na EventEmitter, aby bylo možné volání zřetězený.
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)

Podrobnosti vlastnosti

desiredPath 

static desiredPath: string

Hodnota vlastnosti

string

errorEvent 

static errorEvent: string

Hodnota vlastnosti

string

properties

Slovníky požadovaných a hlášených vlastností (v properties.desired a properties.reported).

properties: TwinProperties

Hodnota vlastnosti

TwinProperties

userRegisteredDesiredPropertiesListener 

userRegisteredDesiredPropertiesListener: boolean

Hodnota vlastnosti

boolean

Podrobnosti zděděných vlastností

captureRejections

Hodnota: logická hodnota

Změňte výchozí captureRejections možnost u všech nových EventEmitter objektů.

static captureRejections: boolean

Hodnota vlastnosti

boolean

Zděděno z EventEmitter.captureRejections

captureRejectionSymbol

Hodnota: Symbol.for('nodejs.rejection')

Podívejte se, jak napsat vlastní rejection handler.

static captureRejectionSymbol: typeof captureRejectionSymbol

Hodnota vlastnosti

typeof captureRejectionSymbol

Zděděno z EventEmitter.captureRejectionSymbol

defaultMaxListeners

Ve výchozím nastavení je možné pro libovolnou událost zaregistrovat maximálně naslouchací 10 procesy. Tento limit je možné změnit pro jednotlivé EventEmitter instance pomocí emitter.setMaxListeners(n) metody . Pokud chcete změnit výchozí nastavení pro všechnyEventEmitter instance, events.defaultMaxListeners můžete použít vlastnost . Pokud tato hodnota není kladné číslo, vyvolá se RangeError hodnota .

Při nastavování events.defaultMaxListeners hodnoty buďte opatrní, protože změna ovlivní všechnyEventEmitter instance, včetně těch vytvořených před provedením změny. Volání emitter.setMaxListeners(n) má ale stále přednost před voláním events.defaultMaxListeners.

Toto není pevný limit. Instance EventEmitter umožní přidání dalších naslouchacích procesů, ale výstupem bude výstupu upozornění trasování stderr, které bude indikovat, že byla zjištěna "možná nevracení paměti EventEmitter". EventEmitteremitter.getMaxListeners() K dočasnému zabránění tomuto upozornění můžete použít metody a 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));
});

Příznak --trace-warnings příkazového řádku lze použít k zobrazení trasování zásobníku pro taková upozornění.

Vygenerované upozornění lze zkontrolovat pomocí process.on('warning') a bude mít další emittervlastnosti , typea count odkazující na instanci emitoru událostí, název události a počet připojených naslouchacích procesů. Jeho name vlastnost je nastavená na 'MaxListenersExceededWarning'.

static defaultMaxListeners: number

Hodnota vlastnosti

number

Zděděno z EventEmitter.defaultMaxListeners

errorMonitor

Tento symbol se používá k instalaci naslouchacího procesu pouze pro monitorování 'error' událostí. Naslouchací procesy nainstalované pomocí tohoto symbolu se volají před zavolání běžných 'error' naslouchacích procesů.

Instalace naslouchacího procesu pomocí tohoto symbolu nezmění chování po 'error' vygenerování události. Pokud tedy není nainstalovaný žádný běžný 'error' naslouchací proces, proces se stále chybově ukončí.

static errorMonitor: typeof errorMonitor

Hodnota vlastnosti

typeof errorMonitor

Zděděno z EventEmitter.errorMonitor

Podrobnosti metody

get() 

function get(): Promise<Twin>

Návraty

Promise<Twin>

get(Callback<Twin>)

Získá ze služby celé dvojče.

function get(callback?: Callback<Twin>)

Parametry

callback

Callback<Twin>

volitelná funkce, která musí být volána zpět s dvojčetem nebo chybou, pokud se přenosu nepodaří načíst dvojče.

Podrobnosti zděděných metod

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

Naslouchá jednou abort události na zadaném signal.

Naslouchání události při abort signálech přerušení je nebezpečné a může vést k úniku prostředků, protože jiná třetí strana se signálem může volat e.stopImmediatePropagation(). Bohužel Node.js nemůže toto nastavení změnit, protože by to porušilo webový standard. Původní rozhraní API navíc umožňuje snadno zapomenout odebrat naslouchací procesy.

Toto rozhraní API umožňuje bezpečně používat AbortSignals v rozhraních api Node.js tím, že tyto dva problémy řeší nasloucháním události tak, aby stopImmediatePropagation nezabránily spuštění naslouchacího procesu.

Vrátí jednorázové předplatné, aby bylo možné ho snadněji odhlásit z odběru.

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

Parametry

signal

AbortSignal

resource

(event: Event) => void

Návraty

Disposable

Jednorázové, které odebere naslouchací abort proces.

Zděděno z EventEmitter.addAbortListener

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

Alias pro emitter.on(eventName, listener).

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

Parametry

eventName

string | symbol

listener

(args: any[]) => void

Návraty

Twin

Zděděno z EventEmitter.addListener

emit<K>(string | symbol, AnyRest)

Synchronně volá každý z naslouchacích procesů zaregistrovaných pro událost s názvem eventNamev pořadí, v jakém byly registrovány, a předává každému z nich zadané argumenty.

Vrátí hodnotu, true pokud událost měla naslouchací procesy, false jinak.

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

Parametry

eventName

string | symbol

args

AnyRest

Návraty

boolean

Zděděno z EventEmitter.emit

eventNames()

Vrátí pole se seznamem událostí, pro které má emitor zaregistrované naslouchací procesy. Hodnoty v poli jsou řetězce nebo 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)[]

Návraty

(string | symbol)[]

Zděděno z EventEmitter.eventNames

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

Vrátí kopii pole naslouchacích procesů pro událost s názvem eventName.

Pro EventEmitters se to chová úplně stejně jako volání .listeners na emitoru.

Pro EventTargets je to jediný způsob, jak získat naslouchací procesy událostí pro cíl události. To je užitečné pro účely ladění a diagnostiky.

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

Parametry

emitter

EventEmitter<DefaultEventMap> | EventTarget

name

string | symbol

Návraty

Function[]

Zděděno z EventEmitter.getEventListeners

getMaxListeners()

Vrátí aktuální maximální hodnotu naslouchacího EventEmitter procesu, která je buď nastavena hodnotou emitter.setMaxListeners(n)defaultMaxListeners, nebo na hodnotu defaultMaxListeners.

function getMaxListeners(): number

Návraty

number

Zděděno z EventEmitter.getMaxListeners

getMaxListeners(EventEmitter<DefaultEventMap> | EventTarget)

Vrátí aktuálně nastavený maximální počet naslouchacích procesů.

Pro EventEmitters se to chová úplně stejně jako volání .getMaxListeners na emitoru.

Pro EventTargets je to jediný způsob, jak získat maximální počet naslouchacích procesů událostí pro cíl události. Pokud počet obslužných rutin událostí v jednom EventTarget překročí maximální sadu, EventTarget zobrazí upozornění.

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

Parametry

emitter

EventEmitter<DefaultEventMap> | EventTarget

Návraty

number

Zděděno z EventEmitter.getMaxListeners

listenerCount(EventEmitter<DefaultEventMap>, string | symbol)

Upozornění

Toto rozhraní API je teď zastaralé.

Since v3.2.0 - Use listenerCount instead.

Metoda třídy, která vrací počet naslouchacích procesů pro dané eventName registrované na daném emitterobjektu .

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

Parametry

emitter

EventEmitter<DefaultEventMap>

Emitor, který se má dotazovat

eventName

string | symbol

Název události

Návraty

number

Zděděno z EventEmitter.listenerCount

listenerCount<K>(string | symbol, Function)

Vrátí počet naslouchacích procesů pro událost s názvem eventName. Pokud listener je zadaný, vrátí počet nalezených naslouchacích procesů v seznamu naslouchacích procesů události.

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

Parametry

eventName

string | symbol

Název události, které nasloucháte

listener

Function

Funkce obslužné rutiny události

Návraty

number

Zděděno z EventEmitter.listenerCount

listeners<K>(string | symbol)

Vrátí kopii pole naslouchacích procesů pro událost s názvem 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[]

Parametry

eventName

string | symbol

Návraty

Function[]

Zděděno z EventEmitter.listeners

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

Alias pro emitter.removeListener().

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

Parametry

eventName

string | symbol

listener

(args: any[]) => void

Návraty

Twin

Zděděno z 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

Vrátí hodnotu , AsyncIterator která iteruje eventName události. Vyvolá se, pokud vygeneruje EventEmitter'error'. Při ukončení smyčky se odeberou všechny naslouchací procesy. Každá value iterace vrací pole složené z vygenerovaných argumentů události.

Pomocí parametru AbortSignal můžete zrušit čekání na události:

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>

Parametry

emitter

EventEmitter<DefaultEventMap>

eventName

string

Název události, které nasloucháte

options

StaticEventEmitterOptions

Návraty

AsyncIterableIterator<any>

An AsyncIterator , který iteruje eventName události generované emitter

Zděděno z EventEmitter.on

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

listener Přidá funkci na konec pole naslouchacích procesů pro událost s názvem eventName. Neprovedou se žádné kontroly, které by zjistily listener , jestli už není přidaný. Více volání předávajících stejnou kombinaci eventName a listener způsobí listener , že se bude vícenásobně přidávat a volat.

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

Vrátí odkaz na EventEmitter, aby bylo možné volání zřetězený.

Ve výchozím nastavení se naslouchací procesy událostí volají v pořadí, v jakém jsou přidány. Metodu emitter.prependListener() lze použít jako alternativu k přidání naslouchacího procesu událostí na začátek pole naslouchacích procesů.

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

Parametry

eventName

string | symbol

Název události.

listener

(args: any[]) => void

Funkce zpětného volání

Návraty

Twin

Zděděno z EventEmitter.on

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

Vytvoří , Promise která je splněna, když EventEmitter vygeneruje danou událost nebo která je odmítnuta, pokud EventEmitter vygeneruje 'error' během čekání. Přeloží Promise se polem všech argumentů vygenerovaných do dané události.

Tato metoda je záměrně obecná a funguje s rozhraním EventTarget webové platformy, které nemá žádnou zvláštní'error' sémantiku událostí a nenaslouchá 'error' události.

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

Zvláštní zpracování 'error' události se používá pouze v případě, že events.once() se používá k čekání na jinou událost. Pokud events.once() se používá k čekání naerror' samotnou událost, považuje se za jakýkoli jiný druh události bez speciálního zpracování:

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

Můžete AbortSignal použít ke zrušení čekání na událost:

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

Parametry

emitter

EventEmitter<DefaultEventMap>

eventName

string | symbol

options

StaticEventEmitterOptions

Návraty

Promise<any[]>

Zděděno z EventEmitter.once

once(EventTarget, string, StaticEventEmitterOptions) 

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

Parametry

emitter

EventTarget

eventName

string

options

StaticEventEmitterOptions

Návraty

Promise<any[]>

Zděděno z EventEmitter.once

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

Přidá jednorázovoulistener funkci pro událost s názvem eventName. Při příští eventName aktivaci se tento naslouchací proces odebere a pak vyvolá.

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

Vrátí odkaz na EventEmitter, aby bylo možné volání zřetězený.

Ve výchozím nastavení se naslouchací procesy událostí volají v pořadí, v jakém jsou přidány. Metodu emitter.prependOnceListener() lze použít jako alternativu k přidání naslouchacího procesu událostí na začátek pole naslouchacích procesů.

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

Parametry

eventName

string | symbol

Název události.

listener

(args: any[]) => void

Funkce zpětného volání

Návraty

Twin

Zděděno z EventEmitter.once

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

listener Přidá funkci na začátek pole naslouchacích procesů pro událost s názvem eventName. Neprovedou se žádné kontroly, které by zjistily listener , jestli už není přidaný. Více volání předávajících stejnou kombinaci eventName a listener způsobí listener , že se bude vícenásobně přidávat a volat.

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

Vrátí odkaz na EventEmitter, aby bylo možné volání zřetězený.

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

Parametry

eventName

string | symbol

Název události.

listener

(args: any[]) => void

Funkce zpětného volání

Návraty

Twin

Zděděno z EventEmitter.prependListener

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

Přidá jednorázovoulistener funkci pro událost s názvem eventName na začátek pole naslouchacích procesů. Při příští eventName aktivaci se tento naslouchací proces odebere a pak se vyvolá.

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

Vrátí odkaz na EventEmitter, aby bylo možné volání zřetězený.

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

Parametry

eventName

string | symbol

Název události.

listener

(args: any[]) => void

Funkce zpětného volání

Návraty

Twin

Zděděno z EventEmitter.prependOnceListener

rawListeners<K>(string | symbol)

Vrátí kopii pole naslouchacích procesů pro událost s názvem eventName, včetně všech obálky (například těch, které vytvořil )..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[]

Parametry

eventName

string | symbol

Návraty

Function[]

Zděděno z EventEmitter.rawListeners

removeAllListeners(string | symbol)

Odebere všechny naslouchací procesy nebo naslouchací procesy zadaného eventNameobjektu .

Není vhodné odebrat naslouchací procesy přidané jinde v kódu, zejména v případě, že EventEmitter instanci vytvořila jiná komponenta nebo modul (např. sokety nebo datové proudy souborů).

Vrátí odkaz na EventEmitter, aby bylo možné volání zřetězený.

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

Parametry

eventName

string | symbol

Návraty

Twin

Zděděno z EventEmitter.removeAllListeners

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

Odebere zadaný listener objekt z pole naslouchacího procesu pro událost s názvem eventName.

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

removeListener() odebere z pole naslouchacího procesu maximálně jednu instanci naslouchacího procesu. Pokud byl některý jeden naslouchací proces vícekrát přidán do pole naslouchacího procesu pro zadaný eventName, musí removeListener() být volána vícekrát, aby se každá instance odebrala.

Jakmile je událost vygenerovaná, všechny naslouchací procesy, které jsou k ní v době generování připojeny, jsou volány v pořadí. To znamená, že všechna removeListener() volání nebo removeAllListeners()po vygenerování a před dokončením posledního naslouchacího procesu neodeberou probíhající.emit() Následné události se chovají podle očekávání.

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

Vzhledem k tomu, že naslouchací procesy jsou spravovány pomocí interního pole, toto volání změní indexy pozice libovolného naslouchacího procesu zaregistrovaného po odebrání naslouchacího procesu. To nebude mít vliv na pořadí, ve kterém jsou naslouchací procesy volána, ale znamená to, že všechny kopie pole naslouchacího procesu vrácené metodou emitter.listeners() bude nutné znovu vytvořit.

Pokud byla jedna funkce přidána jako obslužná rutina vícekrát pro jednu událost (jako v následujícím příkladu), removeListener() odebere se naposledy přidaná instance. V příkladu once('ping') je naslouchací proces odebrán:

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

Vrátí odkaz na EventEmitter, aby bylo možné volání zřetězený.

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

Parametry

eventName

string | symbol

listener

(args: any[]) => void

Návraty

Twin

Zděděno z EventEmitter.removeListener

setMaxListeners(number)

Ve výchozím nastavení EventEmitterse upozornění zobrazí, pokud je pro určitou událost přidáno více naslouchacích 10 procesů. Toto je užitečné výchozí nastavení, které pomáhá najít nevrácenou paměť. Metoda emitter.setMaxListeners() umožňuje úpravu limitu pro tuto konkrétní EventEmitter instanci. Hodnota se dá nastavit na Infinity (nebo 0) a označit tak neomezený počet naslouchacích procesů.

Vrátí odkaz na EventEmitter, aby bylo možné volání zřetězený.

function setMaxListeners(n: number): Twin

Parametry

n

number

Návraty

Twin

Zděděno z 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)[])

Parametry

n

number

Nezáporné číslo. Maximální počet naslouchacích procesů na EventTarget událost.

eventTargets

(EventEmitter<DefaultEventMap> | EventTarget)[]

Zděděno z EventEmitter.setMaxListeners

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

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

Parametry

error

Error

event

string | symbol

args

AnyRest

Zděděno z EventEmitter.__@captureRejectionSymbol@138