Skip to main content

Directive Comments

Directives​

在TypeScript中，可接收一些注释指令，采用JavaScript双斜杠注释的形式，向TypeScript编译器发出相关指令以执行对应的类型检查程序。这些指令可以以注释的形式书写在代码中，在编译过程中会被TypeScript编译器解析和处理。

@ts-check​

如果一个JavaScript脚本即.js文件顶部添加了// @ts-check，那么编译器将对该脚本进行类型检查。即使它没有显式的使用 .ts 或 .tsx 扩展名，也不管是否启用了checkJs编译选项。

// @ts-check

let isCheck = false;

// Type 'number' is not assignable to type 'boolean'.
isCheck = 1

@ts-nocheck​

该指令告诉TypeScript编译器不对当前脚本进行类型检查，可以用于TypeScript脚本，也可以用于JavaScript脚本。

// @ts-nocheck

let isCheck = false;
// here is no error
isCheck = 1;

@ts-ignore​

该指令告诉 TypeScript 编译器忽略下一行或下一段代码的类型检查错误，这可以用来暂时性地关闭某些类型检查错误的提示。TypeScript和JavaScript脚本均可使用。

let x = true

// @ts-ignore
x = 1;

@ts-expect-error​

该指令标记下一行或下一段代码应该触发一个类型错误。如果下一行有类型错误时，它会压制 TypeScript 的报错信息，把错误留给代码自己处理，主要用在测试用例中。

function doStuff(abc: string, xyz: string) {
  assert(typeof abc === "string");
  assert(typeof xyz === "string");
  // do some stuff
}

// @ts-expect-error
expect(() => {
	// error wanto to test
  doStuff(123, 456);
}).toThrow();

JSDoc​

JSDoc是一种用于JavaScript的文档注释标准。它提供了一种结构化的方式来描述代码的功能、参数、返回值以及其他重要信息，以便开发人员和工具能够理解和生成文档。JSDoc注释通常是以特殊的注释语法编写的，其目的是为了生成有关代码的文档。

TypeScript在直接处理JavaScript文件时，如果无法推断出类型，则会使用 JavaScript脚本里面的 JSDoc 注释。目前，大部分编译器都支持JSDoc的大部分声明。

在使用JSDoc时，需要遵守以下格式：

  • JSDoc 注释必须以/**开始，其中星号（*）的数量必须为两个。若使用其他形式的多行注释，则 JSDoc 会忽略该条注释。
  • JSDoc注释必须与它描述的代码处于相邻的位置，注释在上，代码在下。
/**
 * @param {string} user 
 */
function sayHello(user) { }

@typedef​

创建自定义类型，相当于TypeScript里面的类型别名type。

/**
 * @typedef {(number | string)} NumberLike
 */

/**
 * @type { NumberLike }
 */
var numberOrString;

@type​

定义变量的类型，其值可以是：

  • 原始类型，如string、number
  • TypeScript声明的类型，全局或导入的类型
  • 声明在@typedef中的类型
/**
 * @type {string | number}
 */
var s;

/**
 * @type {Window}
 */
var win;

/**
 * @type {Promise<number>}
 */
var promiseNumber;

/**
 * @type {HTMLElement}
 */
var ele = document.getElementById('#root');

// types.d.ts
export type Pet = {
    name: string
}

/**
 * @type {import('./types.d.ts').Pet}
 */
var p;

/**
 * @typedef {import('./types').Pet} Pet
 */
/**
 * @type {Pet}
 */
var p1

@param​

定义函数参数的类型，同时可使用可选参数、默认值等。

/**
 * @param {string}  x
 */
function foo(x) {}

// 可选参数
/**
 * @param {string}  [x]
 */
function foo(x) {}

// 默认值
/**
 * @param {string}  [x='100']
 */
function foo(x) {}

@returns​

指定函数返回值的类型

/**
 * @param {string}  x
 * @returns {void}
 */
function foo(x) {}

/**
 * @param {string}  [x]
 * @returns {boolean}
 */
function foo(x) {}

更多命令可参考JSDoc Reference

Last updated on