Client class
用來將裝置與 Azure IoT 中樞連線的 IoT 中樞裝置用戶端。
SDK 的用戶應該呼叫其中一個 Factory 方法 ,fromConnectionString 或 fromSharedAccessSignature 來建立 IoT 中樞裝置用戶端。
- Extends
-
InternalClient
建構函式
Client(Device |
繼承的屬性
capture |
值: 布爾值 變更所有新 |
capture |
值: 瞭解如何撰寫自訂 |
default |
根據預設,最多可以註冊任何單一 設定 這不是硬式限制。
您可以檢查 |
error |
此符號應該用來只安裝監視 使用此符號安裝接聽程式不會在發出事件之後 |
方法
close() | |
close(Callback<Disconnected>) | 關閉傳輸連線並終結客戶端資源。 注意:呼叫此方法之後,無法重複使用 Client 物件。 |
from |
使用指定的傳輸類型,從指定的驗證方法建立IoT中樞裝置用戶端。 |
from |
使用指定的傳輸類型,從指定的連接字串建立IoT中樞裝置用戶端。 |
from |
使用指定的傳輸類型,從指定的共用存取簽章建立IoT中樞裝置用戶端。 |
get |
|
get |
會 |
notify |
|
notify |
方法會 |
on |
註冊名為 |
set |
|
set |
|
upload |
|
upload |
方法 |
繼承的方法
abandon(Message) | |
abandon(Message, Callback<Message |
|
add |
在提供的 接 此 API 允許在 Node.js API 中安全地使用 傳回可處置的 ,以便更輕鬆地取消訂閱。
|
add |
的 |
complete(Message) | |
complete(Message, Callback<Message |
|
emit<K>(string | symbol, Any |
以同步方式呼叫針對名為 如果事件具有接聽程式,則傳
|
event |
傳回數位,其中列出發出器已註冊接聽程式的事件。 陣列中的值是字串或
|
get |
傳回名為 針對 針對
|
get |
傳回預設為 defaultMaxListeners 所設定 |
get |
傳回目前設定的接聽程序數量上限。 針對 針對
|
get |
|
get |
|
listener |
類別方法,傳回在指定 上註冊之指定
|
listener |
傳回接聽名為 之事件的接聽程式 |
listeners<K>(string | symbol) | 傳回名為
|
off<K>(string | symbol, (args: any[]) => void) | 的 |
on(Event |
傳回逐一
|
on(Event |
|
on<K>(string | symbol, (args: any[]) => void) | 將函
傳回 的 根據預設,事件接聽程式會依新增的順序叫用。 方法
|
once(Event |
建立 , 這個方法是刻意泛型的,適用於 Web 平臺 EventTarget 介面,其沒有特殊的
只有在用來等候另一個事件時
|
once(Event |
|
once<K>(string | symbol, (args: any[]) => void) | 為名為
傳回 的 根據預設,事件接聽程式會依新增的順序叫用。 方法
|
open() | |
open(Callback<Connected>) | |
prepend |
將函
傳回 的 |
prepend |
將名為
傳回 的 |
raw |
傳回名為
|
reject(Message) | |
reject(Message, Callback<Message |
|
remove |
拿掉所有接聽程式,或指定 拿掉程式代碼中其他位置新增的接聽程式是錯誤的作法,特別是當 傳回 的 |
remove |
從名為
發出事件之後,在發出時附加的所有接聽程式都會依序呼叫。 這表示發出之後和最後一個接聽程式完成執行之前的任何
由於接聽程式是使用內部數位來管理的,因此呼叫這會變更移除接聽程序 之後 所註冊之任何接聽程式的位置索引。 這不會影響呼叫接聽程式的順序,但表示必須重新建立方法所 當單一函式新增為單一事件的處理程式多次時, (如下列範例所示) ,
傳回 的 |
send |
|
send |
|
send |
|
send |
|
set |
根據預設 傳回 的 |
set |
|
set |
設定用戶端在所有作業上使用的重試原則。 預設值為 ExponentialBackoffWithJitter。 |
set |
|
set |
|
update |
|
[capture |
建構函式詳細資料
Client(DeviceTransport, string, BlobUploadClient, FileUploadInterface)
new Client(transport: DeviceTransport, connStr?: string, blobUploadClient?: BlobUploadClient, fileUploadApi?: FileUploadInterface)
參數
- transport
- DeviceTransport
實作傳輸物件預期介面的物件,例如 Http。
- connStr
-
string
連接字串 (選擇性:未提供時,必須呼叫 updateSharedAccessSignature,才能直接) 設定 SharedAccessSignature 令牌。
- blobUploadClient
-
BlobUploadClient
能夠將數據流上傳至 Blob 的物件。
- fileUploadApi
-
FileUploadInterface
對象,用於與 Blob 記憶體相關動作的 IoT 中樞通訊。
繼承的屬性詳細資料
captureRejections
值: 布爾值
變更所有新EventEmitter
物件上的預設captureRejections
選項。
static captureRejections: boolean
屬性值
boolean
繼承自 InternalClient.captureRejections
captureRejectionSymbol
值:Symbol.for('nodejs.rejection')
瞭解如何撰寫自訂 rejection handler
。
static captureRejectionSymbol: typeof captureRejectionSymbol
屬性值
typeof captureRejectionSymbol
繼承自 InternalClient.captureRejectionSymbol
defaultMaxListeners
根據預設,最多可以註冊任何單一 10
事件的接聽程式。 您可以使用 方法來變更個別 EventEmitter
實例 emitter.setMaxListeners(n)
的限制。 若要變更 所有EventEmitter
實例的預設值, events.defaultMaxListeners
可以使用 屬性。 如果此值不是正數, RangeError
則會擲回 。
設定 events.defaultMaxListeners
時請小心,因為變更會影響 所有EventEmitter
實例,包括在進行變更之前建立的實例。 不過,呼叫 emitter.setMaxListeners(n)
仍然優先於 events.defaultMaxListeners
。
這不是硬式限制。 EventEmitter
實例將允許新增更多接聽程式,但會將追蹤警告輸出至 stderr,指出偵測到「可能的 EventEmitter 記憶體流失」。 對於任何單一 EventEmitter
, emitter.getMaxListeners()
和 emitter.setMaxListeners()
方法可用來暫時避免這個警告:
import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.setMaxListeners(emitter.getMaxListeners() + 1);
emitter.once('event', () => {
// do stuff
emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
});
--trace-warnings
命令行旗標可用來顯示這類警告的堆疊追蹤。
您可以檢查 process.on('warning')
發出的警告,並分別具有其他 emitter
、 type
和 count
屬性,參考事件發出器實例、事件的名稱和附加接聽程式的數目。
屬性 name
會設定為 'MaxListenersExceededWarning'
。
static defaultMaxListeners: number
屬性值
number
繼承自 InternalClient.defaultMaxListeners
errorMonitor
此符號應該用來只安裝監視 'error'
事件的接聽程式。 使用這個符號安裝的接聽程式會在呼叫一般 'error'
接聽程式之前呼叫。
使用此符號安裝接聽程式不會在發出事件之後 'error'
變更行為。 因此,如果未安裝一般 'error'
接聽程式,進程仍會當機。
static errorMonitor: typeof errorMonitor
屬性值
typeof errorMonitor
繼承自 InternalClient.errorMonitor
方法詳細資料
close()
function close(): Promise<Disconnected>
傳回
Promise<Disconnected>
close(Callback<Disconnected>)
關閉傳輸連線並終結客戶端資源。
注意:呼叫此方法之後,無法重複使用 Client 物件。
function close(closeCallback?: Callback<Disconnected>)
參數
- closeCallback
-
Callback<Disconnected>
在傳輸中斷連線且用戶端關閉之後,要呼叫的選擇性函式。
fromAuthenticationProvider(AuthenticationProvider, any)
使用指定的傳輸類型,從指定的驗證方法建立IoT中樞裝置用戶端。
static function fromAuthenticationProvider(authenticationProvider: AuthenticationProvider, transportCtor: any): Client
參數
- authenticationProvider
-
AuthenticationProvider
物件,用來取得IoT中樞的驗證參數。
- transportCtor
-
any
用來連線到IoT中樞的傳輸通訊協定。
傳回
fromConnectionString(string, any)
使用指定的傳輸類型,從指定的連接字串建立IoT中樞裝置用戶端。
static function fromConnectionString(connStr: string, transportCtor: any): Client
參數
- connStr
-
string
連接字串,封裝IoT中樞上的「裝置連線」許可權。
- transportCtor
-
any
傳輸建構函式。
傳回
fromSharedAccessSignature(string, any)
使用指定的傳輸類型,從指定的共用存取簽章建立IoT中樞裝置用戶端。
static function fromSharedAccessSignature(sharedAccessSignature: string, transportCtor: any): Client
參數
- sharedAccessSignature
-
string
共用存取簽章,封裝IoT中樞上的「裝置連線」許可權。
- transportCtor
-
any
傳回
getBlobSharedAccessSignature(string)
function getBlobSharedAccessSignature(blobName: string): Promise<UploadParams>
參數
- blobName
-
string
傳回
Promise<UploadParams>
getBlobSharedAccessSignature(string, Callback<UploadParams>)
會 getBlobSharedAccessSignature
從IoT中樞取得連結的記憶體帳戶 SAS 令牌
function getBlobSharedAccessSignature(blobName: string, callback?: Callback<UploadParams>)
參數
- blobName
-
string
要用於將使用數據流內容建立之 Blob 的名稱。
- callback
-
Callback<UploadParams>
上傳完成時要呼叫的選擇性回呼。
notifyBlobUploadStatus(string, boolean, number, string)
function notifyBlobUploadStatus(correlationId: string, isSuccess: boolean, statusCode: number, statusDescription: string): Promise<void>
參數
- correlationId
-
string
- isSuccess
-
boolean
- statusCode
-
number
- statusDescription
-
string
傳回
Promise<void>
notifyBlobUploadStatus(string, boolean, number, string, ErrorCallback)
方法會 notifyBlobUploadStatus
傳送IoT中樞 Blob 上傳的結果。
function notifyBlobUploadStatus(correlationId: string, isSuccess: boolean, statusCode: number, statusDescription: string, callback?: ErrorCallback)
參數
- correlationId
-
string
將上傳狀態與特定 Blob 相互關聯的標識碼。 在呼叫 getBlobSharedAccessSignature
期間產生。
- isSuccess
-
boolean
記憶體 Blob 作業結果的成功或失敗狀態。
- statusCode
-
number
與記憶體 Blob 結果相關聯的 HTTP 狀態代碼。
- statusDescription
-
string
HTTP 狀態代碼的描述。
- callback
-
ErrorCallback
上傳完成時要呼叫的選擇性回呼。
onDeviceMethod(string, (request: DeviceMethodRequest, response: DeviceMethodResponse) => void)
註冊名為 methodName
的方法回呼。
function onDeviceMethod(methodName: string, callback: (request: DeviceMethodRequest, response: DeviceMethodResponse) => void)
參數
- methodName
-
string
回呼將處理的方法名稱
- callback
-
(request: DeviceMethodRequest, response: DeviceMethodResponse) => void
每當收到所呼叫方法 methodName
的方法要求時,應該呼叫的函式。
setOptions(DeviceClientOptions)
function setOptions(options: DeviceClientOptions): Promise<TransportConfigured>
參數
- options
- DeviceClientOptions
傳回
Promise<TransportConfigured>
setOptions(DeviceClientOptions, Callback<TransportConfigured>)
function setOptions(options: DeviceClientOptions, done: Callback<TransportConfigured>)
參數
- options
- DeviceClientOptions
- done
-
Callback<TransportConfigured>
uploadToBlob(string, Stream, number)
function uploadToBlob(blobName: string, stream: Stream, streamLength: number): Promise<void>
參數
- blobName
-
string
- stream
-
Stream
- streamLength
-
number
傳回
Promise<void>
uploadToBlob(string, Stream, number, ErrorCallback)
方法 uploadToBlob
會將數據流上傳至 Blob。
function uploadToBlob(blobName: string, stream: Stream, streamLength: number, callback: ErrorCallback)
參數
- blobName
-
string
要用於將使用數據流內容建立之 Blob 的名稱。
- stream
-
Stream
應該上傳至 Blob 的數據。
- streamLength
-
number
應該上傳至 Blob 的數據大小。
- callback
-
ErrorCallback
繼承的方法的詳細資料
abandon(Message)
function abandon(message: Message): Promise<MessageAbandoned>
參數
- message
- Message
傳回
Promise<MessageAbandoned>
繼承自 InternalClient.abandon
abandon(Message, Callback<MessageAbandoned>)
function abandon(message: Message, abandonCallback: Callback<MessageAbandoned>)
參數
- message
- Message
- abandonCallback
-
Callback<MessageAbandoned>
繼承自 InternalClient.abandon
addAbortListener(AbortSignal, (event: Event) => void)
在提供的 signal
上接abort
聽事件一次。
接 abort
聽中止訊號上的事件不安全,而且可能會導致資源流失,因為具有訊號的另一方可以呼叫 e.stopImmediatePropagation()
。 不幸的是,Node.js 無法變更此專案,因為它會違反 Web 標準。 此外,原始 API 可讓您輕鬆忘記移除接聽程式。
此 API 允許在 Node.js API 中安全地使用 AbortSignal
,方法是藉由接聽事件來解決這兩個問題, stopImmediatePropagation
以避免接聽程式執行。
傳回可處置的 ,以便更輕鬆地取消訂閱。
import { addAbortListener } from 'node:events';
function example(signal) {
let disposable;
try {
signal.addEventListener('abort', (e) => e.stopImmediatePropagation());
disposable = addAbortListener(signal, (e) => {
// Do something when signal is aborted.
});
} finally {
disposable?.[Symbol.dispose]();
}
}
static function addAbortListener(signal: AbortSignal, resource: (event: Event) => void): Disposable
參數
- signal
-
AbortSignal
- resource
-
(event: Event) => void
傳回
Disposable
可處置的可移除接 abort
聽程式。
繼承自 InternalClient.addAbortListener
addListener<K>(string | symbol, (args: any[]) => void)
的 emitter.on(eventName, listener)
別名。
function addListener<K>(eventName: string | symbol, listener: (args: any[]) => void): Client
參數
- eventName
-
string | symbol
- listener
-
(args: any[]) => void
傳回
繼承自 InternalClient.addListener
complete(Message)
function complete(message: Message): Promise<MessageCompleted>
參數
- message
- Message
傳回
Promise<MessageCompleted>
繼承自 InternalClient.complete
complete(Message, Callback<MessageCompleted>)
function complete(message: Message, completeCallback: Callback<MessageCompleted>)
參數
- message
- Message
- completeCallback
-
Callback<MessageCompleted>
繼承自 InternalClient.complete
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
繼承自 InternalClient.emit
eventNames()
傳回數位,其中列出發出器已註冊接聽程式的事件。 陣列中的值是字串或 Symbol
。
import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});
const sym = Symbol('symbol');
myEE.on(sym, () => {});
console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
function eventNames(): (string | symbol)[]
傳回
(string | symbol)[]
繼承自 InternalClient.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[]
繼承自 InternalClient.getEventListeners
getMaxListeners()
傳回預設為 defaultMaxListeners 所設定emitter.setMaxListeners(n)
之 的目前 max 接聽程式值EventEmitter
。
function getMaxListeners(): number
傳回
number
繼承自 InternalClient.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
繼承自 InternalClient.getMaxListeners
getTwin()
getTwin(Callback<Twin>)
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
繼承自 InternalClient.listenerCount
listenerCount<K>(string | symbol, Function)
傳回接聽名為 之事件的接聽程式 eventName
數目。
如果 listener
提供 ,它會傳回接聽程式在事件的接聽程式清單中找到的次數。
function listenerCount<K>(eventName: string | symbol, listener?: Function): number
參數
- eventName
-
string | symbol
正在接聽的事件名稱
- listener
-
Function
事件處理程式函式
傳回
number
繼承自 InternalClient.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[]
繼承自 InternalClient.listeners
off<K>(string | symbol, (args: any[]) => void)
的 emitter.removeListener()
別名。
function off<K>(eventName: string | symbol, listener: (args: any[]) => void): Client
參數
- eventName
-
string | symbol
- listener
-
(args: any[]) => void
傳回
繼承自 InternalClient.off
on(EventEmitter<DefaultEventMap>, string | symbol, StaticEventEmitterOptions)
import { on, EventEmitter } from 'node:events';
import process from 'node:process';
const ee = new EventEmitter();
// Emit later on
process.nextTick(() => {
ee.emit('foo', 'bar');
ee.emit('foo', 42);
});
for await (const event of on(ee, 'foo')) {
// The execution of this inner block is synchronous and it
// processes one event at a time (even with await). Do not use
// if concurrent execution is required.
console.log(event); // prints ['bar'] [42]
}
// Unreachable here
傳回逐一 AsyncIterator
查看 eventName
事件的 。 如果 EventEmitter
發出 'error'
,則會擲回 。 它會在結束迴圈時移除所有接聽程式。 value
每個反覆專案所傳回的陣列是由發出的事件自變數所組成。
AbortSignal
可用來取消等候事件:
import { on, EventEmitter } from 'node:events';
import process from 'node:process';
const ac = new AbortController();
(async () => {
const ee = new EventEmitter();
// Emit later on
process.nextTick(() => {
ee.emit('foo', 'bar');
ee.emit('foo', 42);
});
for await (const event of on(ee, 'foo', { signal: ac.signal })) {
// The execution of this inner block is synchronous and it
// processes one event at a time (even with await). Do not use
// if concurrent execution is required.
console.log(event); // prints ['bar'] [42]
}
// Unreachable here
})();
process.nextTick(() => ac.abort());
static function on(emitter: EventEmitter<DefaultEventMap>, eventName: string | symbol, options?: StaticEventEmitterOptions): AsyncIterableIterator<any>
參數
- emitter
-
EventEmitter<DefaultEventMap>
- eventName
-
string | symbol
正在接聽的事件名稱
- options
-
StaticEventEmitterOptions
傳回
AsyncIterableIterator<any>
, AsyncIterator
逐一查看 eventName
所發出的事件 emitter
繼承自 InternalClient.on
on(EventTarget, string, StaticEventEmitterOptions)
static function on(emitter: EventTarget, eventName: string, options?: StaticEventEmitterOptions): AsyncIterableIterator<any>
參數
- emitter
-
EventTarget
- eventName
-
string
- options
-
StaticEventEmitterOptions
傳回
AsyncIterableIterator<any>
繼承自 InternalClient.on
on<K>(string | symbol, (args: any[]) => void)
將函 listener
式加入至名為 eventName
之事件的接聽程式陣列結尾。 不會進行任何檢查,以檢視 是否已 listener
新增 。 多個呼叫會傳遞和 listener
的相同組合eventName
,將會導致listener
新增和呼叫多次。
server.on('connection', (stream) => {
console.log('someone connected!');
});
傳回 的 EventEmitter
參考,以便鏈結呼叫。
根據預設,事件接聽程式會依新增的順序叫用。 方法 emitter.prependListener()
可作為將事件接聽程式新增至接聽程式陣列開頭的替代方法。
import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
// b
// a
function on<K>(eventName: string | symbol, listener: (args: any[]) => void): Client
參數
- eventName
-
string | symbol
事件的名稱。
- listener
-
(args: any[]) => void
回調函式
傳回
繼承自 InternalClient.on
once(EventEmitter<DefaultEventMap>, string | symbol, Pick<StaticEventEmitterOptions, "signal">)
建立 ,Promise
當發出指定的事件時EventEmitter
,或在等候時發出'error'
時EventEmitter
遭到拒絕。
Promise
將會使用發出給指定事件之所有自變數的數位來解析。
這個方法是刻意泛型的,適用於 Web 平臺 EventTarget 介面,其沒有特殊的'error'
事件語意,而且不會接 'error'
聽事件。
import { once, EventEmitter } from 'node:events';
import process from 'node:process';
const ee = new EventEmitter();
process.nextTick(() => {
ee.emit('myevent', 42);
});
const [value] = await once(ee, 'myevent');
console.log(value);
const err = new Error('kaboom');
process.nextTick(() => {
ee.emit('error', err);
});
try {
await once(ee, 'myevent');
} catch (err) {
console.error('error happened', err);
}
只有在用來等候另一個事件時events.once()
,才會使用事件的特殊處理'error'
。 如果使用 events.once()
來等候 'error'
事件本身,則會將其視為任何其他類型的事件,而不需特殊處理:
import { EventEmitter, once } from 'node:events';
const ee = new EventEmitter();
once(ee, 'error')
.then(([err]) => console.log('ok', err.message))
.catch((err) => console.error('error', err.message));
ee.emit('error', new Error('boom'));
// Prints: ok boom
AbortSignal
可用來取消等候事件:
import { EventEmitter, once } from 'node:events';
const ee = new EventEmitter();
const ac = new AbortController();
async function foo(emitter, event, signal) {
try {
await once(emitter, event, { signal });
console.log('event emitted!');
} catch (error) {
if (error.name === 'AbortError') {
console.error('Waiting for the event was canceled!');
} else {
console.error('There was an error', error.message);
}
}
}
foo(ee, 'foo', ac.signal);
ac.abort(); // Abort waiting for the event
ee.emit('foo'); // Prints: Waiting for the event was canceled!
static function once(emitter: EventEmitter<DefaultEventMap>, eventName: string | symbol, options?: Pick<StaticEventEmitterOptions, "signal">): Promise<any[]>
參數
- emitter
-
EventEmitter<DefaultEventMap>
- eventName
-
string | symbol
- options
-
Pick<StaticEventEmitterOptions, "signal">
傳回
Promise<any[]>
繼承自 InternalClient.once
once(EventTarget, string, StaticEventEmitterOptions)
static function once(emitter: EventTarget, eventName: string, options?: StaticEventEmitterOptions): Promise<any[]>
參數
- emitter
-
EventTarget
- eventName
-
string
- options
-
StaticEventEmitterOptions
傳回
Promise<any[]>
繼承自 InternalClient.once
once<K>(string | symbol, (args: any[]) => void)
為名為eventName
的事件加入一次性listener
函式。 下次觸發時 eventName
,會移除此接聽程式,然後叫用。
server.once('connection', (stream) => {
console.log('Ah, we have our first user!');
});
傳回 的 EventEmitter
參考,以便鏈結呼叫。
根據預設,事件接聽程式會依新增的順序叫用。 方法 emitter.prependOnceListener()
可作為將事件接聽程式新增至接聽程式陣列開頭的替代方法。
import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
// b
// a
function once<K>(eventName: string | symbol, listener: (args: any[]) => void): Client
參數
- eventName
-
string | symbol
事件的名稱。
- listener
-
(args: any[]) => void
回調函式
傳回
繼承自 InternalClient.once
open()
function open(): Promise<Connected>
傳回
Promise<Connected>
繼承自 InternalClient.open
open(Callback<Connected>)
function open(openCallback: Callback<Connected>)
參數
- openCallback
-
Callback<Connected>
繼承自 InternalClient.open
prependListener<K>(string | symbol, (args: any[]) => void)
將函listener
式加入至名為 eventName
之事件的接聽程式數位開頭。 不會進行任何檢查,以檢視 是否已 listener
新增 。 多個呼叫會傳遞和 listener
的相同組合eventName
,將會導致listener
新增和呼叫多次。
server.prependListener('connection', (stream) => {
console.log('someone connected!');
});
傳回 的 EventEmitter
參考,以便鏈結呼叫。
function prependListener<K>(eventName: string | symbol, listener: (args: any[]) => void): Client
參數
- eventName
-
string | symbol
事件的名稱。
- listener
-
(args: any[]) => void
回調函式
傳回
繼承自 InternalClient.prependListener
prependOnceListener<K>(string | symbol, (args: any[]) => void)
將名為 eventName
之事件的一次性listener
函式新增至接聽程式陣列的開頭。 下次觸發時 eventName
,會移除此接聽程式,然後叫用。
server.prependOnceListener('connection', (stream) => {
console.log('Ah, we have our first user!');
});
傳回 的 EventEmitter
參考,以便鏈結呼叫。
function prependOnceListener<K>(eventName: string | symbol, listener: (args: any[]) => void): Client
參數
- eventName
-
string | symbol
事件的名稱。
- listener
-
(args: any[]) => void
回調函式
傳回
繼承自 InternalClient.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[]
繼承自 InternalClient.rawListeners
reject(Message)
function reject(message: Message): Promise<MessageRejected>
參數
- message
- Message
傳回
Promise<MessageRejected>
繼承自 InternalClient.reject
reject(Message, Callback<MessageRejected>)
function reject(message: Message, rejectCallback: Callback<MessageRejected>)
參數
- message
- Message
- rejectCallback
-
Callback<MessageRejected>
繼承自 InternalClient.reject
removeAllListeners(string | symbol)
拿掉所有接聽程式,或指定 eventName
之的接聽程式。
拿掉程式代碼中其他位置新增的接聽程式是錯誤的作法,特別是當 EventEmitter
實例是由某些其他元件或模組所建立時, (例如套接字或檔案數據流) 。
傳回 的 EventEmitter
參考,以便鏈結呼叫。
function removeAllListeners(eventName?: string | symbol): Client
參數
- eventName
-
string | symbol
傳回
繼承自 InternalClient.removeAllListeners
removeListener<K>(string | symbol, (args: any[]) => void)
從名為 eventName
之事件的接聽程式陣列中移除指定的 listener
。
const callback = (stream) => {
console.log('someone connected!');
};
server.on('connection', callback);
// ...
server.removeListener('connection', callback);
removeListener()
最多會從接聽程式陣列中移除一個接聽程序的實例。 如果任何單一接聽程式已多次新增至指定 eventName
之的接聽程式陣列, removeListener()
則必須多次呼叫 ,才能移除每個實例。
發出事件之後,在發出時附加的所有接聽程式都會依序呼叫。 這表示發出之後和最後一個接聽程式完成執行之前的任何 removeListener()
或 removeAllListeners()
呼叫都不會從emit()
進行中移除它們。 後續事件會如預期般運作。
import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
const callbackA = () => {
console.log('A');
myEmitter.removeListener('event', callbackB);
};
const callbackB = () => {
console.log('B');
};
myEmitter.on('event', callbackA);
myEmitter.on('event', callbackB);
// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
// A
// B
// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
// A
由於接聽程式是使用內部數位來管理的,因此呼叫這會變更移除接聽程序 之後 所註冊之任何接聽程式的位置索引。 這不會影響呼叫接聽程式的順序,但表示必須重新建立方法所 emitter.listeners()
傳回的任何接聽程式陣列複本。
當單一函式新增為單一事件的處理程式多次時, (如下列範例所示) , removeListener()
將會移除最近新增的實例。 在範例中, once('ping')
會移除接聽程式:
import { EventEmitter } from 'node:events';
const ee = new EventEmitter();
function pong() {
console.log('pong');
}
ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);
ee.emit('ping');
ee.emit('ping');
傳回 的 EventEmitter
參考,以便鏈結呼叫。
function removeListener<K>(eventName: string | symbol, listener: (args: any[]) => void): Client
參數
- eventName
-
string | symbol
- listener
-
(args: any[]) => void
傳回
繼承自 InternalClient.removeListener
sendEvent(Message)
function sendEvent(message: Message): Promise<MessageEnqueued>
參數
- message
- Message
傳回
Promise<MessageEnqueued>
繼承自 InternalClient.sendEvent
sendEvent(Message, Callback<MessageEnqueued>)
function sendEvent(message: Message, sendEventCallback: Callback<MessageEnqueued>)
參數
- message
- Message
- sendEventCallback
-
Callback<MessageEnqueued>
繼承自 InternalClient.sendEvent
sendEventBatch(Message[])
function sendEventBatch(messages: Message[]): Promise<MessageEnqueued>
參數
- messages
-
Message[]
傳回
Promise<MessageEnqueued>
繼承自 InternalClient.sendEventBatch
sendEventBatch(Message[], Callback<MessageEnqueued>)
function sendEventBatch(messages: Message[], sendEventBatchCallback: Callback<MessageEnqueued>)
參數
- messages
-
Message[]
- sendEventBatchCallback
-
Callback<MessageEnqueued>
繼承自 InternalClient.sendEventBatch
setMaxListeners(number)
根據預設 EventEmitter
,如果針對特定事件新增超過 10
接聽程式,則會列印警告。 這是有助於尋找記憶體流失的實用預設值。 方法 emitter.setMaxListeners()
允許修改這個特定 EventEmitter
實例的限制。 此值可以設定為 Infinity
(或 0
) ,以表示不限數目的接聽程式。
傳回 的 EventEmitter
參考,以便鏈結呼叫。
function setMaxListeners(n: number): Client
參數
- n
-
number
傳回
繼承自 InternalClient.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)[]
繼承自 InternalClient.setMaxListeners
setRetryPolicy(RetryPolicy)
設定用戶端在所有作業上使用的重試原則。 預設值為 ExponentialBackoffWithJitter。
function setRetryPolicy(policy: RetryPolicy)
參數
- policy
-
RetryPolicy
{RetryPolicy}應該用於所有未來作業的重試原則。
繼承自 InternalClient.setRetryPolicy
setTransportOptions(any)
function setTransportOptions(options: any): Promise<TransportConfigured>
參數
- options
-
any
傳回
Promise<TransportConfigured>
繼承自 InternalClient.setTransportOptions
setTransportOptions(any, Callback<TransportConfigured>)
function setTransportOptions(options: any, done: Callback<TransportConfigured>)
參數
- options
-
any
- done
-
Callback<TransportConfigured>
繼承自 InternalClient.setTransportOptions
updateSharedAccessSignature(string, Callback<SharedAccessSignatureUpdated>)
function updateSharedAccessSignature(sharedAccessSignature: string, updateSasCallback?: Callback<SharedAccessSignatureUpdated>)
參數
- sharedAccessSignature
-
string
- updateSasCallback
-
Callback<SharedAccessSignatureUpdated>
繼承自 InternalClient.updateSharedAccessSignature
[captureRejectionSymbol]<K>(Error, string | symbol, AnyRest)
function [captureRejectionSymbol]<K>(error: Error, event: string | symbol, args: AnyRest)
參數
- error
-
Error
- event
-
string | symbol
- args
-
AnyRest
繼承自 InternalClient.__@captureRejectionSymbol@145