眾所周知的原因，由于JS的語(yǔ)言特性，任何開發(fā)工具都不能為JS提供足夠好的智能提示，正因?yàn)榇耍④泟?chuàng)造的輪子：typescript，橫空出世！

那么，有沒有一種不用typescript的解決方案呢？有，那就是今天的主角：jsdoc；這可能是一個(gè)大家很少使用的開發(fā)利器；它是一個(gè)可以使你像寫typescript一樣寫JavaScript；沒錯(cuò)，jsdoc主要就是用來(lái)給js添加類型信息的。

下面我們看一個(gè)簡(jiǎn)單的函數(shù)，這個(gè)函數(shù)接收一個(gè)參數(shù)modalElement，由于編輯器不知道它是什么類型，所以在調(diào)用它的querySelector方法的時(shí)候，無(wú)法獲得編輯器的智能提示；同樣地，編輯器也無(wú)法給出btnClose的click方法的智能提示。

const closeModal = modalElement => {
  if (modalElement) {
    const btnClose = modalElement.querySelector('.el-dialog__close')
    if (btnClose) {
      btnClose.click()
      return true
    }
  }
}

這時(shí)候，就該jsdoc出場(chǎng)了；它的語(yǔ)法需要寫在多行注釋中，因?yàn)樗粚儆趈s語(yǔ)法的一部分；我們只需給modalElement和btnClose增加一個(gè)類型標(biāo)注，編輯器就知道它們是什么類型，擁有什么能力了；

為函數(shù)參數(shù)指定類型，使用@param標(biāo)記，語(yǔ)法：@param {類型} 參數(shù)名；為變量指定類型，使用@type標(biāo)記，語(yǔ)法：@type {類型}；代碼如下：

/** @param {HTMLDivElement} modalElement */
const closeModal = modalElement => {
  if (modalElement) {
    /** @type {HTMLLinkElement} */
    const btnClose = modalElement.querySelector('.el-dialog__close')
    if (btnClose) {
      btnClose.click()
      return true
    }
  }
}

現(xiàn)在，當(dāng)我們把指針移入modalElement的時(shí)候，就不是一個(gè)簡(jiǎn)單的any類型了，編輯器可以根據(jù)文檔注釋確定它是HTMLDivElement類型，我們?cè)谡{(diào)用它的querySelector方法的時(shí)候就能得到編輯器的智能提示；當(dāng)我們把指針移入click的時(shí)候，編輯器告訴我們，這個(gè)方法是從HTMLElement繼承來(lái)的。

@returns標(biāo)注用于指定函數(shù)返回值數(shù)據(jù)類型；語(yǔ)法：@returns {類型}；如下函數(shù)返回由HTMLDivElement構(gòu)成的數(shù)組。

/** @returns {HTMLDivElement[]} */
const getAllModals = () => {
  return Array.from(
    document.body.querySelectorAll('.el-dialog__wrapper, .el-drawer__wrapper')
  ).filter(_ => {
    return window.getComputedStyle(_, null).display !== 'none'
  })
}

如下圖，當(dāng)我們調(diào)用getAllModals函數(shù)返回值的reduce方法的時(shí)候，編輯器可以給出智能提示。

我們還可以使用@typedef標(biāo)記自定義類型；語(yǔ)法：import('模塊路徑')，用于從模塊中導(dǎo)入TS類型定義；&符號(hào)用于合并2個(gè)類型；如下例子定義了一個(gè)名叫RouteConfig的類型，該類型在import('vue-router').RouteConfig的基礎(chǔ)上為meta字段增加了number類型的index字段。

/**
 * @typedef {import('vue-router').RouteConfig & {meta: { index: number }}} RouteConfig
 */

如下例子定義了一個(gè)EntAccountInfo類型，包含2個(gè)字段：數(shù)值類型的id和字符串類型的password。

/**
 * @typedef {{id: number, password: string}} EntAccountInfo
 */

如果我們的字段比較多，可以使用@property標(biāo)記定義每個(gè)字段。

/**
 * @typedef UserData 用戶數(shù)據(jù)
 * @property {any} entid 租戶id
 * @property {string} name 姓名
 * @property {string} workNo 工號(hào)
 * @property {string} userId 用戶id
 * @property {string} username 登錄用戶名
 */

我們自定義的類型和內(nèi)置類型用法完全一樣；請(qǐng)看下面例子，包含內(nèi)置類型和我們上面創(chuàng)建的自定義類型；我們?cè)诮o對(duì)象字段指定類型的時(shí)候，可以有2種寫法：寫在字段名前面或上面；大家覺得哪種風(fēng)格優(yōu)雅？

