Как настроить Webpack, TypeScript и ts-loader
4 месяца назад·8 мин. на чтение
Здесть вы узнаете, как правильно настроить Webpack с использованием TypeScript и ts-loader. Шаг за шагом мы проведем вас через процесс интеграции TypeScript в ваш проект с помощью ts-loader, расскажем об основных конфигурационных параметрах и поделимся советами по оптимизации сборки.
Используемый во многих современных проектах, Webpack, является инструментом, который оптимизирует ресурсы приложения, чтобы они работали более эффективно на любом устройстве. Webpack помогает компилировать и объединять модули в единый файл, уменьшая количество HTTP-запросов и, как следствие, повышая производительность приложения.
С помощью Webpack код TypeScript компилируется в файл JavaScript, который удобен для браузера. С помощью загрузчиков (loaders) Webpack вы также можете конвертировать файлы Sass и Less в один CSS файл.
В этой статье мы узнаем, как использовать Webpack для компиляции TypeScript в JavaScript, объединять исходный код в один JavaScript файл и использовать source map исходного кода для отладки. Мы также рассмотрим, как использовать плагины Webpack.
Чтобы следовать инструкциям в этом руководстве, вам потребуется следующее:
- npm
- Node.js (≥v8.x)
- Редактор кода на ваш выбор (например, Visual Studio Code)
- Базовые знания TypeScript
Содержание
- Загрузчики Webpack
- Настройка Webpack и TypeScript
- Конфигурация Webpack
- Конфигурация TypeScript
- Конфигурация пакета
- Создание HTML-страниц с помощью HtmlWebpackPlugin
- Объединение CSS с MiniCssExtractPlugin
- Минимизация CSS
- Минификация JavaScript
- Использование CopyWebpackPlugin
- Отладка с помощью source map
Загрузчики Webpack
По умолчанию Webpack понимает только файлы JavaScript, рассматривая каждый импортированный файл как модуль. Webpack не может компилировать или объединять файлы, отличные от JavaScript, поэтому он использует загрузчики. Загрузчики сообщают Webpack, как компилировать и объединять статические ресурсы. Они используются для компиляции модулей TypeScript в JavaScript, обработки стилей приложений и даже линтинга кода с помощью ESLint. Некоторые загрузчики Webpack включают ts-loader, css-loader, style-loader и другие. Мы обсудим их позже в этом руководстве.Настройка Webpack и TypeScript
Начнем с настройки нашего проекта. Во-первых, на вашем компьютере должен быть установлен TypeScript. Чтобы установить TypeScript глобально, используйте следующую команду:Глобальная установка TypeScript избавляет от необходимости устанавливать TypeScript каждый раз, когда вы начинаете новый проект. Далее мы установим пакеты webpack и ts-loader в качестве зависимостей в нашем проекте:npm install -g typescript
npm init -y npm install -D webpack webpack-cli ts-loader webpack-dev-server
Конфигурация Webpack
По умолчанию Webpack не нуждается в конфигурационном файле. Предполагается, что точкой входа для вашего проекта являетсяsrc/index.js
и выведет минимизированный и оптимизированный результат в dist/main.js
.
Если вы хотите использовать плагины или загрузчики, то вам нужно будет использовать конфигурационный файл Webpack, позволяющий указать, как Webpack будет работать с вашим проектом, какие файлы компилировать и где будет находиться выходной файл.
Давайте добавим конфигурационный файл Webpack в наш проект. В корневой папке проекта создайте webpack.config.js
со следующими конфигурациями:
Давайте рассмотрим некоторые параметры конфигурации Webpack. Во-первых, опцияconst path = require('path'); module.exports = { entry: './src/index.ts', module: { rules: [ { test: /\.ts?$/, use: 'ts-loader', exclude: /node_modules/, }, ], }, resolve: { extensions: ['.tsx', '.ts', '.js'], }, output: { filename: 'bundle.js', path: path.resolve(__dirname, 'dist'), }, devServer: { static: path.join(__dirname, "dist"), compress: true, port: 4000, }, };
entry
является отправной точкой для приложения, где Webpack начинает строить граф зависимостей. Webpack перейдет к другим модулям в зависимости от входного файла.
Опция output
указывает Webpack, куда сохранять бандлы (результаты сборки), и позволяет присвоить файлу имя. Наконец, опция module указывает Webpack, как обрабатывать модули с определенными правилами с помощью загрузчиков.
Конфигурация TypeScript
Конфигурационный файл TypeScript определяет, как TypeScript будет компилироваться в JavaScript, и определяет различные параметры компилятора, необходимые для транспиляции TypeScript. В корневой папке проекта создайтеtsconfig.json
и добавьте следующие конфигурации:
{
"compilerOptions": {
"noImplicitAny": true,
"target": "ES5",
"module": "ES2015"
}
}
target
— это версия JavaScript, в которую вы хотите транспилировать TypeScript, а module
— это формат используемого оператора импорта. Вы можете установить модуль на CommonJS, ES6 или UMD, так как Webpack будет работать со всеми системами модулей.
Конфигурация проекта
Теперь нам нужно добавить сценарий Webpack, который будет запускатьwebpack.config.js
файл для нас.
Чтобы добавить сценарий Webpack, откройте package.json
и добавьте следующие скрипты в опцию script
:
- "dev": "webpack-dev-server --mode development",
- "build" : "webpack --mode production"
package.json
теперь будет содержать следующие параметры конфигурации:
Теперь давайте создадим простую программу TypeScript, которая будет вычитать два числа. Внутри папки{ "name": "webpack-setup", "version": "1.0.0", "description": "", "main": "src/index.ts", "scripts": { "test": "echo \"Error: no test specified\" && exit 1", "dev": "webpack-dev-server --mode development", "build": "webpack --mode production" }, "keywords": [], "author": "", "license": "ISC", "devDependencies": { "css-loader": "^6.7.1", "html-webpack-plugin": "^5.5.0", "mini-css-extract-plugin": "^2.6.1", "ts-loader": "^9.4.1", "webpack": "^5.74.0", "webpack-cli": "^4.10.0", "webpack-dev-server": "^4.11.1" } }
src
создайте index.ts
и добавьте следующий код TypeScript:
Затем создайте еще один файлimport { subtract } from "./app"; function init() { const form = document.querySelector("form"); form?.addEventListener("submit", submitHandler); } function submitHandler(e: Event) { e.preventDefault(); const num1 = document.querySelector("input[name='firstnumber']") as HTMLInputElement; const num2 = document.querySelector("input[name='secondnumber']") as HTMLInputElement; const result = subtract(Number(num1.value), Number(num2.value)); const resultElement = document.querySelector("p"); if (resultElement) { resultElement.textContent = result.toString(); } } init();
app.ts
и добавьте следующий код:
Запуск скрипта dev запустит приложение в режиме разработки:export function subtract(firstnumber: number, secondnumber: number): number { return firstnumber - secondnumber; }
Запуск скрипта build запустит приложение в режиме для продакшен сборки:npm run develop
После выполнения команды build Webpack транспилирует два файла TypeScript в код JavaScript и сгенерируетnpm run build
bundle.js
в папке dist
.
Создание HTML-страниц с помощью HtmlWebpackPlugin
HtmlWebpackPlugin позволяет Webpack генерировать стандартную HTML-страницу, которая будет обслуживать сгенерированные файлы пакета. Когда имя файла пакета изменяется или хэшируется, HTMLWebpackPlugin обновляет имена файлов на HTML-странице. Во-первых, чтобы установить HtmlWebpackPlugin, выполните следующую команду:Далее нам нужно импортировать и добавить HtmlWebpackPlugin в опцию плагина конфигурации Webpack следующим образом:npm install html-webpack-plugin --save-dev
Шаблон представляет собой пользовательский HTML-файл, сгенерированный HtmlWebpackPlugin для вставки в HTML-страницу. Чтобы создать пользовательский HTML-код, внутри папки src создайтеconst HtmlWebpackPlugin = require("html-webpack-plugin"); const path = require('path'); module.exports = { entry: './src/index.ts', module: { rules: [ { test: /\.ts?$/, use: 'ts-loader', exclude: /node_modules/, } ], }, resolve: { extensions: ['.tsx', '.ts', '.js'], }, output: { filename: 'bundle.js', path: path.resolve(__dirname, 'dist'), }, plugins: [ new HtmlWebpackPlugin({ title: 'our project', template: 'src/custom.html' }) ], devServer: { static: path.join(__dirname, "dist"), compress: true, port: 4000, }, };
custom.html
и добавьте следующий HTML-код:
Вам не нужно включать скрипт или теги ссылок в пользовательский HTML. HtmlWebpackPlugin позаботится об этом, связав URL-адрес файла пакета со сгенерированной страницей. При запуске приложения в продакшен режиме файл<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> </head> <body> <div class="cal"> <center> <form><br> <p>Result : <span id="display"></span></p> <input type="number" class="input" placeholder="Enter first number" name="firstnumber" value="1" min="1" min="9" /><br> <input type="number" class="input" placeholder="Enter second number" name="secondnumber" value="1" min="1" min="9" /><br><br> <button type="submit" class="button">Subtract</button> </form> </center> </div> </body> </html>
index.html
появится внутри папки dist
.
Собираем CSS с MiniCSSExtractPlugin
css-loader подсказывает Webpack, как работать с CSS. Он интерпретирует@import
и URL
как import/require
и резолвит их. css-loader позволяет Webpack скомпилировать все CSS файлы и конвертировать их в формат JavaScript.
Объединение CSS-файлов с загрузчиком стилей приводит к тому, что стили HTML-страниц не отвечают на запросы до тех пор, пока bundle.js
полностью не загружен. Загрузчик стилей внедряет CSS в DOM, но собранный JavaScript файл должен быть полностью загружен до внедрения стилей. Чтобы решить эту проблему, мы можем использовать MiniCssExtractPlugin.
MiniCssExtractPlugin извлекает файлы CSS и объединяет их в один bundle.css
файл. Это полезно для уменьшения размера ресурсов CSS и помогает избежать ненужных HTTP-запросов для их загрузки.
Мы можем установить css-loader и MiniCssExtractPlugin, выполнив в терминале следующие команды:
Теперь давайте добавим css-loader и MiniCssExtractPlugin вnpm install css-loader --save-dev npm install mini-css-extract-plugin --save-dev
webpack.config.js
файл.
В верхней части webpack.config.js
импортируйте модуль MiniCssExtractPlugin, используя приведенный ниже код:
Затем мы добавим новое правило в свойство rules следующим образом:const MiniCssExtractPlugin = require("mini-css-extract-plugin");
Когда css-loader компилирует все CSS файлы в JavaScript, MiniCssExtractPlugin.loader загружает CSS в CSS бандл. Далее мы добавим MiniCssExtractPlugin в опцию плагина следующим образом:… { test: /\.css$/, use: [MiniCssExtractPlugin.loader, "css-loader"] } …
Теперь, когда мы настроили css-loader и MiniCssExtractPlugin, давайте создадим CSS-файл и импортируем его вplugins: [ new HtmlWebpackPlugin({ title: 'our project', template: 'src/custom.html' }), new MiniCssExtractPlugin({ filename:"bundle.css" }) ]
index.ts
. Внутри папки src
создайте index.css
и добавьте следующий CSS-код:
Импортируйте CSS-стиль вform { background-color: pink; margin-top: 100px; border-radius: 40px; } .cal { width: 550px; height: 300px; margin-left: 400px; } .button { border-radius: 10px; margin-top: 20px; margin-bottom: 20px; } .input { border-radius: 10px; margin-top: 40px; }
index.ts
следующим образом:
Запускimport styles "./main.css"
npm run build
объединит CSS и применит его к index.html
. Когда вы запускаете приложение в режиме разработки и открываете http://localhost:4000
.
Минимизация CSS
Мы можем использовать css-minimizer-webpack-plugin, чтобы уменьшить размер файлов CSS, удалив неиспользуемые правила CSS и оставив только необходимые. css-minimizer-webpack-plugin находит все неиспользуемые стили. Затем этот плагин удалит эти неиспользуемые стили из вашего окончательного файла CSS, тем самым уменьшив его размер. Выполните приведенную ниже команду установки, чтобы установить css-minimizer-webpack-plugin:Добавим css-minimizer-webpack-plugin в конфигурацию Webpack. Во-первых, импортируйте плагин следующим образом:npm install css-minimizer-webpack-plugin --save-dev
Затем мы добавим новое свойство optimization в конфигурацию Webpack следующим образом:const CssMinimizerPlugin = require("css-minimizer-webpack-plugin");
Когда мы запускаем командуoptimization: { minimizer: [ new CssMinimizerPlugin() ], }
npm run build
, bundle.css
будет минифицироваться, но bundle.js
не будет. Стандартная минификация для bundle.js
была переопределена параметром minimizer
, который мы установили. Чтобы решить эту проблему, нам нужно минифицировать JavaScript с помощью TerserWebpackPlugin.
Минификация JavaScript
В текущей версии Webpack (на момент написания статьи 5.74.0) и более поздних, вам не нужно устанавливать TerserWebpackPlugin, так как он включен из коробки. Во-первых, мы должны импортировать TerserWebpackPlugin:Затем добавьте TerserPlugin в опцию минимизации следующим образом:const TerserPlugin = require("terser-webpack-plugin");
Если вы запустите скриптoptimization: { minimizer: [ new CssMinimizerPlugin(), new TerserPlugin() ], }
npm run build
и посмотрите на файлы в папке dist, вы увидите, что и JavaScript, и CSS минифицированы.
Использование CopyWebpackPlugin
Мы можем настроить Webpack для копирования ресурсов приложения из папки c исходными файлами в папку сборки dist с помощью CopyWebpackPlugin. Этот плагин может копировать такие файлы, как изображения, видео и другие ресурсы, в папкуdist
.
Установите CopyWebpackPlugin с помощью следующей команды:
Теперь добавим CopyWebpackPlugin в конфигурацию Webpack. Импортируйте плагин следующим образом:npm install copy-webpack-plugin --save-dev
Далее мы добавим CopyWebpackPlugin в опцию плагина. Свойствоconst CopyPlugin = require("copy-webpack-plugin");
from
— это папка, из которой мы будем копировать, а to
— это папка в каталоге dist, в которую нужно скопировать все файлы:
Создайте новую папку img и добавьте в нее изображения. После выполнения команды// ... plugins: [ new HtmlWebpackPlugin({ title: 'our project', template: 'src/custom.html' }), new MiniCssExtractPlugin({ filename: "bundle.css" }), new CopyPlugin({ patterns: [ { from: "src/img", to: "img" } ] }), ] // ...
npm run build
образы будут скопированы в dist/img
.
Отладка с помощью source map
Когда мы собираем пакет путем компиляции файлов TypeScript в файлы JavaScript (npm run build
), нам может потребоваться отладить и протестировать код с помощью DevTools нашего браузера.
При отладке кода инструментам разработки браузера вы заметите, что отображаются только собранные файлы. Всякий раз, когда в нашем коде TypeScript есть ошибка, она будет указана только в собранном файле, что затрудняет отслеживание ошибок в TypeScript для исправления. Тем не менее, с source map кода мы можем легко отлаживать TypeScript с помощью DevTools.
Source map кода отображают исходный файл, что упрощает отладку TypeScript и исправление кода и минимизированного кода JavaScript.
Файлы .map содержат сведения как об исходных файлах, так и о собранных файлах. DevTools использует этот файл для сопоставления исходного файла с собранным файлом.
Чтобы сгенерировать .map
для файлов пакета, нам нужно настроить как Webpack, так и TypeScript. В конфигурационном файле TypeScript добавьте sourceMap к параметру компилятора и присвойте ему значение true
:
Далее мы добавим свойство devtool в конфигурацию Webpack и установим его в{ "compilerOptions": { "noImplicitAny": true, "target": "ES5", "module": "ES2015", "sourceMap": true } }
true
, указав Webpack сгенерировать соответствующую карту исходного кода для каждого собранного файла:
Выполнив командуmodule.exports = { devtool: 'source-map', // ... }
npm run build
, вы сможете отлаживать исходный код напрямую.
Итоги
По мере того, как популярность TypeScript продолжает расти, Webpack стал важным вариантом для разработчиков, стремящихся оптимизировать свои проекты. С помощью плагинов Webpack мы можем оптимизировать ресурсы приложения TypeScript. В этом руководстве мы рассмотрели пошаговый процесс настройки Webpack с помощью TypeScript. Мы также узнали, как оптимизировать приложения TypeScript с помощью подключаемых модулей Webpack, и изучили отладку кода TypeScript с помощью карты исходного кода.Типизация функций с помощью 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; };