electron builder.Class.CancellationToken

Electron-Builder / electron-builder / CancellationToken

继承自¶

EventEmitter

构造函数¶

new CancellationToken()¶

new CancellationToken(parent?): CancellationToken

参数¶

• parent?: CancellationToken

返回值¶

CancellationToken

覆盖¶

EventEmitter.constructor

属性¶

captureRejections¶

static captureRejections: boolean

值: boolean

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

始于¶

v13.4.0, v12.16.0

继承自¶

EventEmitter.captureRejections

captureRejectionSymbol¶

readonly static captureRejectionSymbol: typeof captureRejectionSymbol

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

查看如何编写自定义 rejection handler。

始于¶

v13.4.0, v12.16.0

继承自¶

EventEmitter.captureRejectionSymbol

defaultMaxListeners¶

static defaultMaxListeners: number

默认情况下，对于任何单个事件，最多可以注册 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'。

始于¶

v0.11.2

继承自¶

EventEmitter.defaultMaxListeners

errorMonitor¶

readonly static errorMonitor: typeof errorMonitor

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

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

始于¶

v13.6.0, v12.17.0

继承自¶

EventEmitter.errorMonitor

访问器¶

cancelled¶

get cancelled(): boolean

返回值¶

boolean

parent¶

set parent(value): void

参数¶

• value: CancellationToken

方法¶

[captureRejectionSymbol]()?¶

optional [captureRejectionSymbol]<K>(error, event, …args): void

类型参数¶

• K

参数¶

• error: Error

• event: string | symbol

• …args: AnyRest

返回值¶

void

继承自¶

EventEmitter.[captureRejectionSymbol]

addListener()¶

addListener<K>(eventName, listener): this

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

类型参数¶

• K

参数¶

• eventName: string | symbol

• listener

返回值¶

this

始于¶

v0.1.26

继承自¶

EventEmitter.addListener

cancel()¶

cancel(): void

返回值¶

void

createPromise()¶

createPromise<R>(callback): Promise<R>

类型参数¶

• R

参数¶

• callback

返回值¶

Promise<R>

dispose()¶

dispose(): void

返回值¶

void

emit()¶

emit<K>(eventName, …args): boolean

同步调用为名为 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

类型参数¶

• K

参数¶

• eventName: string | symbol

• …args: AnyRest

返回值¶

boolean

始于¶

v0.1.26

继承自¶

EventEmitter.emit

eventNames()¶

eventNames(): (string | symbol)[]

返回一个数组，列出 emitter 已注册监听器的事件。数组中的值是字符串或 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) ]

返回值¶

(string | symbol)[]

始于¶

v6.0.0

继承自¶

EventEmitter.eventNames

getMaxListeners()¶

getMaxListeners(): number

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

返回值¶

number

始于¶

v1.0.0

继承自¶

EventEmitter.getMaxListeners

listenerCount()¶

listenerCount<K>(eventName, listener?): number

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

类型参数¶

• K

参数¶

• eventName: string | symbol

要监听的事件的名称

• listener?: Function

事件处理函数

返回值¶

number

始于¶

v3.2.0

继承自¶

EventEmitter.listenerCount

listeners()¶

listeners<K>(eventName): Function[]

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

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

类型参数¶

• K

参数¶

• eventName: string | symbol

返回值¶

Function[]

始于¶

v0.1.26

继承自¶

EventEmitter.listeners

off()¶

off<K>(eventName, listener): this

emitter.removeListener() 的别名。

类型参数¶

• K

参数¶

• eventName: string | symbol

• listener

返回值¶

this

始于¶

v10.0.0

继承自¶

EventEmitter.off

on()¶

on<K>(eventName, listener): this

将 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

类型参数¶

• K

参数¶

• eventName: string | symbol

事件的名称。

• listener

回调函数

返回值¶

this

始于¶

v0.1.101

继承自¶

EventEmitter.on

once()¶

once<K>(eventName, listener): this

为名为 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

类型参数¶

• K

参数¶

• eventName: string | symbol

事件的名称。

• listener

回调函数

返回值¶

this

始于¶

v0.3.0

继承自¶

EventEmitter.once

prependListener()¶

prependListener<K>(eventName, listener): this

将 listener 函数添加到名为 eventName 的事件的监听器数组的开头。不检查是否已添加 listener。多次调用传递相同的 eventName 和 listener 组合将导致 listener 被添加和调用多次。

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

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

类型参数¶

• K

参数¶

• eventName: string | symbol

事件的名称。

• listener

回调函数

返回值¶

this

始于¶

v6.0.0

继承自¶

EventEmitter.prependListener

prependOnceListener()¶

prependOnceListener<K>(eventName, listener): this

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

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

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

