Аннотирование типов с помощью JSDoc

внешний интерфейс переводчик JavaScript Google

JavaScript использует динамическую типизацию и не проверяет тип во время компиляции. Когда он фактически выполняется, среда выполнения определяет, есть ли ошибка в типе. Эта функция немного похожа на вычисление в ассемблере. Тип очень слабый, и разные типы всегда явные, конвертировать неявно.

В обычном Todo Demo тип может быть не так важен, но когда проект становится огромным, в нем много разной логики, когда проект берет на себя другой человек, читать очень хлопотно, потому что всегда приходится check Тип каждой переменной в контексте кода (пользовательский тип или собственный тип), вообще говоря, вы можете увидеть его во внешнем интерфейсе console.log, но это только временное решение, а не постоянное решение.

Конечно сильно типизированный JavaScript очень зрелый, то есть TypeScript, но не все проекты пишутся на TS с самого начала, а есть и чисто JS проекты, так как же поддерживать тип в этих проектах?

Ответ заключается в использовании JSDoc в VSCode; VSCode сделает все возможное, чтобы определить тип.

Что такое JSDoc

JSDOC фактически является аннотацией кода, в которой может быть указан тип значения в javaScript, а также комментарий к коду, обычно можно увидеть в коде@Метка в начале символа, то есть JSDoc. Вот простой пример

/**
 * 加法
 * @param { Number } x 
 * @param { Number } y 
 * @returns { Number } 
 */
function add(x, y) {
    return x + y; 
}

над@param, @returnsОн определяет тип параметров x y и возвращаемое значение функции.

Ссылаться наVSCode - type-checkingПроверка типов JS может быть включена явно:

打开类型检查可以看到传入其他类型的参数的时候会报错

При включении проверки типов видно, что при передаче параметров других типов будет выдаваться сообщение об ошибке, а после заполнения значения правильного типа VSCode будет знатьzКакой это тип (поскольку x, y - это оба числа, x + y, конечно, тоже число)

Вы также можете реализовать запрос на завершение кода:

代码补全

Основные типы в коде аннотаций

@paramможно получить позжеString Number Array Objectи т.п. Такие как:

/**
 * 
 * @param { Array<Number> } numbers
 * @param { String[] } names
 */
function test(numbers, names) {
    names.forEach(name => {
        // ... 
    })
}

надString[]на самом деле написано сArray<String>Он такой же, он представляет собой массив, элементами которого являются строки, и VSCode также может автоматически дополнять кодforEachметод иnameметод (String.pototype).

И следующий пример представляет пользовательский объект:

/**
 * say hello 
 * @param { { name: String } } person 
 */
function sayHello(person) {
    console.log(person.name); 
}

@paramУказывает тип параметра функции;@returnsУказывает тип функции.

Пользовательский тип выноски

На самом деле, в приведенном выше примере есть описание пользовательского типа (объекта), но приведенный выше пример предназначен для объявления литералов.Теперь давайте представим обработку VSCode классов JavaScript.

class Person {
    /**
     * Person  
     * @param { String } name 
     */
    constructor(name) {
        this.name = name; 
    }

    /**
     * @returns { Person }
     */
    sayHello() {
        console.log('Hello, i am', this.name); 

        return this; 
    }

    /**
     * @param { Person } friend 
     * @returns { Person } 
     */
    playWith(friend) {
        this.sayHello(); 
        console.log('and i will play with', friend.name); 

        return this; 
    }
}

объявлено здесьPersonкласс с методами на немsayHelloесть еще одинnameАтрибуты. С точки зрения VSCode, это тоже тип, который можно использовать как@paramИспользуемые параметры (приведенный выше примерplayWithфункция)

Кстати, синтаксис для аннотаций типов в JSDoc исходит в основном изGoogle Clojure Compileвведите выражение в .

Дженерики (ограничено)

JSDoc также предоставляет определенные возможности.泛型, но этот универсальный тип очень ограничен и далек от настоящего универсального типа.

Вернуться к предыдущему примеруadd(x, y)Если x y ограничен числами, нужно ли для добавления строкового типа x y снова переписывать add? На самом деле нет, вы можете использовать@templateспособ завершить.

/**
 * 加法
 * @template T
 * @param { T } x 
 * @param { T } y 
 * @returns { T }
 */
function add(x, y) {
    return x + y; 
}

представлен здесьT, вы можете понять этот JSDoc так:

  1. xа такжеyТипыT, указывая на то, что их типы одинаковы, как и возвращаемые значения.
  2. если не@templateЧтобы объявить T, тогда VSCode будет думать, что это тип конструктора T, объявление @template здесь указывает, что T является «общим», это специальная переменная, которая используется только для представления типов, а не значений

После использования @template:

Это означает, что типы d и z должны быть переданыVSCodeпониматьaddизJSDocможно вывести позже иTкажется,变量, в указанных двух случаях соответственноstringа такжеnumber.

.d.ts

Существует также метод аннотации типа, который заключается в использовании*.d.tsфайл, обычно обычные библиотеки JavaScript не аннотированы по типам, что будет несовместимо с проверкой типов в TypeScript, поэтому его необходимо импортироватьd.tsТипы, используемые для описания библиотек js, которые может использовать ts.

Конечно, VSCode может его прочитать и облегчить разработку. Напишите test.js:

/**
 * @param { Person } p
 */
function test(p) {
    
}

Затем напишите описание типа Persontest.d.ts

declare interface Person {
    name: string, 
    age?: number, 
    sayHello: () => Person, 
    playWith: (friend: Person) => Person
}

Примечание. Знак вопроса в поле возраста означает, что возраст указывать необязательно.

* .D.ts VSCode Затем найдите и прочитайте файл, получите информацию:

d.ts

Ссылка на ссылку

http://www.css88.com/doc/jsdoc/about-block-inline-tags.html https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#type-expressions https://code.visualstudio.com/Docs/languages/javascript#_type-checking https://zh.wikipedia.org/wiki/JavaScript

Категории