export const state = Vue.observable({
  /** @type {string[]} */ keeps: [],
  /** @type {RouteConfig[]} */ menus: [],
  /** @type {EntAccountInfo} */ entInfo: {},
  /** @type {UserData} */ userData: {},
})

export const state = Vue.observable({
  /** @type {string[]} */
  keeps: [],
  /** @type {RouteConfig[]} */
  menus: [],
  /** @type {EntAccountInfo} */
  entInfo: {},
  /** @type {UserData} */
  userData: {}
})

我們可以使用管道符為一個(gè)變量指定多個(gè)可能的類型，請(qǐng)看如下例子，當(dāng)用戶調(diào)用該函數(shù)的時(shí)候，編輯器會(huì)提示該函數(shù)期望接收一個(gè)類型為日期或字符串或數(shù)值的參數(shù)time。

/** @param {Date | string | number} time */
export const getHalfYearAfterTime = time => {
  const date = new Date(time)
  date.setMonth(date.getMonth() + 6)
  date.setDate(date.getDate() - 1)
  return date
}

如果我們的函數(shù)有不限個(gè)數(shù)的參數(shù)，可以使用語(yǔ)法：@param {...類型} 參數(shù)名，指定參數(shù)類型；請(qǐng)看如下例子：

/** @param  {...string} paths */
export const getApiUrl = (...paths) => joinPath(API_BASE, ...paths)

不限參數(shù)個(gè)數(shù)的函數(shù)，還有更高級(jí)的類型標(biāo)注寫法；請(qǐng)看如下代碼，formRequest是一個(gè)axios的實(shí)例，我們想每次發(fā)起post請(qǐng)求的時(shí)候少寫10來(lái)個(gè)字符，定義了一個(gè)post函數(shù)，直接返回了對(duì)formRequest的post方法調(diào)用。

export const post = (...args) => formRequest.post(...args)

通過(guò)編輯器的提示，我們得知axios的post方法有3個(gè)不同類型的參數(shù)；而我們?yōu)榱耸∈拢褂昧苏归_運(yùn)算符，不管傳入多少個(gè)參數(shù)，全部仍給axios實(shí)例的post方法；那么，參數(shù)類型該如何標(biāo)注呢？

我們可以使用中括號(hào)語(yǔ)法為每個(gè)參數(shù)指定字段名和類型，例子如下：

/** @param  {[url: string, data?: any, config?: RequestConfig]} args */
export const post = (...args) => formRequest.post(...args)

下圖是當(dāng)指針移入post函數(shù)上時(shí)，編輯器給出的提示；是不是很酷？

如下是RequestConfig的類型定義，我們擴(kuò)展了AxiosRequestConfig，為其增加了2個(gè)布爾類型字段；現(xiàn)在當(dāng)我們調(diào)用post函數(shù)的時(shí)候，編輯器就會(huì)知道我們的第3個(gè)參數(shù)config包含這2個(gè)布爾類型字段。

/**
 * @typedef {import('axios').AxiosRequestConfig & { needAuth: boolean, saveToken: boolean }} RequestConfig
 */

jsdoc還可以定義泛型類型，語(yǔ)法：@template 泛型名；請(qǐng)看如下例子，TreeNode是一個(gè)泛型類型，我們唯一能確定的是它有一個(gè)children字段；它具體還包含哪些字段，由泛型T決定。

/**
 * @template T
 * @typedef {T & {children: TreeNode[]}} TreeNode
*/

我們還可以在函數(shù)類型標(biāo)注中使用泛型，請(qǐng)看如下例子，我們定義了一個(gè)泛型T，參數(shù)data為泛型T數(shù)組，返回值為泛型類型TreeNode<T>構(gòu)成的數(shù)組。

/**
 * @template T
 * @param {T[]} data
 * @param {{key: string, parentId: string}} config
 * @returns {TreeNode<T>[]}
 */
export const toTree = (data, config) => {
  const { key = 'id', parentId: pId = 'parentId' } = config || {}
  const ids = data.map(_ => _[key])
  /** @type {TreeNode<T>[]} */
  const result = []
  // ... ...
  return result
}

以上就是我工作中最常用的jsdoc用法，還有很多用法沒有涉及到；篇幅有限，大家可以去官網(wǎng)查看文檔；希望該文章能助大家的JS技術(shù)更上一層樓，感謝閱讀！