使用 TS 声明文件+JSDoc 对 es 项目提供智能提示

3,307 阅读2分钟

背景:最近做的内部使用的管理系统,使用es6 构建,之前一直使用 typescript 构建项目,感觉到写声明文件真的很烦很浪费时间。这次使用es6构建项目,发现效率更低,没有智能提示浪费的时间比写声明文件的多了好几倍。

VS Code 对 JavaScript 项目的支持

VS Code 编辑器通过 jsconfig.js(ts 项目是 tsconfig.js)对 JavaScript 项目提供支持type-checking-javascript-files

配置项

// 根目录:jsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "node",
    "module": "es2015",
    "target": "es6",
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "exclude": ["node_modules", "dist"],
  "include": ["src/**/*", "types"]
}

支持的 jsdoc 类型

请仔细阅读支持的 jsdoc 类型supported-jsdoc

使用 ts 声明的方式书写 jsdoc

copy 官方例子

// type和类型转换,复杂的格式我还是喜欢写到d.ts文件里面
/**
 * @type {number | string}
 */
var numberOrString = Math.random() < 0.5 ? "hello" : 100;
var typeAssertedNumber = /** @type {number} */ (numberOrString)

// 对象
/**
 * @type { {id: number, name: string} }
 */
var user = {
  id: 123,
  name: '张三'
}

// 函数
/**
 * @type { (params: any) => Promise }
 */
var fn = (params) => {
  return Promise((reslove, reject) => {
    // ...
  })
}

导入类型(import types)

typescript 支持在 jsdoc 的注释中导入 ts declaration file 的类型声明 import-types

完整的例子

github.com/betgar/jsdo…

// src/types/index.d.ts
import { AxiosPromise } from "axios";

export declare interface ResponseData<T = any> {
  code: number;
  message: string;
  data: T;
}

/**
 * 返回的数据格式.
 */
export interface AjaxPromise<T = any>
  extends AxiosPromise<ResponseData<T>> {}

export  interface LoginParams {
  account: string;
  password: string;
}

export interface UserModel {
  account: string
  nickname: string
  id: string | number
  role: any
  extraProps: any
}

// src\api\modules\LoginApi.js

/**
 * login
 * @param { import('@/types').LoginParams } data
 * @return { import('@/types').AjaxPromise<import('@/types').UserModel> }
 */
export function login (data) {
  return Axios.post('/api/login', data)
}

// src\common\login\services\index.js

/**
 * loginService
 * @param { import('@/types').LoginParams } data - 数据
 * @returns { Promise<import('@/types').UserModel> }
 */
export function loginService (data) {
  // 可以做一些参数的校验
  // 和其它services的组合
  // 数据结构的转换
  return login(data).then(res => {
    const { data: { data: user } } = res
    console.log(user)
    console.log(user.account)
    return loginTransformer.transformOne(user)
  })
}

// src\main.js
// Vue中的调用
const rootVue = new Vue({
  created () {
    loginService({
      account: '123',
      password: '1231'
    }).then(this.$apiResolver).catch(this.$apiRejecter)
  }
})

参考

JavaScript 文件类型检查

jsconfig.json 配置

javascript in vs code

检查 JavaScript 文件

TypeScript 支持的 JSDoc