前端笔记 Front-end Dev Engineer

在无ts环境时，进行类型注释

2021-08-28
JavaScript
   

Typescript非常好用，类型提示也非常棒，但是有的时候，必须只能使用js，所以我们使用jsdoc来对js代码进行注释，也能获得一些类型帮助

typescriptlang

通用的JSDoc

基础类型

类型其实就是ts的类型，常见以下类型

  • boolean 布尔类型
  • string 字符串类型
  • number 数字类型
  • xxx[]或Array<xxx> 数组类型
  • any 任意类型
  • unknown 未知的任意类型
  • void 无返回
  • undefined undefined类型
  • null null类型
  • Never 从不存在

以下是使用案例代码

/** @type {boolean} 一个布尔值 */
var a = true
/** @type {string}  字符串值 */
var b = ''
/** @type {number} 数字类型 */
var c = 1
/** @type {number[]} 数字数组 */
var d = [1,2,3,4]
/** @type {any} 任意类型 */
var e = {a:true,b:'',c:1}
/** 
 * 一个示例函数f
 * @param {unknown} a 未知类型的参数
 * @returns {null} 返回值为null
 */
var f = (a)=>null
/** 
 * 一个示例函数g
 * @returns {void} 没有返回值
 */
var g = ()=>{ console.log(0) }

其他常见类型

其他一些相对特殊一点的类型

  • 函数类型: 例如 (a:number,b:number)=>number
  • 对象类型: 例如 {[key:string]:any}
  • 复合类型: 例如 '1'|'2'|'3'
/** @type {(a:number,b:number)=>number} 求和方法 */
var a;

a = (num1,num2)=>num1+num2

/** 
 * 求和
 * @param {number} num1 被加数
 * @param {number} num2 加数
 * @returns {number} 和 
 */
var b = (num1,num2)=>num1+num2

/** @type  不知道类型的 */
var c = {}

/** 
 * 获取对应状态的标题 
 * @param {1|2|3} state 状态
 * @returns {'新建'|'编辑'|'详情'} 返回的标题
 */
var getTitle=(state)=>{
    if(state===0){
        return '新建'
    }

    if(state===1){
        return '编辑'
    }

    if(state===2){
        return '详情'
    }
}

interface的替代写法

interface是ts中的接口,可以简单的理解为就是对象的类型

a.ts文件

/** 自定义接口Obj */
export interface Obj {
    /** 布尔值类型a */
    a:boolean;
    /** 字符串类型b */
    b:string;
    /** 可选的数字类型c */
    c?:number;
}

a.js文件

/** 
 * @typedef Obj 自定义接口Obj
 * @property {boolean} a 布尔值类型a
 * @property {string} b 字符串类型b
 * @property {number=} c 可选的数字类型c
 */

/** @type {Obj} 某个对象 */
var obj = {a:true,b:'',c:1}

b.js文件

/** @type {import('./a.js').Obj} 某个对象 */
var obj2 = {a:false,b:'bbb'}

/** @type {import('./a.ts').Obj} 某个对象 */
var obj3 = {a:false,b:'ccc',c:2}

泛型

/**
 * @template T
 * @typedef ABC<T=any> 类型abc
 * @property {string} a 字符串a
 * @property {number=} b 数字b
 * @property {T[]=} c 任意数组c
 */

/** @type {ABC<number>} 某个对象abc */
export var abc = {
    a:'1',
    b:1,
    c:[1]
}


/**
 * @template T
 * @callback ForEachCallBack 遍历
 * @param {number} key 数组的序号
 * @param {T} value 数组的值
 * @returns {void}
 */

 /**
  * 显示单位
  * @template T
  * @param {T[]} arr 求和
  * @param {ForEachCallBack<T>} callback 计量单位字符串
  */
 var forEach=(arr,callback)=>{
     var len = arr.length;
     for(var i=0;i<len;i+=1){
        callback&&callback(i,arr[i])
     }
 }

 forEach([1,2,3],function(key,val){
     console.log(key,val)
 })

几种特殊关键词

types-from-types

ts还提供几个特殊的关键词

  • keyof
  • typeof

var obj = {a:true,b:'',c:1}

/** @type { keyof typeof obj } */
var key = 'a' // 类型只能是 "a" | "b" | "c"

几个ts提供的泛型

ts提供的几个类型,可以在jsdoc中,使用

utility-types

  • Partial 部分类型
  • Required 部分类型的对立面
  • Readonly 只读类型
  • Record<Keys,Type> 约束对象的值
  • Pick<Type, Keys> 需要对象中指定的部分
  • Omit<Type, Keys> 需要对象中,除指定之外的部分
  • Exclude<Type, ExcludedUnion> 排除后面中存在的类型
  • Extract<Type, Union> 只要后面中存在的类型
  • NonNullable 排除null、undefined
  • Parameters 获取函数的参数类型

针对vue的注释

vue单文件，只是一个普通对象，针对几个特殊的属性，需要特殊注释

import { PropType } from 'vue'

/** 
 * @typedef Obj 自定义接口Obj
 * @property {boolean} a 布尔值类型a
 * @property {string} b 字符串类型b
 * @property {number=} c 可选的数字类型c
 */

export default {
    prop:{
        /** @type {PropType<Obj>} 某个传入变量 */
        abc:{
            type:Object,
            default:()=>({})
        }
    },
    computed:{
        /** @returns {number} 计算后的数值 */
        ccc(){
            return this.abc.c + 1
        }
    },
    data(){
        return {}
    }
}

对于vuex的计算属性的注释，暂时无解

注释符号的建议

/** */: 用于变量的注释 /* */: 用于普通的多行注释 //: 单行的业务逻辑注释 // TODO: 打算做，还还未作的注释

总结

js中的类型注释，没有ts那么丰富，但是大部分的类型注释都是可以有的，为了提高代码的可读性，建议进行注释

评论

Content