Skip to content
TypeScript Book

Първи стъпки с TypeScript

Инсталация

Visual Studio Code предоставя отлична поддръжка за езика TypeScript, но не включва компилатора на TypeScript. За да инсталирате компилатора на TypeScript, можете да използвате пакетен мениджър като npm или yarn:

Terminal window
npm install typescript --save-dev

or

Terminal window
yarn add typescript --dev

Уверете се, че сте записвали генерирания файл за заключване (lockfile), за да гарантирате, че всеки член на екипа използва една и съща версия на TypeScript.

За да стартирате компилатора TypeScript, можете да използвате следните команди

Terminal window
npx tsc

or

Terminal window
yarn tsc

Препоръчително е да инсталирате TypeScript за всеки проект, а не глобално, тъй като това осигурява по-предвидим процес на изграждане. Въпреки това, за еднократни случаи, можете да използвате следната команда:

Terminal window
npx tsc

или инсталирате глобално:

Terminal window
npm install -g typescript

Ако използвате Microsoft Visual Studio, можете да получите TypeScript като пакет в NuGet за вашите MSBuild проекти. В конзолата NuGet Package Manager Console изпълнете следната команда:

Terminal window
Install-Package Microsoft.TypeScript.MSBuild

По време на инсталирането на TypeScript се инсталират два изпълними файла: “tsc” като компилатор на TypeScript и “tsserver” като самостоятелен сървър на TypeScript. Самостоятелният сървър съдържа компилатора и езиковите услуги, които могат да се използват от редакторите и IDE-тата, за да осигурят интелигентно попълване на кода.

Освен това има няколко транспайлъра, съвместими с TypeScript, като Babel (чрез плъгин) или swc. Тези транспайлъри могат да се използват за преобразуване на TypeScript код в други целеви езици или версии.

Конфигурация

TypeScript може да бъде конфигуриран чрез CLI опциите на tsc или чрез използването на специален конфигурационен файл, наречен tsconfig.json, който се поставя в основната директория (root) на проекта.

За да генерирате файл tsconfig.json, предварително попълнен с препоръчителни настройки, можете да използвате следната команда:

Terminal window
tsc --init

Когато изпълнявате командата tsc локално, TypeScript ще компилира кода, използвайки конфигурацията, зададена в най-близкия файл tsconfig.json.

Ето няколко примера за CLI команди, които се изпълняват с настройките по подразбиране:

