眾所周知的原因，由于JS的語言特性，任何開發工具都不能為JS提供足夠好的智能提示，正因為此，微軟創造的輪子：typescript，橫空出世！
那么，有沒有一種不用typescript的解決方案呢？有，那就是今天的主角：jsdoc；這可能是一個大家很少使用的開發利器；它是一個可以使你像寫typescript一樣寫JavaScript；沒錯，jsdoc主要就是用來給js添加類型信息的。
下面我們看一個簡單的函數，這個函數接收一個參數modalElement，由于編輯器不知道它是什么類型，所以在調用它的querySelector方法的時候，無法獲得編輯器的智能提示；同樣地，編輯器也無法給出btnClose的click方法的智能提示。
const closeModal = modalElement => {
if (modalElement) {
const btnClose = modalElement.querySelector('.el-dialog__close')
if (btnClose) {
btnClose.click()
return true
}
}
}這時候，就該jsdoc出場了；它的語法需要寫在多行注釋中，因為它不屬于js語法的一部分；我們只需給modalElement和btnClose增加一個類型標注，編輯器就知道它們是什么類型，擁有什么能力了；
為函數參數指定類型，使用@param標記，語法：@param {類型} 參數名；為變量指定類型，使用@type標記，語法：@type {類型}；代碼如下：
/** @param {HTMLDivElement} modalElement */
const closeModal = modalElement => {
if (modalElement) {
/** @type {HTMLLinkElement} */
const btnClose = modalElement.querySelector('.el-dialog__close')
if (btnClose) {
btnClose.click()
return true
}
}
}現在，當我們把指針移入modalElement的時候，就不是一個簡單的any類型了，編輯器可以根據文檔注釋確定它是HTMLDivElement類型，我們在調用它的querySelector方法的時候就能得到編輯器的智能提示；當我們把指針移入click的時候，編輯器告訴我們，這個方法是從HTMLElement繼承來的。
@returns標注用于指定函數返回值數據類型；語法：@returns {類型}；如下函數返回由HTMLDivElement構成的數組。
/** @returns {HTMLDivElement[]} */
const getAllModals = () => {
return Array.from(
document.body.querySelectorAll('.el-dialog__wrapper, .el-drawer__wrapper')
).filter(_ => {
return window.getComputedStyle(_, null).display !== 'none'
})
}如下圖，當我們調用getAllModals函數返回值的reduce方法的時候，編輯器可以給出智能提示。
我們還可以使用@typedef標記自定義類型；語法：import('模塊路徑')，用于從模塊中導入TS類型定義；&符號用于合并2個類型；如下例子定義了一個名叫RouteConfig的類型，該類型在import('vue-router').RouteConfig的基礎上為meta字段增加了number類型的index字段。
/**
* @typedef {import('vue-router').RouteConfig & {meta: { index: number }}} RouteConfig
*/
如下例子定義了一個EntAccountInfo類型，包含2個字段：數值類型的id和字符串類型的password。
/**
* @typedef {{id: number, password: string}} EntAccountInfo
*/
如果我們的字段比較多，可以使用@property標記定義每個字段。
/**
* @typedef UserData 用戶數據
* @property {any} entid 租戶id
* @property {string} name 姓名
* @property {string} workNo 工號
* @property {string} userId 用戶id
* @property {string} username 登錄用戶名
*/
我們自定義的類型和內置類型用法完全一樣；請看下面例子，包含內置類型和我們上面創建的自定義類型；我們在給對象字段指定類型的時候，可以有2種寫法：寫在字段名前面或上面；大家覺得哪種風格優雅？
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: {}
})我們可以使用管道符為一個變量指定多個可能的類型，請看如下例子，當用戶調用該函數的時候，編輯器會提示該函數期望接收一個類型為日期或字符串或數值的參數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
}如果我們的函數有不限個數的參數，可以使用語法：@param {...類型} 參數名，指定參數類型；請看如下例子：
/** @param {...string} paths */
export const getApiUrl = (...paths) => joinPath(API_BASE, ...paths)不限參數個數的函數，還有更高級的類型標注寫法；請看如下代碼，formRequest是一個axios的實例，我們想每次發起post請求的時候少寫10來個字符，定義了一個post函數，直接返回了對formRequest的post方法調用。
export const post = (...args) => formRequest.post(...args)
通過編輯器的提示，我們得知axios的post方法有3個不同類型的參數；而我們為了省事，使用了展開運算符，不管傳入多少個參數，全部仍給axios實例的post方法；那么，參數類型該如何標注呢？
我們可以使用中括號語法為每個參數指定字段名和類型，例子如下：
/** @param {[url: string, data?: any, config?: RequestConfig]} args */
export const post = (...args) => formRequest.post(...args)下圖是當指針移入post函數上時，編輯器給出的提示；是不是很酷？
如下是RequestConfig的類型定義，我們擴展了AxiosRequestConfig，為其增加了2個布爾類型字段；現在當我們調用post函數的時候，編輯器就會知道我們的第3個參數config包含這2個布爾類型字段。
/**
* @typedef {import('axios').AxiosRequestConfig & { needAuth: boolean, saveToken: boolean }} RequestConfig
*/
jsdoc還可以定義泛型類型，語法：@template 泛型名；請看如下例子，TreeNode是一個泛型類型，我們唯一能確定的是它有一個children字段；它具體還包含哪些字段，由泛型T決定。
/**
* @template T
* @typedef {T & {children: TreeNode[]}} TreeNode
*/
我們還可以在函數類型標注中使用泛型，請看如下例子，我們定義了一個泛型T，參數data為泛型T數組，返回值為泛型類型TreeNode<T>構成的數組。
/**
* @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用法，還有很多用法沒有涉及到；篇幅有限，大家可以去官網查看文檔；希望該文章能助大家的JS技術更上一層樓，感謝閱讀！