类型参数¶

• K

参数¶

• eventName: string | symbol

事件的名称。

• listener

回调函数

返回值¶

this

始于¶

v6.0.0

继承自¶

EventEmitter.prependOnceListener

rawListeners()¶

rawListeners<K>(eventName): Function[]

返回名为 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');

类型参数¶

• K

参数¶

• eventName: string | symbol

返回值¶

Function[]

始于¶

v9.4.0

继承自¶

EventEmitter.rawListeners

removeAllListeners()¶

removeAllListeners(eventName?): this

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

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

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

参数¶

• eventName?: string | symbol

返回值¶

this

始于¶

v0.1.26

继承自¶

EventEmitter.removeAllListeners

removeListener()¶

removeListener<K>(eventName, listener): this

从名为 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 的引用，以便可以链式调用。

类型参数¶

• K

参数¶

• eventName: string | symbol

• listener

返回值¶

this

始于¶

v0.1.26

继承自¶

EventEmitter.removeListener

setMaxListeners()¶

setMaxListeners(n): this

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

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

参数¶

• n: number

返回值¶

this

始于¶

v0.3.5

继承自¶

EventEmitter.setMaxListeners

addAbortListener()¶

static addAbortListener(signal, resource): Disposable

实验性

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

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

此 API 通过侦听事件（使得 stopImmediatePropagation 不会阻止监听器运行）解决了这两个问题，从而允许在 Node.js API 中安全地使用 AbortSignal。

返回一个 disposable，以便可以更轻松地取消订阅。

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

参数¶

• signal: AbortSignal

• resource

返回值¶

Disposable

删除 abort 监听器的 Disposable。

始于¶

v20.5.0

继承自¶

EventEmitter.addAbortListener

getEventListeners()¶

static getEventListeners(emitter, name): Function[]

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

对于 EventEmitter，这与在 emitter 上调用 .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] ]
}

参数¶

• emitter: EventEmitter<DefaultEventMap> | EventTarget

• name: string | symbol

返回值¶

Function[]

始于¶

v15.2.0, v14.17.0

继承自¶

EventEmitter.getEventListeners

getMaxListeners()¶

static getMaxListeners(emitter): number

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

对于 EventEmitter，这与在 emitter 上调用 .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
}

参数¶

• emitter: EventEmitter<DefaultEventMap> | EventTarget

返回值¶

number

始于¶

v19.9.0

继承自¶

EventEmitter.getMaxListeners

listenerCount()¶

static listenerCount(emitter, eventName): number

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

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

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

参数¶

• emitter: EventEmitter<DefaultEventMap>

要查询的 emitter

• eventName: string | symbol

事件名称

返回值¶

number

始于¶

v0.9.12

已弃用¶

始于 v3.2.0 - 请使用 listenerCount 代替。

继承自¶

EventEmitter.listenerCount

on()¶

on(emitter, eventName, options)¶

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

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

返回一个迭代 eventName 事件的 AsyncIterator。如果 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'

参数¶

• emitter: EventEmitter<DefaultEventMap>

• eventName: string | symbol

• options?: StaticEventEmitterIteratorOptions

返回值¶

AsyncIterator<any[], any, any>

一个 AsyncIterator，用于迭代 emitter 发出的 eventName 事件

始于¶

v13.6.0, v12.16.0

继承自¶

EventEmitter.on

on(emitter, eventName, options)¶

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

参数¶

• emitter: EventTarget

• eventName: string

• options?: StaticEventEmitterIteratorOptions

返回值¶

AsyncIterator<any[], any, any>

继承自¶

EventEmitter.on

once()¶

once(emitter, eventName, options)¶

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

创建一个 Promise，当 EventEmitter 发出给定事件时，该 Promise 将被兑现；如果 EventEmitter 在等待时发出 'error'，则该 Promise 将被拒绝。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!

参数¶

• emitter: EventEmitter<DefaultEventMap>

• eventName: string | symbol

• options?: StaticEventEmitterOptions

返回¶

Promise<any[]>

始于¶

v11.13.0, v10.16.0

继承自¶

EventEmitter.once

once(emitter, eventName, options)¶

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

参数¶

• emitter: EventTarget

• eventName: string

• options?: StaticEventEmitterOptions

返回¶

Promise<any[]>

继承自¶

EventEmitter.once

setMaxListeners()¶

static setMaxListeners(n?, …eventTargets?): void

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

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

setMaxListeners(5, target, emitter);

参数¶

• n?: number

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

• …eventTargets?: (EventEmitter<DefaultEventMap> | EventTarget)[]

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

返回¶

void

始于¶

v15.4.0

继承自¶

EventEmitter.setMaxListeners