Terminal window
tsc main.ts // Compile a specific file (main.ts) to JavaScript
tsc src/*.ts // Compile any .ts files under the 'src' folder to JavaScript
tsc app.ts util.ts --outfile index.js // Compile two TypeScript files (app.ts and util.ts) into a single JavaScript file (index.js)

Конфигурационен файл на TypeScript

Файлът tsconfig.json се използва за конфигуриране на компилатора TypeScript (tsc). Обикновено той се добавя в основната директория на проекта, заедно с файла package.json.

Забележки:

  • tsconfig.json има възможност за коментари, дори ако е в json формат.
  • Препоръчително е да използвате този конфигурационен файл вместо опциите на командния ред.

На следния линк можете да намерите пълната документация и нейната схема:

https://www.typescriptlang.org/tsconfig

https://www.typescriptlang.org/tsconfig/

По-долу е представен списък с често използвани и полезни конфигурации:

target

Свойството “target” се използва, за да се определи в коя версия на JavaScript ECMAScript трябва да се компилира вашият TypeScript. За съвременните браузъри ES6 е добър избор, а за по-старите браузъри се препоръчва ES5. Забележка: Поддръжката на ES5 беше премахната в TypeScript 6.0.

lib

Свойството “lib” се използва, за да се определи кои библиотечни файлове да се включат по време на компилацията. TypeScript автоматично включва API за функции, определени в свойството “target”, но е възможно да се пропуснат или да се изберат конкретни библиотеки за специфични нужди. Например, ако работите по сървър проект, можете да изключите библиотеката “DOM”, която е полезна само в среда с браузър.

strict

Опцията “strict” подобрява типова безопасността, като позволява по-строги проверки. Тя е активирана по подразбиране, считано от TypeScript 6.0; в противен случай трябва изрично да я зададете на true във вашия файл tsconfig.json. Активирането на “strict” позволява на TypeScript да:

  • Генерира код, използвайки “use strict” за всеки изходен файл.
  • Взема предвид “null” и “undefined” в процеса на проверка на типовете.
  • Деактивира използването на типа “any”, когато няма типови анотации.
  • Показва грешка при използването на израза “this”, който иначе би означавал типа “any”.

module

Свойството “module” задава модулната система, която се поддържа от компилираната програма. По време на изпълнение се използва модулен зареждач (module loader), който намира и изпълнява зависимостите според зададената модулна система.

Най-често използваните модулни зареждачи в JavaScript са Node.js CommonJS за сървърни приложения и RequireJS за AMD модули в уеб приложения, базирани на браузър. TypeScript може да генерира код за различни модулни системи, включително UMD, System, ESNext, ES2015/ES6 и ES2020. Модулната система трябва да се избира в зависимост от целевата среда и наличния механизъм за зареждане на модули в тази среда.

Забележка: Поддръжката на по-старите модулни системи (AMD, UMD, SystemJS) беше премахната в TypeScript 6.0.

moduleResolution

Свойството “moduleResolution” определя стратегията за разрешаване на модули. Използвайте “node” за модерен TypeScript код, докато стратегията “classic” се използва само за стари версии на TypeScript (преди 1.6).

esModuleInterop

Свойството “esModuleInterop” позволява импортиране на подразбиращи се експорти от CommonJS модули, които не са експортирали с помощта на свойството “default”. Това свойство предоставя shim, за да се осигури съвместимост в генерирания JavaScript. След активиране на тази опция можем да използваме import MyLibrary from "my-library" вместо import * as MyLibrary from "my-library".

Функциите “esModuleInterop” първоначално се активираха по избор, за да се избегнат промени, нарушаващи съвместимостта, но отдавна са препоръчителните настройки по подразбиране. Деактивирането им може да доведе до незабележими проблеми при изпълнението при използване на CommonJS с ESM. Забележка: Началото с TypeScript 6.0 това по-безопасно поведение при взаимодействието е винаги активирано.

jsx

Свойството “jsx” се прилага само за .tsx файлове, използвани в ReactJS, и контролира как JSX конструкциите се компилират в JavaScript. Често използвана опция е “preserve”, която ще компилира в .jsx файл, като запази JSX непроменен, за да може да бъде предаден на различни инструменти като Babel за по-нататъшни трансформации.

skipLibCheck

Свойството “skipLibCheck” ще попречи на TypeScript да проверява типовете на всички импортирани външни пакети. Това ще намали времето за компилация на проекта. TypeScript обаче все още ще проверява вашия код спрямо дефинициите на типовете, предоставени от тези пакети.

files

Свойството “files” указва на компилатора списък с файлове, които винаги трябва да бъдат включени в програмата.

include

Свойството “include” указва на компилатора списък с файлове, които искаме да включим. Това свойство позволява използването на glob-подобни шаблони, като ”*” за всяка поддиректория, "" за всяко име на файл и ”?” за опционални символи.

exclude

Свойството “exclude” указва на компилатора списък с файлове, които не трябва да бъдат включени в компилацията. Това може да включва файлове като “node_modules” или тестови файлове. Забележка: tsconfig.json позволява коментари.

importHelpers

TypeScript използва помощен код при генериране на код за определени усъвършенствани или down-level JavaScript функционалности. По подразбиране тези помощни функции се дублират във файловете, които ги използват. Опцията importHelpers вместо това импортира тези помощни функции от модула tslib, което прави изходния JavaScript по-ефективен.

Съвети за миграция към TypeScript

При големи проекти се препоръчва постепенна миграция, при който кодът на TypeScript и JavaScript първоначално ще съществуват едновременно. Само малки проекти могат да бъдат мигрирани към TypeScript наведнъж.

Първата стъпка в този преход е въвеждането на TypeScript в процеса на изграждане. Това може да се направи чрез използване на опцията на компилатора “allowJs”, която позволява на файловете .ts и .tsx да са заедно със съществуващите JavaScript файлове. Тъй като TypeScript ще използва типа “any” за променлива, когато не може да изведе типа от JavaScript файловете, се препоръчва да деактивирате “noImplicitAny” в опциите на компилатора в началото на миграцията.

Втората стъпка е да се уверите, че вашите JavaScript тестове работят заедно с TypeScript файловете, така че да можете да изпълнявате тестове, докато конвертирате всеки модул. Ако използвате Jest, обмислете използването на ts-jest, което ви позволява да тествате TypeScript проекти с Jest.

Третата стъпка е да включите декларации за типове за външни библиотеки във вашия проект. Тези декларации могат да бъдат намерени или вградени в самите библиотеки, или в DefinitelyTyped. Можете да ги търсите чрез https://www.typescriptlang.org/dt/search и да ги инсталирате, като използвате:

Terminal window
npm install --save-dev @types/package-name

or

Terminal window
yarn add --dev @types/package-name.

Четвъртата стъпка е да мигрирате модул по модул, като използвате подход “отдолу нагоре” и следвате графика на зависимостите, започвайки от крайните възли. Идеята е да започнете с преобразуването на модулите, които не зависят от други модули. За да визуализирате графиките на зависимостите, можете да използвате инструмента “madge”.

Подходящи модули за тези първоначални преобразувания са помощните функции и кодът, свързан с външни API-та или спецификации. Възможно е автоматично да генерирате дефиниции на типове в TypeScript от Swagger договори, GraphQL или JSON схеми, които да бъдат включени във вашия проект.

Когато няма налични спецификации или официални схеми, можете да генерирате типове от необработени данни, като например JSON, върнат от сървър. Препоръчително е обаче да генерирате типове от спецификации, а не от данни, за да избегнете пропускане на крайни случаи.

По време на миграцията се въздържайте от рефакториране на кода и се фокусирайте единствено върху добавянето на типове към вашите модули.

Петата стъпка е да активирате “noImplicitAny”, което ще наложи всички типове да бъдат известни и дефинирани, осигурявайки по-добра работа с TypeScript за вашия проект.

По време на миграцията можете да използвате директивата @ts-check, която активира проверката на типовете в TypeScript в JavaScript файл. Тази директива осигурява по-свободна форма на проверката на типовете и може първоначално да се използва за идентифициране на проблеми в JavaScript файлове. Когато @ts-check е включена във файл, TypeScript ще се опита да изведе дефиниции, използвайки коментари в стил JSDoc. Въпреки това, помислете за използването на JSDoc анотации само в много ранен етап от миграцията.

Също така е добре да запазите стойността по подразбиране на noEmitOnError в tsconfig.json като false. Това ще позволи генерирането на JavaScript код дори ако бъдат отчетени грешки.