jsdoc也叫文檔注釋，是JS開發(fā)中的一把利器，主要用于為JS添加類型聲明，這樣我們就可以像寫TS一樣寫JS了。

我之前寫過一篇文章，講述了jsdoc的基礎(chǔ)用法。本篇文章，我們來看一個(gè)高級(jí)點(diǎn)的用法。我們來實(shí)現(xiàn)一個(gè)功能：根據(jù)函數(shù)的第一個(gè)參數(shù)，來確定剩余參數(shù)怎么傳。

我想實(shí)現(xiàn)如下函數(shù)，該函數(shù)用于向父窗口發(fā)送消息。它可以接收不確定個(gè)數(shù)的參數(shù)，其中第一個(gè)參數(shù)是eventType，該參數(shù)有固定的幾個(gè)可選值，剩余參數(shù)根據(jù)eventType的值來確定。

const sendEventToParentWindow = (eventType, ...args) => {
  window.postMessage(
    JSON.stringify({ type: eventType, payload: args })
  )
}

首先，我們需要聲明一個(gè)類型

請(qǐng)看如下代碼。其中，@typedef 用于聲明一個(gè)類型，@property 用于聲明該類型包含的字段。

/**
 * @typedef CallEvent
 * @property {[calltype: string, telno: string, callid: string, queid: string, uudata: string]} OnAuthSuccess
 * @property {[calltype: string, telno: string, callid: string, queid: string, uudata: string]} OnCalling
 * @property {[calltype: string, telno: string, callid: string, queid: string, recfile: string, uudata: string]} OnCallConnect
 * @property {[calltype: string]} OnCallHangup
 * @property {[]} changeSeatState
 * @property {[]} changeIVR
 * @property {[]} changeConsult
 * @property {[]} socketConnected
 * @property {[telno: string, exinfo: string]} OnCustomCall
 * @property {[errcode: string]} OnCallReturn
 */

然后，我們來為以上函數(shù)添加類型聲明。

請(qǐng)看如下代碼。其中，@template 用于聲明泛型類型，我們定義了一個(gè)泛型T，它的值取自CallEvent對(duì)象的鍵。@param 用于聲明函數(shù)參數(shù)的類型，eventType的類型為泛型T，args的類型為CallEvent[T]，該類型由T的值決定。這個(gè)聲明，大家都能理解嗎？

/**
 * @template {keyof CallEvent} T
 * @param {T} eventType
 * @param  {CallEvent[T]} args
 */
const sendEventToParentWindow = (eventType, ...args) {}

現(xiàn)在，我們來調(diào)用以上函數(shù)試一試

當(dāng)我們輸入括號(hào)后，編輯器提示我們，該函數(shù)有7種傳參方式。

當(dāng)我們輸入引號(hào)后，編輯器提示出了第一個(gè)參數(shù)期望接收的值。

當(dāng)我們輸入第一個(gè)參數(shù)后，編輯器給出了后面參數(shù)的提示，告訴我們還需5個(gè)參數(shù)，以及每個(gè)參數(shù)期望的類型。

當(dāng)我們將changeIVR作為第一個(gè)參數(shù)時(shí)，編輯器提示我們，后面沒有需要傳的參數(shù)了。

大家說，是不是很酷？JS中很多拼寫錯(cuò)誤都不會(huì)報(bào)錯(cuò)，這增加了排查問題的難度。有了jsdoc，我們的拼寫錯(cuò)誤將大幅減少。由于有了編輯器的智能提示，我們不需要把整個(gè)單詞都敲出來，這樣寫起來更爽了，不是嗎？