Как типизировать с TypeScript?
2 года назад·14 мин. на чтение
В этой статье рассмотрим самые популярные типы, которые используются в JavaScript коде, и объясним способы описания этих типов в TypeScript.
Мы начнем с обзора самых основных и распространенных типов, с которыми вы можете столкнуться при написании JavaScript или TypeScript кода. Позже они сформируют основные строительные блоки для более сложных типов.
Примитивы:
В JavaScript есть три очень часто используемых примитива:
Тип
TypeScript также имеет специальный тип
Когда вы не указываете тип и TypeScript не может вывести его из контекста, компилятор обычно по умолчанию использует тип
В JavaScript есть два примитивных значения, которые используются для обозначения отсутствия или неинициализации значения:
Если
При включении strictNullChecks, когда значение равно
Оператор ненулевого утверждения (Non-null Assertion Operator, постфикс
TypeScript также имеет специальный синтаксис для удаления
Начиная с ES2020, в JavaScript есть примитив, используемый для очень больших целых чисел,
В JavaScript есть примитив, используемый для создания глобальной уникальной ссылки с помощью функции
Примитивы: string
, number
, boolean
В JavaScript есть три очень часто используемых примитива: string
, number
и boolean
. У каждого есть соответствующий тип в TypeScript. Как и следовало ожидать, это те же самые имена, которые вы увидели бы, если бы использовали оператор JavaScript typeof
для значений этих типов:
string
представляет строковые значения, такие как"Hello, world"
number
для чисел вроде42
. В JavaScript нет различий между целочисленными значениями и значениями с плавающей точкой, поэтому нет эквивалентаint
илиfloat
— все простоnumber
boolean
для двух значенийtrue
иfalse
String
, Number
и Boolean
(начинающиеся с заглавных букв) допустимы, но относятся к некоторым специальным встроенным типам, которые очень редко встречаются в коде. Всегда используйте типы string
, number
или boolean
.
Типизация массивов
Чтобы указать тип массива, например[1, 2, 3]
, вы можете использовать синтаксис number[]
; этот синтаксис работает для любого типа (например, string[]
— это массив строк и т.д.). Вы также можете встретить синтаксис Array<number>
, что означает то же самое.
Обратите внимание, что [number]
— это не массив чисел, а кортеж (tuple).
Тип any
TypeScript также имеет специальный тип any
, который вы можете использовать всякий раз, когда вы не хотите, чтобы определенное значение вызывало ошибки проверки типов.
Когда значение имеет тип any
, вы можете получить доступ к любым его свойствам (которые, в свою очередь, будут иметь тип any
), вызвать его как функцию, присвоить ему значения любого типа или почти все что угодно. Это валидный синтаксис:
Типlet obj: any = { x: 0 }; // Ни одна из следующих строк кода не вызовет ошибок компилятора. // Использование any отключает все дальнейшие проверки типов и предполагается, что // вы знаете эти сценарии лучше, чем TypeScript. obj.foo(); obj(); obj.bar = 100; obj = 'hello'; const n: number = obj;
any
полезен, когда вы не хотите записывать длинный тип. Тип any
нужен только для того, чтобы убедить TypeScript в том, что конкретная строка кода валидна.
noImplicitAny
Когда вы не указываете тип и TypeScript не может вывести его из контекста, компилятор обычно по умолчанию использует тип any
.
Обычно этого следует избегать, потому что тип any
не проверяется. Используйте флаг компилятора noImplicitAny
, чтобы пометить любое неявное значение any
как ошибку.
Аннотации типов переменных
Когда вы объявляете переменную с помощьюconst
, var
или let
, вы можете дополнительно добавить аннотацию типа, чтобы явно указать тип переменной:
TypeScript не использует объявления в стиле «типы слева», такие какlet myName: string = 'Alice';
int x = 0;
Аннотации типа всегда будут находится после.
Однако в большинстве случаев в этом нет необходимости. Везде, где это возможно, TypeScript пытается автоматически определить типы в вашем коде. Например, тип переменной выводится на основе типа ее инициализатора:
По большей части вам не нужно явно изучать правила вывода. Если вы только начинаете, попробуйте использовать меньше аннотаций типов — вы удивитесь, как мало нужно для TypeScript, чтобы он понимал, что происходит.// Аннотации типа не требуются — тип 'myName' выводится как 'string' let myName = 'Alice';
Как типизировать функции в TypeScript?
Функции — это основное средство для работы с данными в JavaScript. TypeScript позволяет указывать типы как входных, так и выходных значений функций.Аннотации типов параметров
Когда вы объявляете функцию, вы можете добавить аннотации типа после каждого параметра, чтобы объявить, какие типы параметров принимает функция. Аннотации типа параметра идут после имени параметра:Когда параметр имеет аннотацию типа, будут проверены аргументы этой функции:// Аннотация типа параметра function greet(name: string) { console.log('Hello, ' + name.toUpperCase() + '!!'); }
Даже если вы не указали аннотации типов для параметров, TypeScript все равно проверит, что вы передали правильное количество аргументов.// При вызове возникнет ошибка времени выполнения greet(42); // Argument of type 'number' is not assignable to parameter of type 'string'.
Аннотации типа возвращаемого значения
Вы также можете добавить аннотации типа возвращаемого значения. Аннотации типа возвращаемого значения добавляется после списка параметров:Подобно аннотациям типа переменной, вам обычно не нужна аннотация типа возвращаемого значения, потому что TypeScript будет делать вывод о типе возвращаемого значения функции на основе ее оператораfunction getFavoriteNumber(): number { return 26; }
return
. Аннотация типа в приведенном выше примере ничего не меняет. Некоторые кодовые базы явно указывают тип возвращаемого значения для документирования, для предотвращения случайных изменений или просто из-за личных предпочтений.
Анонимные функции
Анонимные функции немного отличаются от объявлений обычных функций. Когда функция появляется в месте, где TypeScript может определить, как она будет вызываться, параметрам этой функции автоматически присваиваются типы. Например:Несмотря на то, что у параметра// Здесь нет аннотаций типов, но TypeScript может обнаружить ошибку const names = ['Alice', 'Bob', 'Eve']; // Определение типа на основе контекста names.forEach(function (s) { console.log(s.toUppercase()); // Property 'toUppercase' does not exist on type 'string'. Did you mean 'toUpperCase'? // В типе 'string' нет свойства 'toUppercase'. Возможно, вы имели ввиду 'toUpperСase'? }); // Определение типа на основе контекста вызова функции также работает и для стрелочных функций names.forEach((s) => { console.log(s.toUppercase()); // Property 'toUppercase' does not exist on type 'string'. Did you mean 'toUpperCase'? // В типе 'string' нет свойства 'toUppercase'. Возможно, вы имели ввиду 'toUpperСase'? });
s
не было аннотации типа, TypeScript использовал типы функции forEach
вместе с предполагаемым типом массива, чтобы определить тип, который будет иметь s
.
Этот процесс называется контекстной типизацией, потому что контекст, в котором возникла функция, сообщает, какой тип она должна иметь.
Как и в случае с правилами вывода, вам не нужно явно знать, как это происходит, но понимание того, что это действительно происходит, может помочь вам заметить, когда аннотации типов не нужны. Позже мы увидим больше примеров того, как контекст, в котором встречается значение, может повлиять на его тип.
Как типизировать объекты в TypeScript?
Помимо примитивов, наиболее распространенным типом, с которым вы столкнетесь, является объект. Это относится к любому значению JavaScript со свойствами. Чтобы определить тип объекта, мы просто перечисляем его свойства и их типы. Например, вот функция, которая принимает объект точку:Здесь мы типизировали параметр двумя свойствами —// Аннотация типа параметра является типом объекта function printCoord(pt: { x: number; y: number }) { console.log("The coordinate's x value is " + pt.x); console.log("The coordinate's y value is " + pt.y); } printCoord({ x: 3, y: 7 });
x
и y
— оба типа number
. Вы можете использовать ,
или ;
для разделения свойств, а последний разделитель необязателен.
Указание типа каждого свойства также необязательно. Если вы не укажете тип, он будет считаться any
.
Необязательные свойства
Типы объектов также могут указывать, что некоторые или все их свойства являются необязательными. Для этого добавьте?
после имени свойства:
В JavaScript, если вы обращаетесь к несуществующему свойству, вы получите значениеfunction printName(obj: { first: string; last?: string }) { // ... } // Следующие вызовы не вызовут ошибок printName({ first: 'Bob' }); printName({ first: 'Alice', last: 'Alisson' });
undefined
, а не ошибку времени выполнения. Из-за этого, когда вы читаете из необязательного свойства, вам придется проверять его на undefined
перед его использованием.
function printName(obj: { first: string; last?: string }) { // Ошибка, если obj.last не предоставлен: console.log(obj.last.toUpperCase()); Object is possibly 'undefined'. if (obj.last !== undefined) { // OK console.log(obj.last.toUpperCase()); } // Безопасная альтернатива с использованием современного синтаксиса JavaScript: console.log(obj.last?.toUpperCase()); }
Объединение типов (Unions)
Система типов TypeScript позволяет вам создавать новые типы из существующих, используя большое количество операторов. Теперь, когда мы знаем, как писать несколько типов, пора начать комбинировать их интересными способами.Определение объединенного типа
Первый способ комбинирования типов, который вы встретить - это объединение типов. Объединение типов - это тип, сформированный из двух или более других типов, представляющих значения, которые могут быть любым из этих типов. Давайте напишем функцию, которая может работать со строками или числами:function printId(id: number | string) { console.log('Your ID is: ' + id); } // Работает printId(101); // Работает printId('202'); // Ошибка printId({ myID: 22342 }); // Argument of type '{ myID: number; }' is not assignable to parameter of type 'string | number'.
Работа с объединенными типами
TypeScript разрешит операцию только в том случае, если она действительна для каждого члена объединения. Например, если у вас есть объединениеstring | number
, вы не можете использовать методы, доступные только для string
:
Решение состоит в том, чтобы сузить объединение с помощью кода, как в JavaScript без аннотаций типов. Сужение происходит, когда TypeScript может определить более конкретный тип для значения на основе структуры кода. Например, TypeScript знает, что только строковое значение будет иметь значениеfunction printId(id: number | string) { console.log(id.toUpperCase()); // Property 'toUpperCase' does not exist on type 'string | number'. // Property 'toUpperCase' does not exist on type 'number'. }
"string"
при применении оператора typeof
:
Другой пример — использование такой функции, какfunction printId(id: number | string) { if (typeof id === 'string') { // Здесь id имеет тип 'string' console.log(id.toUpperCase()); } else { // Здесь id имеет тип 'number' console.log(id); } }
Array.isArray
:
Обратите внимание, что в веткеfunction welcomePeople(x: string[] | string) { if (Array.isArray(x)) { // Здесь: 'x' это 'string[]' console.log('Hello, ' + x.join(' and ')); } else { // Здесь: 'x' это 'string' console.log('Welcome lone traveler ' + x); } }
else
нам не нужно делать ничего особенного — если x
не является string[]
, то это должна быть строка.
Иногда у вас будет объединение, в котором все члены имеют что-то общее. Например, и массивы, и строки имеют метод slice
. Если у каждого члена объединения есть общее свойство, вы можете использовать это свойство без сужения:
Может сбивать с толку тот факт, что объединение типов имеет пересечение свойств этих типов. Это не случайно — название// Возвращаемый тип определяется из number[] | string function getFirstThree(x: number[] | string) { return x.slice(0, 3); }
union
происходит из теории типов. Объединение number | string
состоит из объединения значений каждого типа. Обратите внимание, что для двух множеств с соответствующими фактами о каждом множестве к объединению самих множеств применимо только пересечение этих фактов. Например, если бы у нас была комната с высокими людьми в шляпах и другая комната с говорящими по-испански в шляпах, после объединения этих комнат единственное, что мы знаем о каждом человеке, это то, что он должен быть в шляпе.
Псевдонимы типов (алиасы, aliases)
Мы использовали типы объектов и типы объединения, записывая их непосредственно в аннотациях типов. Это удобно, но часто хочется использовать один и тот же тип более одного раза и ссылаться на него по одному имени. Псевдоним типа — это именно то, что является именем для любого типа. Синтаксис псевдонима типа:Вы можете использовать псевдоним типа, чтобы дать имя любому типу, а не только объектному типу. Например, псевдоним типа может включать тип объединения:type Point = { x: number; y: number; }; // Тоже самое как и в прошлом примере function printCoord(pt: Point) { console.log("The coordinate's x value is " + pt.x); console.log("The coordinate's y value is " + pt.y); } printCoord({ x: 100, y: 100 });
Обратите внимание, что псевдонимы — это всего лишь псевдонимы — вы не можете использовать псевдонимы типов для создания разных/отличных «версий» одного и того же типа. Другими словами, этот код может выглядеть недопустимым, но в соответствии с TypeScript это нормально, потому что оба типа являются псевдонимами для одного и того же типа:type ID = number | string;
type UserInputSanitizedString = string; function sanitizeInput(str: string): UserInputSanitizedString { return sanitize(str); } // Значение типа UserInputSanitizedString let userInput = sanitizeInput(getInput()); // может также присваивать строку userInput = 'new input';
Интерфейсы
Объявление интерфейса — это еще один способ объявить тип объекта:Точно так же, как когда мы использовали псевдоним типа выше, пример работает так же, как если бы мы использовали анонимный тип объекта. TypeScript заботится только о структуре значения, которое мы передали вinterface Point { x: number; y: number; } function printCoord(pt: Point) { console.log("The coordinate's x value is " + pt.x); console.log("The coordinate's y value is " + pt.y); } printCoord({ x: 100, y: 100 });
printCoord
, — то, что оно имеет ожидаемые свойства. Занимаясь только структурой и возможностями типов, мы называем TypeScript структурно типизированной (structurally typed) системой типов.
Различия типа и интерфейса в TypeScript
Псевдонимы типов (type) и интерфейсы очень похожи, и во многих случаях вы можете свободно выбирать между ними. Почти все возможности интерфейса доступны в типе, ключевое отличие состоит в том, что тип нельзя повторно открыть для добавления новых свойств по сравнению с интерфейсом, который всегда расширяем. Расширение интерфейса:Расширение типа через пересечения:interface Animal { name: string; } interface Bear extends Animal { honey: boolean; } const bear = getBear(); bear.name; bear.honey;
Добавление новых полей в существующий интерфейс:type Animal = { name: string; }; type Bear = Animal & { honey: boolean; }; const bear = getBear(); bear.name; bear.honey;
Тип нельзя изменить после создания:interface Window { title: string; } interface Window { ts: TypeScriptAPI; } const src = 'const a = "Hello World"'; window.ts.transpileModule(src, {});
Вы узнаете больше об этих понятиях в следующих главах, так что не беспокойтесь, если вы не сразу все поймете.type Window = { title: string; }; type Window = { ts: TypeScriptAPI; }; // Error: Duplicate identifier 'Window'
- До TypeScript версии 4.2 имена псевдонимов могут появляться в сообщениях об ошибках, иногда вместо эквивалентного анонимного типа. Интерфейсы всегда будут иметь имена в сообщениях об ошибках.
- Псевдонимы типов не могут участвовать в слиянии объявлений, но интерфейсы могут.
- Интерфейсы могут использоваться только для объявления форм объектов, а не для переименования примитивов.
- Имена интерфейсов всегда будут отображаться в исходном виде в сообщениях об ошибках, но только тогда, когда они используются по имени.
Утверждения типа (Type Assertions)
Иногда у вас будет информация о типе значения, о котором TypeScript не может узнать. Например, если вы используетеdocument.getElementById
, TypeScript знает только, что это вернет какой-то HTMLElement
, но вы можете знать, что на вашей странице всегда будет HTMLCanvasElement
с заданным идентификатором.
В этой ситуации вы можете использовать утверждение типа, чтобы указать более конкретный тип:
Подобно аннотации типа, утверждения типа удаляются компилятором и не влияют на поведение вашего кода во время выполнения. Вы также можете использовать синтаксис угловых скобок (кроме случаев, когда код находится в файлеconst myCanvas = document.getElementById('main_canvas') as HTMLCanvasElement;
.tsx
), что эквивалентно:
TypeScript допускает только утверждения типа, которые преобразуются в более конкретную или менее конкретную версию типа. Это правило предотвращает «невозможные» приведения, такие как:const myCanvas = <HTMLCanvasElement>document.getElementById('main_canvas');
Иногда это правило может быть слишком консервативным и запрещать более сложные приведения, которые могут быть действительными. Если это произойдет, вы можете использовать два утверждения, сначала дляconst x = 'hello' as number; // Conversion of type 'string' to type 'number' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first. // Преобразование типа 'string' в тип 'number' может быть ошибкой, поскольку ни один из типов в достаточной степени не перекрывает другой. Если это было сделано намеренно, сначала преобразуйте выражение к типу 'unknown'.
any
(или unknown
), затем для нужного типа:
const a = expr as any as T;
Литеральные типы (Literal Types)
В дополнение к общим типамstring
и number
мы можем ссылаться на определенные строки и числа в позициях типа.
Один из способов это представить — рассмотреть, как в JavaScript существуют различные способы объявления переменных. И var
, и let
позволяют изменять содержимое переменной, а const
— нет. Это отражено в том, как TypeScript создает типы для литералов.
Сами по себе литеральные типы не очень ценны:let changingString = 'Hello World'; changingString = 'Olá Mundo'; // Поскольку `changingString` может представлять любую возможную строку, именно так TypeScript описывает ее в системе типов const constantString = 'Hello World'; // Поскольку `constantString` может представлять только 1 возможную строку, она имеет буквальное представление типа.
Нет особого смысла иметь переменную, которая может иметь только одно значение. Но комбинируя литералы в объединения, вы можете выразить гораздо более полезную концепцию — например, функции, которые принимают только определенный набор известных значений:let x: 'hello' = 'hello'; // Работает x = 'hello'; // ... x = 'howdy'; // Type '"howdy"' is not assignable to type '"hello"'. // Тип '"howdy"' нельзя назначить типу '"hello"'.
Типы числовых литералов работают так же:function printText(s: string, alignment: 'left' | 'right' | 'center') { // ... } printText('Hello, world', 'left'); printText("G'day, mate", 'centre'); // Argument of type '"centre"' is not assignable to parameter of type '"left" | "right" | "center"'. // Аргумент типа '"centre"' нельзя назначить параметру типа '"left" | "right" | "center"'.
Конечно, вы можете комбинировать их с нелитеральными типами:function compare(a: string, b: string): -1 | 0 | 1 { return a === b ? 0 : a > b ? 1 : -1; }
Есть еще один вид литералов:interface Options { width: number; } function configure(x: Options | 'auto') { // ... } configure({ width: 100 }); configure('auto'); configure('automatic'); // Argument of type '"automatic"' is not assignable to parameter of type 'Options | "auto"'. // Аргумент типа '"automatic"' нельзя назначить параметру типа 'Options | "auto"'.
boolean
литералы. Есть только два типа логических литералов, и, как вы могли догадаться, это true
и false
. Сам тип boolean
на самом деле является просто псевдонимом объединения true | false
.
Вывод литералов
Когда вы инициализируете переменную объектом, TypeScript предполагает, что свойства этого объекта могут изменить значения позже. Например, если вы написали такой код:TypeScript не считает, что присвоениеconst obj = { counter: 0 }; if (someCondition) { obj.counter = 1; }
1
полю, которое ранее имело 0
, является ошибкой. Другой способ выразить тоже самое это то, что obj.counter
должен иметь тип number
, а не 0
, потому что типы используются для определения поведения как при чтении, так и при записи.
То же самое относится и к строкам:
В приведенном выше примереconst req = { url: 'https://example.com', method: 'GET' }; handleRequest(req.url, req.method); // Argument of type 'string' is not assignable to parameter of type '"GET" | "POST"'. // Аргумент типа 'string' нельзя назначить параметру типа '"GET" | "POST"'.
req.method
подразумевается как строка, а не как "GET"
. Поскольку код можно обработать между созданием req
и вызовом handleRequest
, который может назначить новую строку, например "GUESS"
, для req.method
, TypeScript считает, что этот код содержит ошибку.
Есть два способа решить это.
- Вы можете изменить вывод, добавив утверждение типа в любом месте:
Изменение 1 означает: "Я говорю, что// Изменение 1: const req = { url: 'https://example.com', method: 'GET' as 'GET' }; // Изменение 2: handleRequest(req.url, req.method as 'GET');
req.method
всегда имеет литеральный тип "GET"
", предотвращая возможное назначение "GUESS"
этому полю после этого. Изменение 2 означает "Я знаю, что req.method
имеет значение "GET"
".
Вы можете использовать as const
для преобразования всего объекта в литералы типов:
Суффиксconst req = { url: 'https://example.com', method: 'GET' } as const; handleRequest(req.url, req.method);
as const
действует как const
, но для системы типов, гарантируя, что всем свойствам будет присвоен литеральный тип, а не более общая версия, такая как string
или number
.
null
и undefined
В JavaScript есть два примитивных значения, которые используются для обозначения отсутствия или неинициализации значения: null
и undefined
.
TypeScript имеет два соответствующих типа с соответствующими именами. Поведение этих типов зависит от того, включена ли у вас опция strictNullChecks
.
strictNullChecks
выключен
Если strictNullChecks
выключен, значения, которые могут быть null
или undefined
, по-прежнему могут быть доступны в обычном режиме, а значения null
или undefined
могут быть присвоены свойству любого типа. Это похоже на то, как ведут себя языки без проверок на null
(например, C#, Java). Отсутствие проверки этих значений, как правило, является основным источником ошибок; мы всегда рекомендуем включать strictNullChecks
, если это целесообразно в кодовой базе.
strictNullChecks
включен
При включении strictNullChecks, когда значение равно null
или undefined
, вам нужно будет проверить эти значения, прежде чем использовать методы или свойства для этого значения. Точно так же, как проверка на undefined
перед использованием необязательного свойства, мы можем использовать сужение для проверки значений, которые могут быть null
:
function doSomething(x: string | null) { if (x === null) { // … } else { console.log('Hello, ' + x.toUpperCase()); } }
Оператор ненулевого утверждения (Non-null Assertion Operator, постфикс !
)
TypeScript также имеет специальный синтаксис для удаления null
и undefined
из типа без какой-либо явной проверки. Добавление !
после выражения фактически является утверждением того, что значение не является null
или undefined
:
Как и другие утверждения типа, это не меняет поведение вашего кода во время выполнения, поэтому важно использовать толькоfunction liveDangerously(x?: number | null) { // No error console.log(x!.toFixed()); }
!
когда вы знаете, что значение не может быть null
или undefined
.
Что такое Enums в TypeScript (Перечисления)?
Перечисления — это функциональность, добавленная TypeScript, которая позволяет описывать значение, которое может быть одной из множества возможных именованных констант. В отличие от большинства возможностей TypeScript, это не дополнение к JavaScript на уровне типов, а нечто, добавленное к языку и среде выполнения.enum Direction { Up, Down, Left, Right, }
Менее распространенные примитивы
Стоит упомянуть остальные примитивы в JavaScript, представленные в системе типов.bigint
Начиная с ES2020, в JavaScript есть примитив, используемый для очень больших целых чисел, BigInt
:
// Создание значения bigint через функцию BigInt const oneHundred: bigint = BigInt(100); // Создание значения BigInt через литеральный синтаксис const anotherHundred: bigint = 100n;
symbol
В JavaScript есть примитив, используемый для создания глобальной уникальной ссылки с помощью функции Symbol()
:
const firstName = Symbol('name'); const secondName = Symbol('name'); if (firstName === secondName) { // Это условие всегда будет возвращать 'false', поскольку типы 'typeof firstName' и 'typeof secondName' не пересекаются. }
Типизация функций с помощью TypeScript
год назад·15 мин. на чтение
Туториал по TypeScript - Типизация функций TypeScript
Содержание туториала по TypeScript
Функции — это основной строительный блок любого приложения, будь то локальные функции, импортированные из другого модуля или методы класса. Они также являются значениями, и, как и другие значения, в TypeScript есть много способов описать, как можно вызывать функции.
Определение
С помощью анализа потока кода TypeScript сделает вывод о том, чем является
Специальный тип
Тип
Некоторые функции никогда не возвращают значение:
Глобальный тип
Возвращаемый тип
Возвращаемый тип
Типизация функций
Самый простой способ типизировать функцию — использовать выражение функционального типа. Эти типы синтаксически похожи на стрелочные функции:Синтаксисfunction greeter(fn: (a: string) => void) { fn('Hello, World'); } function printToConsole(s: string) { console.log(s); } greeter(printToConsole);
(a:string) => void
означает "функция с одним параметром a
, типа string
, который не имеет возвращаемого значения". Как и в случае с определением функции, если тип параметра не указан, он будет иметь тип any
.
Обратите внимание, что имя параметра является обязательным. Тип функции (string) => void
означает "функция с параметром, названным string
типа any
"!
Конечно, мы можем использовать псевдоним типа для обозначения типа функции:
type GreetFunction = (a: string) => void; function greeter(fn: GreetFunction) { // ... }
Сигнатура вызова (Call Signature)
В JavaScript функции могут не только вызываться, но и иметь свойства. Однако синтаксис выражения функционального типа не позволяет объявлять свойства. Если мы хотим описать что-то вызываемое с помощью свойств, мы можем написать сигнатуру вызова в объектном типе:Обратите внимание, что синтаксис немного отличается от выражения функционального типа — используетсяtype DescribableFunction = { description: string; (someArg: number): boolean; }; function doSomething(fn: DescribableFunction) { console.log(fn.description + ' returned ' + fn(6)); }
:
между списком параметров и возвращаемым типом, а не =>
.
Сигнатура конструктора (Construct Signature)
Функции JavaScript также можно вызывать с помощью оператораnew
. В TypeScript они считаются конструкторами, потому что они обычно создают новый объект. Вы можете написать сигнатуру конструктора, добавив ключевое слово new
перед сигнатурой вызова:
Некоторые объекты, такие как объектtype SomeConstructor = { new (s: string): SomeObject; }; function fn(ctor: SomeConstructor) { return new ctor('hello'); }
Date
в JavaScript, можно вызывать как с оператором new
, так и без него. Вы можете произвольно комбинировать сигнатуры вызова и конструктора в одном и том же типе:
interface CallOrConstruct { new (s: string): Date; (n?: number): number; }
Функции-дженерики (Generic Functions)
Обычно пишут функцию, в которой типы входных данных связаны с типом выходных данных или где типы двух входных данных каким-то образом связаны. Давайте рассмотрим функцию, которая возвращает первый элемент массива:Эта функция выполняет свою работу, но, к сожалению, имеет возвращаемый типfunction firstElement(arr: any[]) { return arr[0]; }
any
. Лучше бы функция возвращала тип элемента массива.
В TypeScript дженерики используются, когда мы хотим описать соответствие между двумя значениями. Мы делаем это, объявляя параметр типа в сигнатуре функции:
Добавив к этой функции параметрfunction firstElement<Type>(arr: Type[]): Type | undefined { return arr[0]; }
Type
и используя его в двух местах, мы создали связь между входными данными функции (массивом) и выходными (возвращаемым значением). Теперь, когда мы ее вызываем, получается более конкретный тип:
// s имеет тип 'string' const s = firstElement(['a', 'b', 'c']); // n имеет тип 'number' const n = firstElement([1, 2, 3]); // u имеет тип undefined const u = firstElement([]);
Предположение типа (Inference)
Мы можем использовать несколько параметров типа. Например, самописная версия функцииmap
может выглядеть так:
Обратите внимание, что в приведенном примере TypeScript может сделать вывод относительно типаfunction map<Input, Output>( arr: Input[], func: (arg: Input) => Output ): Output[] { return arr.map(func); } // Параметр 'n' имеет тип 'string' // 'parsed' имеет тип 'number[]' const parsed = map(['1', '2', '3'], (n) => parseInt(n));
Input
на основе переданного string[]
, а относительно типа Output
на основе возвращаемого number
.
Ограничения (constraints)
Ограничение используется для того, чтобы ограничивать типы, которые принимаются параметром типа. Реализуем функцию, возвращающую самое длинное из двух значений. Для этого нам потребуется свойствоlength
, которое будет числом. Мы ограничим параметр типа типом number
с помощью ключевого слова extends
:
В этом примере есть несколько интересных моментов. Мы позволили TypeScript определять возвращаемый тип самого длинного значения. Вывод типа возвращаемого значения также работает с функциями-дженериками. Поскольку мы ограничилиfunction longest<Type extends { length: number }>(a: Type, b: Type) { if (a.length >= b.length) { return a; } else { return b; } } // longerArray имеет тип 'number[]' const longerArray = longest([1, 2], [1, 2, 3]); // longerString имеет тип 'alice' | 'bob' const longerString = longest('alice', 'bob'); // Ошибка! У чисел нет свойства 'length' const notOK = longest(10, 100); // Argument of type 'number' is not assignable to parameter of type '{ length: number; }'. // Аргумент типа 'number' не может быть присвоен аргументу типа '{ length: number; }'.
Type
значением {length: number}
, мы смогли получить доступ к свойству .length
параметров a
и b
. Без ограничения типа мы не смогли бы получить доступ к этим свойствам, потому что значения могли быть какого-то другого типа без свойства length
.
Типы longerArray
и longerString
были выведены на основе аргументов. Помните, что дженерики — это связывание двух или более значений с одним и тем же типом.
Наконец, как мы и хотели, вызов longest(10, 100)
,был отклонен, потому что тип number
не имеет свойства .length
.
Работа со значениями с ограничениями
Вот распространенная ошибка при работе с ограничениями-дженериками:Может показаться, что с этой функцией все в порядке —function minimumLength<Type extends { length: number }>( obj: Type, minimum: number ): Type { if (obj.length >= minimum) { return obj; } else { return { length: minimum }; // Type '{ length: number; }' is not assignable to type 'Type'. // '{ length: number; }' is assignable to the constraint of type 'Type', but 'Type' could be instantiated with a different subtype of constraint '{ length: number; }'. } }
Type
ограничен до { length: number }
, и функция либо возвращает Type
, либо значение, соответствующее этому ограничению. Проблема в том, что функция обещает вернуть тот же тип объекта, который был передан, а не просто какой-то объект, соответствующий ограничению. Если бы этот код был работающим, вы могли бы написать код, который не работал бы:
// 'arr' получает значение { length: 6 } const arr = minimumLength([1, 2, 3], 6); // и падает, т.к. массив имеет метод 'slice' // но не возвращаемый объект! console.log(arr.slice(0));
Определение типа аргументов
TypeScript обычно может вывести предполагаемые аргументы типа в вызове дженерика, но не всегда. Например, вы написали функцию для объединения двух массивов:Обычно было бы ошибкой вызывать эту функцию с несовпадающими массивами:function combine<Type>(arr1: Type[], arr2: Type[]): Type[] { return arr1.concat(arr2); }
Однако, если вы намеревались сделать это, вы можете вручную указатьconst arr = combine([1, 2, 3], ['hello']); // Type 'string' is not assignable to type 'number'. // Нельзя присвоить тип 'string' типу 'number'.
Type
:
const arr = combine<string | number>([1, 2, 3], ['hello']);
Как написать хорошую функцию-дженерик?
Написание функций-дженериков — это весело, и можно легко увлечься параметрами типа. Наличие слишком большого количества параметров типа или использование ограничений там, где они не нужны, может сделать вывод менее успешным, вызывая разочарование у пользователей функции.Используйте параметры типа без ограничений
Вот два способа написания функции, которые кажутся похожими:На первый взгляд они могут показаться идентичными, ноfunction firstElement1<Type>(arr: Type[]) { return arr[0]; } function firstElement2<Type extends any[]>(arr: Type) { return arr[0]; } // a: number (хорошо) const a = firstElement1([1, 2, 3]); // b: any (плохо) const b = firstElement2([1, 2, 3]);
firstElement1
— гораздо лучший способ написать эту функцию. Предполагаемый тип возвращаемого значения — Type
, но предполагаемый возвращаемый тип firstElement2
— any
, поскольку TypeScript должен разрешать выражение arr[0]
с использованием типа ограничения, а не «ждать» элемент во время вызова.
Правило: по возможности используйте сам параметр типа, а не ограничивайте его.
Используйте меньше параметров типа
Вот еще пара похожих функций:Мы создали параметр типаfunction filter1<Type>(arr: Type[], func: (arg: Type) => boolean): Type[] { return arr.filter(func); } function filter2<Type, Func extends (arg: Type) => boolean>( arr: Type[], func: Func ): Type[] { return arr.filter(func); }
Func
, который не связывает два значения. Это всегда красный флаг, потому что это означает, что вызывающие программы, желающие указать аргументы типа, должны вручную указать дополнительный аргумент типа без всякой причины. Func
ничего не делает, но затрудняет чтение и осмысление функции!
Правило: всегда используйте как можно меньше параметров типа
Параметры типа должны появляться дважды
Иногда мы забываем, что функции не обязательно быть дженериком:Мы могли бы написать более простую версию:function greet<Str extends string>(s: Str) { console.log('Hello, ' + s); } greet('world');
Помните, что параметры типа предназначены для связи типов нескольких значений. Если параметр типа используется только один раз в сигнатуре функции, он ни с чем не связан. Правило: если параметр типа появляется только в одном месте, серьезно подумайте, действительно ли он вам нужен.function greet(s: string) { console.log('Hello, ' + s); }
Необязательные параметры
Функции в JavaScript часто принимают переменное количество аргументов. Например, методtoFixed
для значений типа number
принимает необязательное количество цифр:
Мы можем смоделировать это в TypeScript, пометив параметр как необязательный с помощьюfunction f(n: number) { console.log(n.toFixed()); // 0 аргументов console.log(n.toFixed(3)); // 1 аргумент }
?
:
Хотя параметр указан как типаfunction f(x?: number) { // ... } f(); // OK f(10); // OK
number
, параметр x
на самом деле будет иметь тип number | undefined
, потому что неуказанные параметры в JavaScript получают значение undefined
.
Вы также можете указать параметр по умолчанию:
Теперь в телеfunction f(x = 10) { // ... }
f
, x
будет иметь тип number
, потому что любой неопределенный аргумент будет заменен на 10
. Обратите внимание, что, когда параметр является необязательным, вызывающая сторона всегда может передать значение undefined
, так как это просто имитирует «отсутствующий» аргумент:
declare function f(x?: number): void; // все вызовы допустимы f(); f(10); f(undefined);
Необязательные параметры в функциях обратного вызова
Мы уже знаем о необязательных параметрах и типизации функциональных выражений. Очень легко сделать следующие ошибки при написании функций, которые вызывают колбеки:Обычно при написанииfunction myForEach(arr: any[], callback: (arg: any, index?: number) => void) { for (let i = 0; i < arr.length; i++) { callback(arr[i], i); } }
index?
в качестве необязательного параметр разработчики хотят, чтобы оба этих вызова валидными:
На самом деле это означает, что колбек может быть вызван с одним аргументом. Другими словами, в определении функции сказано, что реализация может выглядеть так:myForEach([1, 2, 3], (a) => console.log(a)); myForEach([1, 2, 3], (a, i) => console.log(a, i));
В свою очередь, TypeScript будет применять это значение и выдавать ошибки:function myForEach(arr: any[], callback: (arg: any, index?: number) => void) { for (let i = 0; i < arr.length; i++) { callback(arr[i]); } }
В JavaScript, если вы вызываете функцию с бОльшим количеством аргументов, лишние аргументы просто игнорируются. TypeScript ведет себя точно так же. Функции с меньшим количеством параметров (одного и того же типа) всегда могут заменить функции с бОльшим количеством параметров. При типизации функции для колбека никогда делайте параметр необязательным, если вы не собираетесь вызывать функцию без передачи этого аргумента.myForEach([1, 2, 3], (a, i) => { console.log(i.toFixed()); // Object is possibly 'undefined'. // Объект, возможно, 'undefined'. });
Перегрузка функций (Function Overloads)
Некоторые функции JavaScript можно вызывать с различным числом аргументов и типами. Например, вы можете написать функцию для создания датыDate
, которая принимает отметку времени (один аргумент) или спецификацию месяц/день/год (три аргумента).
В TypeScript мы можем указать функцию, которую можно вызывать по-разному, написав сигнатуры перегрузки. Для этого нужно написать несколько сигнатур функции (обычно две или более), а затем тело функции:
В этом примере мы написали две перегрузки: одну, принимающую один аргумент, и другую, принимающую три аргумента. Эти первые две сигнатуры называются сигнатурами перегрузки. Затем мы написали реализацию функции с совместимой сигнатурой. Функции имеют сигнатуру реализации, но эту сигнатуру нельзя вызвать напрямую. Несмотря на то, что мы написали функцию с двумя необязательными параметрами после обязательного, ее нельзя вызвать с двумя параметрами!function makeDate(timestamp: number): Date; function makeDate(m: number, d: number, y: number): Date; function makeDate(mOrTimestamp: number, d?: number, y?: number): Date { if (d !== undefined && y !== undefined) { return new Date(y, mOrTimestamp, d); } else { return new Date(mOrTimestamp); } } const d1 = makeDate(12345678); const d2 = makeDate(5, 5, 5); const d3 = makeDate(1, 3); // No overload expects 2 arguments, but overloads do exist that expect either 1 or 3 arguments. // Нет перегрузки, ожидающей 2 аргумента, но есть перегрузки, которые ожидают либо 1, либо 3 аргумента.
Сигнатуры перегрузки и сигнатура реализации
Это распространенный источник путаницы. Часто люди пишут такой код и не понимают, почему возникает ошибка:Сигнатура, используемая для написания тела функции, не может быть использована извне. Сигнатура реализации не видна снаружи. При написании перегруженной функции вы всегда должны иметь две или более сигнатуры над реализацией функции. Сигнатура реализации также должна быть совместима с сигнатурами перегрузки. Например, в этих функциях есть ошибки, потому что сигнатура реализации не соответствует перегруженным версиям должным образом:function fn(x: string): void; function fn() { // ... } // Expected to be able to call with zero arguments // Ожидается, что можно вызвать без аргументов fn(); // Expected 1 arguments, but got 0. // Ожидается 1 аргумент, но получено 0.
function fn(x: boolean): void; // Неправильный аргумент функции function fn(x: string): void; // This overload signature is not compatible with its implementation signature. // Эта перегрузка сигнатуры не совместима с сигнатурой реализации. function fn(x: boolean) {}
function fn(x: string): string; // Неверный возвращаемый тип function fn(x: number): boolean; // This overload signature is not compatible with its implementation signature. // Cигнатура перегрузки не совместима с сигнатурой реализации. function fn(x: string | number) { return 'oops'; }
Как написать хорошую перегрузку
Как и в случае с дженериками, при использовании перегруженных функций следует соблюдать несколько рекомендаций. Следование этим принципам упростит вызов вашей функции, ее понимание и реализацию. Рассмотрим функцию, которая возвращает длину строки или массива:С этой функцией все в порядке; мы можем вызывать ее со строками или массивами. Однако мы не можем вызвать ее со значением, которое может быть строкой или массивом, потому что TypeScript может разрешить вызов функции только для одной перегрузки:function len(s: string): number; function len(arr: any[]): number; function len(x: any) { return x.length; }
Поскольку обе перегрузки имеют одинаковое количество аргументов и один и тот же тип возвращаемого значения, вместо этого мы можем написать не перегруженную версию функции:len(''); // OK len([0]); // OK len(Math.random() > 0.5 ? 'hello' : [0]); // No overload matches this call. // Overload 1 of 2, '(s: string): number', gave the following error. // Argument of type 'number[] | "hello"' is not assignable to parameter of type 'string'. // Type 'number[]' is not assignable to type 'string'. // Overload 2 of 2, '(arr: any[]): number', gave the following error. // Argument of type 'number[] | "hello"' is not assignable to parameter of type 'any[]'. // Type 'string' is not assignable to type 'any[]'.
Так гораздо лучше! Ее можно вызывать со значением любого типа, и в качестве дополнительного бонуса нам не нужно вычислять правильную сигнатуру реализации. Всегда предпочитайте параметры с объединением вместо перегрузок, когда это возможно.function len(x: any[] | string) { return x.length; }
Определение this
в функциях
С помощью анализа потока кода TypeScript сделает вывод о том, чем является this
:
TypeScript понимает, что функцияconst user = { id: 123, admin: false, becomeAdmin: function () { this.admin = true; }, };
user.becomeAdmin
имеет соответствующий this
, который является объектом user
извне. В спецификации JavaScript указано, что у вас не может быть параметра с именем this
, TypeScript использует это, чтобы можно было объявить тип для this
в теле функции.
Этот шаблон распространен в API обратного вызова, где другой объект обычно управляет вызовом вашей функции. Обратите внимание, что вам нужно использоватьinterface DB { filterUsers(filter: (this: User) => boolean): User[]; } const db = getDB(); const admins = db.filterUsers(function (this: User) { return this.admin; });
function
, а не стрелочные функции, чтобы получить такое поведение:
interface DB { filterUsers(filter: (this: User) => boolean): User[]; } const db = getDB(); const admins = db.filterUsers(() => this.admin); // The containing arrow function captures the global value of 'this'. // Стрелочная функция захватывает глобальный `this`. // Element implicitly has an 'any' type because type 'typeof globalThis' has no index signature. // Элемент неявно имеет тип 'any' т.к. тип 'typeof globalThis' не имеет сигнатуры.
Другие типы, о которых следует знать
Есть несколько дополнительных типов, которые часто появляются при работе с типами функций. Как и все типы, вы можете использовать их везде, но они особенно актуальны в функциях.void
void
представляет возвращаемое значение функций, которые не возвращают значения. Этот тип выведется из функции, когда функция не имеет операторов return
или не возвращает никакого явного значения из этих операторов return
:
В JavaScript функция, которая не возвращает никакого значения, неявно вернет значение// Выведенный тип возвращаемого результата void function noop() { return; }
undefined
. Однако void
и undefined
— это не одно и то же в TypeScript. Дополнительные подробности приведены в конце этой главы.
object
Специальный тип object
относится к любому значению, не являющемуся примитивом (string
, number
, bigint
, boolean
, symbol
, null
или undefined
). Это отличается от типа пустого объекта { }
, а также отличается от глобального типа Object
. Очень вероятно, что вы никогда не будете использовать Object
.
object
не является Object
. Всегда используйте object
!
Обратите внимание, что в JavaScript функции являются объектами: у них есть свойства, есть Object.prototype
в своей цепочке прототипов, являются instanceof Object
, вы можете вызывать для них Object.keys
и т.д. По этой причине типы функций считаются object
в TypeScript.
unknown
Тип unknown
представляет любое значение. Это похоже на тип any
, но безопаснее, потому что нельзя ничего делать с неизвестным значением:
Это полезно при описании типов функций, потому что вы можете описывать функции, которые принимают любое значение, не имея значенийfunction f1(a: any) { a.b(); // OK } function f2(a: unknown) { a.b(); // Object is of type 'unknown'. // Объект типа 'unknown'. }
any
в теле вашей функции.
И наоборот, вы можете описать функцию, которая возвращает значение типа unknown
:
function safeParse(s: string): unknown { return JSON.parse(s); } // Нужно быть осторожным с 'obj'! const obj = safeParse(someRandomString);
never
Некоторые функции никогда не возвращают значение:
Типfunction fail(msg: string): never { throw new Error(msg); }
never
представляет значения, которые никогда не возвращаются. В возвращаемом типе это означает, что функция выдает исключение или завершает выполнение программы.
never
появляется, когда TypeScript определяет, что в объединении ничего не осталось.
function fn(x: string | number) { if (typeof x === 'string') { // что-то делаем } else if (typeof x === 'number') { // что-то делаем еще } else { x; // имеет тип 'never'! } }
Function
Глобальный тип Function
описывает такие свойства, как bind
, call
, apply
и другие, присутствующие во всех значениях функций в JavaScript. Он также имеет специальное свойство, позволяющее вызывать значения типа Function — такие вызовы возвращают any:
Это нетипизированный вызов функции, и его обычно лучше избегать из-за небезопасного возвращаемого типаfunction doSomething(f: Function) { return f(1, 2, 3); }
any
.
Если вам нужно принять произвольную функцию без ее вызова, тип () => void
, как правило, безопаснее.
Остальные параметры и аргументы (rest)
Остальные параметры
В дополнение к использованию необязательных параметров или перегрузок функций, которые могут принимать множество фиксированных аргументов, мы также можем определить функции, которые принимают неограниченное количество аргументов, используя синтаксис остальных параметров (rest parameters). Остальные параметры появляется после всех остальных параметров и используют синтаксис...
:
В TypeScript аннотация типа для этих параметров неявно являетсяfunction multiply(n: number, ...m: number[]) { return m.map((x) => n * x); } // 'a' имеет значение [10, 20, 30, 40] const a = multiply(10, 1, 2, 3, 4);
any[]
вместо any
, и любая указанная аннотация типа должна иметь форму Array<T>
или T[]
или тип кортежа (о котором мы узнаем позже).
Остальные аргументы
И наоборот, мы можем предоставить переменное количество аргументов из массива, используя синтаксис распыления (spread syntax). Например, метод массивовpush
принимает любое количество аргументов:
Обратите внимание, что в целом TypeScript не предполагает, что массивы иммутабельные. Это может привести к неожиданному поведению:const arr1 = [1, 2, 3]; const arr2 = [4, 5, 6]; arr1.push(...arr2);
Лучшее решение для этой ситуации зависит от вашего кода, но в целом// Предполагаемый тип number[] - массив с двумя или более числами, // не конкретно с двумя числами const args = [8, 5]; const angle = Math.atan2(...args); // A spread argument must either have a tuple type or be passed to a rest parameter. // Распыленный аргумент должен быть типом кортежа или отправлен как остальные параметры (rest)
const
является наиболее простым решением:
Использование остальных аргументов может потребовать включения// Представлен как кортеж длины 2 const args = [8, 5] as const; // OK const angle = Math.atan2(...args);
downlevelIteration
если старые среды выполнения являются целевыми.
Деструктуризация параметров (Parameter Destructuring)
Вы можете использовать деструктуризацию параметров для удобной распаковки объектов, предоставленных в качестве аргумента, в одну или несколько локальных переменных в теле функции. В JavaScript это выглядит так:Аннотация типа для объекта идет после синтаксиса деструктурирования:function sum({ a, b, c }) { console.log(a + b + c); } sum({ a: 10, b: 3, c: 9 });
Это может выглядеть немного многословно, но здесь вы также можете использовать именованный тип:function sum({ a, b, c }: { a: number; b: number; c: number }) { console.log(a + b + c); }
type ABC = { a: number; b: number; c: number }; function sum({ a, b, c }: ABC) { console.log(a + b + c); }
Присваиваемость функций
Возвращаемый тип void
Возвращаемый тип void
для функций может привести к необычному, но ожидаемому поведению.
Контекстуальная типизация (contextual typing) с возвращаемым типом void
не заставляет функции ничего не возвращать. Иными словами, По-другому можно сказать, что функция с возвращаемым типом void
(type vf = () => void
), при реализации может вернуть любое другое значение, но оно будет проигнорировано.
Таким образом, допустимы следующие реализации () => void
:
И когда возвращаемое значение одной из этих функций будет присвоено другой переменной, оно сохранит типtype voidFunc = () => void; const f1: voidFunc = () => { return true; }; const f2: voidFunc = () => true; const f3: voidFunc = function () { return true; };
void
:
Поэтому следующий код валидный, несмотря на то, чтоconst v1 = f1(); const v2 = f2(); const v3 = f3();
Array.prototype.push
возвращает number
, а метод Array.prototype.forEach
ожидает функцию с возвращаемым типом void
.
Есть еще один особый случай, о котором следует знать, когда литеральное определение функции имеет возвращаемый типconst src = [1, 2, 3]; const dst = [0]; src.forEach((el) => dist.push(el));
void
, эта функция не должна ничего возвращать.
function f2(): void { // @ts-expect-error return true; } const f3 = function (): void { // @ts-expect-error return true; };