@use JSDoc

語法

@event <className>#[event:]<eventName>

概觀

@event 標籤允許您記載可以觸發的事件。典型的事件會由具有已定義屬性集的物件表示。

一旦您使用 @event 標籤定義特定類型的事件，您就可以使用 @fires 標籤指出方法可以觸發該事件。您也可以使用 @listens 標籤指出符號會監聽該事件。

JSDoc 會自動在每個事件名稱前面加上名稱空間 event:。一般來說，當您在其他文件說明中連結到事件時，您必須包含這個名稱空間。（@fires 標籤是一個值得注意的例外；它允許您省略名稱空間。）

注意：JSDoc 3 使用 @event 文件說明記載事件的內容。相反地，JSDoc Toolkit 2 使用 @event 文件說明識別當同名事件發生時可以觸發的函式。

範例

以下範例顯示如何記載 Hurl 類別中稱為 snowball 的事件。該事件包含具有單一屬性的物件。

將函式呼叫記載為事件
/**
 * Throw a snowball.
 *
 * @fires Hurl#snowball
 */
Hurl.prototype.snowball = function() {
    /**
     * Snowball event.
     *
     * @event Hurl#snowball
     * @type {object}
     * @property {boolean} isPacked - Indicates whether the snowball is tightly packed.
     */
    this.emit('snowball', {
        isPacked: this._snowball.isPacked
    });
};
使用命名文件說明記載事件
/**
 * Throw a snowball.
 *
 * @fires Hurl#snowball
 */
Hurl.prototype.snowball = function() {
    // ...
};

/**
 * Snowball event.
 *
 * @event Hurl#snowball
 * @type {object}
 * @property {boolean} isPacked - Indicates whether the snowball is tightly packed.
 */