支援JSDoc

下面的列表概述了使用JSDoc註釋在JavaScript檔案中提供型別資訊時當前支援的構造。

請注意，尚不支援下面未明確列出的任何標記（例如@async）。

含義通常與usejsdoc.org上給出的標記含義相同或超​​集。下面的程式碼描述了這些差異，並給出了每個標記的一些示例用法。

@type

您可以使用”@type“標記並引用型別名稱（原語，在TypeScript宣告中定義，或在JSDoc”@typedef“標記中）。您可以使用任何Typescript型別和大多數JSDoc型別。

/**
 * @type {string}
 */
var s;

/** @type {Window} */
var win;

/** @type {PromiseLike<string>} */
var promisedString;

// You can specify an HTML Element with DOM properties
/** @type {HTMLElement} */
var myElement = document.querySelector(selector);
element.dataset.myData = '';
 

@type可以指定聯合型別 - 例如，某些東西可以是字串或布林值。

/**
 * @type {(string | boolean)}
 */
var sb;

請注意，括號對於聯合型別是可選的。

/**
 * @type {string | boolean}
 */
var sb;

您可以使用各種語法指定陣列型別：

/** @type {number[]} */
var ns;
/** @type {Array.<number>} */
var nds;
/** @type {Array<number>} */
var nas;

您還可以指定物件文字型別。例如，具有屬性’a’（字串）和’b’（數字）的物件使用以下語法：

/** @type {{ a: string, b: number }} */
var var9;

您可以使用標準JSDoc語法或Typescript語法，使用字串和數字索引簽名指定類似地圖和類似陣列的物件。

/**
 * A map-like object that maps arbitrary `string` properties to `number`s.
 *
 * @type {Object.<string, number>}
 */
var stringToNumber;

/** @type {Object.<number, object>} */
var arrayLike;
 

前兩種型別等同於Typescript型別{ [x: string]: number }和{ [x: number]: any }。編譯器理解這兩種語法。

您可以使用Typescript或Closure語法指定函式型別：

/** @type {function(string, boolean): number} Closure syntax */
var sbn;
/** @type {(s: string, b: boolean) => number} Typescript syntax */
var sbn2;

或者您可以使用未指定的函式型別：

/** @type {Function} */
var fn7;
/** @type {function} */
var fn6;

Closure的其他型別也有效：

/**
 * @type {*} - can be 'any' type
 */
var star;
/**
 * @type {?} - unknown type (same as 'any')
 */
var question;

型別轉換

Typescript借用了Closure的強制語法。這允許您通過在任何帶括號的表示式之前新增@type標記將型別轉換為其他型別。

/**
 * @type {number | string}
 */
var numberOrString = Math.random() < 0.5 ? "hello" : 100;
var typeAssertedNumber = /** @type {number} */ (numberOrString)

匯入型別

您還可以使用匯入型別從其他檔案匯入宣告。此語法是特定於Typescript的，與JSDoc標準不同：

/**
 * @param p { import("./a").Pet }
 */
function walk(p) {
    console.log(`Walking ${p.name}...`);
}

匯入型別也可以在類型別名宣告中使用：

/**
 * @typedef Pet { import("./a").Pet }
 */

/**
 * @type {Pet}
 */
var myPet;
myPet.name;

如果你不知道型別，或者它有一個令人討厭的大型型別，可以使用import型別從模組中獲取值的型別：

/**
 * @type {typeof import("./a").x }
 */
var x = require("./a").x;

未完待續…