Dokumentacja TypeScript
Zwięzła dokumentacja TypeScript oparta na przykładach. Przeczytaj o zagadnieniu, zobacz kod i przećwicz go na ścieżce Coddy.
Zacznij ścieżkę TypeScript z przewodnikiemPierwsze kroki
- Co to jest TypeScriptTypeScript to JavaScript ze statycznymi typami. Oznaczasz wartości typami, kompilator sprawdza je przed uruchomieniem kodu, a wynikiem jest zwykły JavaScript, który działa w każdej przeglądarce oraz w Node.js, Deno i Bun.
- TypeScript vs JavaScriptTypeScript to JavaScript z dodanym statycznym systemem typów, sprawdzanym przed uruchomieniem kodu. Porównaj oba języki obok siebie: składnię, błędy wyłapywane przez sprawdzanie typów, krok budowania, szybkość działania, próg wejścia i migrację projektu z JavaScriptu.
- Instalacja TypeScriptZainstaluj TypeScript przez npm jako zależność deweloperską projektu, sprawdź wersję poleceniem npx tsc --version, utwórz tsconfig.json przez tsc --init i skompiluj pierwszy plik. Obejmuje instalację globalną, pnpm, Yarn i Bun oraz najczęstsze błędy.
- Uruchamianie TypeScriptPięć sposobów na uruchomienie pliku .ts: kompilacja przez tsc i uruchomienie JavaScriptu, bezpośrednio przez node file.ts (type stripping), tsx lub ts-node albo Deno i Bun. Które sprawdzają typy, jaką składnię obsługuje każdy z nich i który wybrać.
- tsconfig.jsontsconfig.json oznacza folder jako projekt TypeScript i ustawia opcje kompilatora. Opcje, które mają znaczenie (target, module, moduleResolution, strict, rootDir, outDir, include, lib, types, noEmit, skipLibCheck), zalecana konfiguracja startowa, extends i zmiany w TypeScript 7.
- TypeScript 7TypeScript 7 to kompilator TypeScript przepisany w Go jako natywny program: około dziesięć razy szybszy, z tym samym poleceniem tsc i tym samym językiem. Co się zmieniło dla użytkowników (nowe wartości domyślne, usunięte opcje, brak API dla JavaScriptu), które narzędzia nadal potrzebują TypeScript 6 i jak zaktualizować projekt.
- KomentarzeTypeScript używa komentarzy JavaScriptu // i /* */ oraz komentarzy JSDoc /** */, które edytory pokazują po najechaniu kursorem. Odczytuje też kilka specjalnych komentarzy: @ts-expect-error, @ts-ignore, @ts-nocheck, @ts-check i dyrektywy /// <reference>.
- TypeScript vs PythonTypeScript i Python to języki wysokiego poziomu z garbage collectorem, ale TypeScript sprawdza typy przed uruchomieniem kodu, a type hints w Pythonie są opcjonalne i ignorowane w czasie wykonania. Porównanie typowania, środowiska uruchomieniowego, szybkości, ekosystemów i zastosowań, z tym samym programem w obu językach.
Typy podstawowe
- Typy podstawoweWbudowane typy TypeScript: string, number, boolean, bigint, symbol, null i undefined, a do tego krótko o tablicach i obiektach. Jak pisać adnotację typu, dlaczego nie ma typu całkowitego i dlaczego piszesz string zamiast String.
- Wnioskowanie typówTypeScript ustala większość typów na podstawie wartości, które piszesz. Zobacz, co wnioskuje dla zmiennych, let i const, obiektów, tablic i wartości zwracanych, jak callbacki dostają typy z kontekstu i gdzie nadal potrzebna jest adnotacja.
- StringiPraca ze stringami w TypeScript: interpolacja w template literal, stringi wielolinijkowe, sprawdzanie, czy string zawiera podciąg, najczęstsze metody i zwracane przez nie typy oraz typy literałów stringowych.
- String na numberZamiana stringa na liczbę w TypeScript przez Number(), parseInt(), parseFloat() albo jednoargumentowy +, to, jak każda z nich radzi sobie z "42px", "" i "1e3", bezpieczne sprawdzanie NaN oraz zamiana liczb z powrotem na stringi.
- TabliceJak typować tablice w TypeScript: T[] a Array<T>, tablice obiektów, tablice z kilkoma typami, tablice tylko do odczytu i co zwracają map, filter, reduce i find. Do tego pułapka z includes w tablicach literałów.
- Krotki (tuple)Krotka (tuple) w TypeScript to tablica o stałej liczbie elementów, których typy są znane według pozycji, na przykład [string, number]. Poznaj składnię, elementy nazwane, opcjonalne i rest, krotki readonly i as const, zwracanie krotek z funkcji oraz różnice między krotką a tablicą.
- Typy obiektoweJak typować obiekty w TypeScript: typy obiektowe inline, właściwości opcjonalne z ?, właściwości readonly, zagnieżdżone obiekty, metody, sprawdzanie nadmiarowych właściwości oraz różnica między object, {} i Object.
- EnumyEnum w TypeScript to nazwany zbiór stałych, na przykład enum Direction { Up, Down }. Poznaj enumy numeryczne i tekstowe, JavaScript, do którego kompiluje się enum, mapowanie odwrotne, iterowanie po enumie, const enum oraz sytuacje, w których lepiej sprawdza się unia literałów tekstowych albo obiekt as const.
Typy specjalne
- Typy literałoweTyp literałowy to typ z dokładnie jedną wartością, na przykład "GET" albo 404. Poznaj typy literałowe string, number i boolean, unie literałów, powód, dla którego let poszerza typ, a const nie, działanie as const i parametry typu const.
- any vs unknownZarówno any, jak i unknown przyjmują każdą wartość. any wyłącza sprawdzanie typów dla tej wartości, a unknown każe ci sprawdzić wartość, zanim jej użyjesz. Poznaj różnice, zawężanie unknown, noImplicitAny i miejsca, w których any wkrada się do otypowanego kodu.
- Typ nevernever to typ bez żadnych wartości. Jest typem zwracanym przez funkcje, które nigdy się nie kończą, typem, który zostaje, gdy zawężanie wykluczyło każdy przypadek, i narzędziem stojącym za wyczerpującym sprawdzaniem w switch. Zobacz, skąd się bierze i czym różni się od void.
- null i undefinedPrzy strictNullChecks null i undefined to osobne typy, które TypeScript każe ci obsłużyć. Zobacz, jak je sprawdzać, jak działa optional chaining (?.), podwójny znak zapytania (??) i ??=, oraz czym różni się właściwość opcjonalna od | undefined.
- Non-null assertion (!)Wykrzyknik po wartości, na przykład user!, to operator non-null assertion: usuwa null i undefined z typu bez żadnego sprawdzenia w czasie działania. Zobacz, co robi x!, jak działają formy definite assignment let x!: T i prop!: T, dlaczego są ryzykowne i jakie są bezpieczniejsze alternatywy.
Interfejsy i aliasy typów
- InterfejsyInterfejs nadaje nazwę kształtowi obiektu: jakie ma właściwości i jakiego typu jest każda z nich. Dowiedz się, jak go zadeklarować, czym są właściwości opcjonalne i readonly, metody, sygnatury indeksu, rozszerzanie, implementowanie w klasie, łączenie deklaracji, interfejsy generyczne i jak nadać interfejsowi wartości domyślne.
- Aliasy typówAlias typu nadaje nazwę dowolnemu typowi za pomocą słowa kluczowego type: kształtom obiektów, uniom, krotkom, funkcjom, typom generycznym i rekurencyjnym. Poznaj składnię, wygląd każdej formy i powód, dla którego alias to tylko nazwa, a nie nowy, osobny typ.
- Interface vs typeinterface i type mogą opisywać kształty obiektów i zwykle sprawdzi się każde z nich. Poznaj prawdziwe różnice: łączenie deklaracji, unie i mapped types, extends kontra przecięcia, niejawne sygnatury indeksu, komunikaty błędów i wydajność kompilatora, a do tego jasną regułę wyboru.
- Słowo kluczowe extendsSłowo kluczowe extends buduje jeden typ na podstawie drugiego. Zobacz, jak rozszerzyć interfejs (jeden lub kilka), rozszerzyć alias typu przez &, nadpisać typ właściwości, podmienić właściwości przez Omit i co znaczy extends w klasach, ograniczeniach generycznych i conditional types.
- Typy uniiTyp unii, taki jak string | number, oznacza, że wartość może mieć jeden z kilku typów. Zobacz, co można zrobić z unią (tylko to, co obsługuje każdy jej element), jak ją zawęzić, unie literałów i typów obiektów oraz różnicę między (A | B)[] a A[] | B[].
- Typy przecięciaTyp przecięcia A & B opisuje wartość, która jest jednocześnie A i B, więc ma wszystkie składowe obu. Dowiedz się, jak łączyć typy obiektowe przez &, dlaczego sprzeczne właściwości stają się never, jak przecięcia unii zostawiają tylko wspólne elementy i kiedy lepiej użyć extends.
- Unie dyskryminowaneUnia dyskryminowana to unia typów obiektowych, które mają wspólną właściwość-znacznik z typem literałowym, na przykład kind albo status. Sprawdzenie znacznika zawęża cały obiekt. Poznaj ten wzorzec, zawężanie w switch, wyczerpujące sprawdzenia z never i modelowanie wyników API, stanu żądań i maszyn stanów.
Funkcje
- FunkcjeJak typować funkcje w TypeScript: adnotacja każdego parametru, adnotacja albo wnioskowanie typu zwracanego, void dla funkcji, które nic nie zwracają, oraz typowanie funkcji strzałkowych, wyrażeń funkcyjnych, funkcji async i parametru this.
- Typy funkcjiJak zapisać typ funkcji w TypeScript: składnia strzałkowa (a: number) => string, aliasy typów dla funkcji, typowanie funkcji strzałkowych i callbacków, sygnatury wywołania i konstrukcji oraz dlaczego typ Function jest zbyt luźny.
- Parametry opcjonalneOznacz parametr w TypeScript jako opcjonalny przez ?, nadaj mu wartość domyślną albo zbierz dowolną liczbę argumentów parametrem rest. Omawiamy zasady kolejności, pominięcie a undefined, obiekty opcji i parametry opcjonalne w typach funkcji.
- Przeciążanie funkcjiPrzeciążenia funkcji w TypeScript pozwalają jednej funkcji mieć kilka sygnatur wywołania, każdą z własnym typem zwracanym. Poznaj wzorzec sygnatur przeciążeń i implementacji, reguły sprawdzane przez kompilator, sytuacje, w których lepszy jest parametr unii, oraz przeciążenia w klasach.
Zawężanie i sprawdzanie typów
- Zawężanie typówZawężanie to sposób, w jaki TypeScript zamienia szeroki typ, taki jak string | number, w konkretny wewnątrz if, switch albo po wczesnym return. Wszystkie formy zawężania w jednym miejscu: typeof, truthiness, równość, in, instanceof, przypisania, predykaty typów i discriminated unions.
- Operator typeoftypeof ma w TypeScript dwa zadania. W kodzie to operator JavaScriptu, który w czasie wykonania zwraca "string", "number", "object" i tak dalej, a TypeScript na jego podstawie zawęża typy. W typie to zapytanie o typ, które kopiuje typ zmiennej, jak w keyof typeof obj i ReturnType<typeof fn>.
- Operator instanceofinstanceof sprawdza w czasie działania, czy obiekt został utworzony przez daną klasę, a TypeScript zawęża zmienną do tej klasy. Jak działa z twoimi klasami i podklasami Error, dlaczego nie sprawdzi interfejsów ani aliasów typów i kiedy daje zaskakujące wyniki.
- Type guardsType guard to sprawdzenie w czasie wykonania, które TypeScript rozumie. Poznaj wbudowane type guardy, pisanie własnych z predykatem value is Type, sprawdzanie, czy obiekt ma dany typ, funkcje asercji z asserts i walidację danych typu unknown.
- Asercje typówSłowo kluczowe as każe TypeScriptowi traktować wartość jako inny typ. To nie jest rzutowanie: w czasie wykonania nic nie jest konwertowane ani sprawdzane. Poznaj składnię as i nawiasów ostrych, na co pozwala kompilator, podwójne asercje przez unknown i sytuacje, w których lepszym narzędziem jest type guard.
- Operator satisfiesOperator satisfies sprawdza, czy wartość pasuje do typu, nie zmieniając jej wywnioskowanego typu. Zobacz, co robi, jak wypada na tle adnotacji typu i as (ten sam obiekt zapisany na trzy sposoby), jak łączy się z as const i dlaczego pasuje do obiektów konfiguracji.
Klasy
- KlasyKlasy w TypeScript to klasy JavaScript z otypowanymi polami, metodami i konstruktorami. Zobacz, jak działają deklaracje pól i strictPropertyInitialization, jak typować this, gettery i settery, składowe statyczne, implements i jak klasa służy jednocześnie jako typ.
- KonstruktoryJak typować konstruktor klasy w TypeScript: otypowane i opcjonalne parametry, właściwości parametrów w rodzaju constructor(private name: string), kolejność inicjalizacji pól, przeciążenia konstruktora, wywołania super w podklasach, prywatne konstruktory i typy konstruktorów z new.
- Modyfikatory dostępuTypeScript ma trzy modyfikatory dostępu, public, private i protected, oraz readonly. Zobacz, na co pozwala każdy z nich, dlaczego private w TypeScript to tylko sprawdzenie w czasie kompilacji, a pola #private z JavaScript są egzekwowane w czasie działania, i który wybrać.
- DziedziczenieDziedziczenie klas w TypeScript: extends i super, nadpisywanie metod ze zgodnymi typami, słowo kluczowe override i noImplicitOverride, składowe protected, ponowna deklaracja pól przez declare oraz sytuacje, w których lepszym narzędziem jest implements.
- Klasy abstrakcyjneKlasa abstrakcyjna w TypeScript to klasa bazowa, której nie da się utworzyć przez new i która może zostawić metody do zaimplementowania podklasom. Poznaj metody i właściwości abstrakcyjne, wzorzec template method, abstrakcyjne typy konstruktorów i sytuacje, w których lepszy jest interfejs.
- DekoratoryDekoratory to funkcje, które opakowują albo zastępują składowe klas za pomocą składni @. Poznaj standardowe dekoratory, które TypeScript obsługuje bez żadnej flagi (klasy, metody, gettery, pola i akcesory), fabryki dekoratorów, addInitializer i różnice względem starszego experimentalDecorators używanego przez Angular i NestJS.
Typy generyczne
- GenerykiGeneryki pozwalają funkcji, interfejsowi, typowi lub klasie działać z wieloma typami i zachować między nimi powiązanie: to, co wchodzi, decyduje o tym, co wychodzi. Poznaj funkcje generyczne, wnioskowanie argumentów typu, kilka parametrów typu, generyczne interfejsy i klasy, wartości domyślne i sytuacje, w których generyki są zbędne.
- Ograniczenia generyczneOgraniczenie generyczne, T extends Coś, zawęża typy, które przyjmuje parametr typu, i pozwala funkcji używać tego, co gwarantuje ograniczenie. Omawia extends z kształtami obiektów i interfejsami, K extends keyof T dla bezpiecznego dostępu do właściwości, ograniczenia do prymitywów i typowe błędy.
Operatory typów
- Operator keyofkeyof bierze typ obiektowy i daje unię nazw jego właściwości. Poznaj keyof z interfejsami, keyof typeof dla zwykłych obiektów, typowany dostęp do właściwości z generykami, sygnatury indeksu (string | number) i powód, dla którego Object.keys zwraca string[].
- Indexed access typesTyp dostępu indeksowanego odczytuje typ właściwości z innego typu: Person["age"] to number. Poznaj T["key"], klucze w unii, T[keyof T], T[number] dla elementów tablicy, indeksy krotek i (typeof arr)[number], które zamienia tablicę const w unię.
- Mapped typesMapped type buduje nowy typ obiektowy, przechodząc w pętli po kluczach: { [K in keyof T]: ... }. Poznaj składnię, modyfikatory readonly i ? z + i -, zmianę nazw kluczy przez as, filtrowanie kluczy oraz to, jak zapisane są Partial, Readonly, Required, Pick i Record.
- Typy warunkoweTyp warunkowy wybiera jeden z dwóch typów na podstawie testu: T extends U ? X : Y. Poznaj składnię, rozdzielanie typów warunkowych po uniach (i jak je wyłączyć), wyciąganie typów przez infer i samodzielne napisanie ReturnType.
- Template literal typesTemplate literal types budują typy literałów string tą samą składnią z backtickami co template stringi w JavaScripcie: `on${Capitalize<E>}`. Poznaj składnię, mnożenie unii, Uppercase i Capitalize, wzorce takie jak `${number}px`, gettery w mapped types i parsowanie stringów z infer.
- Branded typesBranded type to typ prosty z niewidocznym znacznikiem, na przykład string & { readonly __brand: "UserId" }, dzięki czemu UserId nie da się przekazać tam, gdzie oczekiwany jest OrderId. Zobacz, jak działają brandy, funkcje tworzące z walidacją, generyczny pomocnik Brand, brandy z unique symbol i oznaczone liczby.
Typy narzędziowe
- Utility typesWszystkie wbudowane utility types TypeScript w jednym miejscu: Partial, Required, Readonly, Pick, Omit, Record, Exclude, Extract, NonNullable, Parameters, ReturnType, Awaited, typy dla stringów i inne, każdy z jednozdaniowym opisem i przykładem do uruchomienia.
- RecordRecord<K, V> to typ obiektu, którego klucze są typu K, a wszystkie wartości typu V. Zobacz Record z kluczami string i z kluczami z unii (każdy klucz wymagany), Partial<Record>, iterowanie po Record z otypowanymi kluczami, pułapkę brakującego klucza i kiedy zamiast tego użyć sygnatury indeksu lub Map.
- Partial i RequiredPartial<T> czyni każdą właściwość T opcjonalną, a to dokładnie typ obiektu aktualizacji lub łatki. Zobacz Partial w funkcjach aktualizujących, dlaczego jest płytki, jak napisać DeepPartial, pułapkę jawnego undefined oraz jego przeciwieństwo, Required<T>.
- OmitOmit<T, K> tworzy typ ze wszystkimi właściwościami T poza kluczami K. Zobacz Omit z jednym i kilkoma kluczami, nadpisywanie typu właściwości, usuwanie właściwości w czasie działania, Omit a Exclude i Pick, dlaczego Omit przyjmuje nieistniejące klucze, ścisły Omit oraz Omit na uniach.
- PickPick<T, K> tworzy typ zawierający tylko te właściwości T, których klucze są w K. Zobacz Pick z jednym lub kilkoma kluczami, jak sprawdza klucze, Pick a Omit, wybieranie z typów zagnieżdżonych, otypowaną funkcję pick() i wybieranie właściwości według typu wartości.
- readonly i ReadonlyModyfikator readonly i typ narzędziowy Readonly<T> blokują ponowne przypisywanie właściwości. Zobacz właściwości readonly i pola klas, Readonly<T>, tablice tylko do odczytu (readonly T[] i ReadonlyArray), ReadonlyMap i ReadonlySet, dlaczego readonly jest płytkie i działa tylko podczas kompilacji oraz jak wypada na tle Object.freeze i as const.
- Exclude i ExtractExclude, Extract i NonNullable filtrują człony typu unii. Dowiedz się, co każdy z nich zostawia, a co usuwa, jak wybierać człony unii po kształcie, jak są zbudowane z typów warunkowych i czym różnią się od Omit i Pick.
- ReturnType i ParametersReturnType, Parameters, ConstructorParameters, InstanceType i Awaited wyciągają typy z funkcji, klas i promise'ów. Zobacz, jak używać ich z typeof, jak uzyskać typ wyniku funkcji async, co się dzieje z przeciążeniami i funkcjami generycznymi oraz jak ReturnType jest zbudowany z infer.
Pętle i kolekcje
- PętleWszystkie sposoby iterowania w TypeScript i typy, które daje każdy z nich: klasyczna pętla for, for...of po tablicach, mapach i stringach, for...in i jego klucze typu string, forEach (bez break i await), typowane pętle po kluczach obiektu oraz while.
- Instrukcja switchInstrukcja switch w TypeScript: składnia, jak każdy case zawęża typ unii, wyczerpujący switch, który nie kompiluje się, gdy brakuje case, wzorzec switch (true), fallthrough i zasięg bloku.
- MapJak używać Map w TypeScript: tworzenie typowanego Map<K, V>, dlaczego get zwraca V | undefined, set, has i delete, iteracja w kolejności wstawiania, obiekty jako klucze, konwersja do obiektu i JSON oraz z powrotem, Map a obiekt i Record oraz typowanie array.map().
- SłownikTypeScript nie ma klasy słownika ani hashmapy; wyszukiwanie klucz-wartość typujesz sygnaturą indeksu, Record<K, V> albo Map<K, V>. Poznaj każde z nich, sprawdzanie, czy klucz istnieje, dodawanie, usuwanie i iterację oraz powód, dla którego noUncheckedIndexedAccess ma znaczenie przy słownikach.
Asynchroniczność i błędy
- PromiseJak typuje się promise w TypeScript: typ Promise<T>, typowanie new Promise i resolve, jak then zmienia typ, dlaczego catch daje any, Promise.all z wynikami w krotce, typy wyników Promise.allSettled oraz opakowywanie API z callbackami w otypowany promise.
- Async/awaitJak typowane są async i await w TypeScript: funkcja async zwraca Promise<T>, await go rozpakowuje, błędy łapie się przez try/catch, await na najwyższym poziomie wymaga modułu ES, a do tego różnica między czekaniem po kolei, czekaniem równoległym i pułapką z forEach.
- Obsługa błędówObsługa błędów w TypeScript: dlaczego zmienna w catch ma typ unknown, jak zawęzić ją przez instanceof Error, jak rzucać błędy, pisać własne klasy błędów z name i cause oraz stosować wzorzec typu Result dla błędów, których się spodziewasz.
- SleepTypeScript nie ma wbudowanego sleep, ale jedna linia wystarczy, żeby go mieć: funkcja zwracająca Promise<void>, który rozwiązuje setTimeout. Zobacz, jak na niego czekać przez await, jak robić pauzy w pętlach, ponawiać z opóźnieniem, anulować sleep i dlaczego w JavaScripcie nie ma blokującego sleep.
Moduły i narzędzia
- ModułyKażdy plik TypeScript z importem lub eksportem na najwyższym poziomie jest modułem. Poznaj eksporty nazwane i domyślne, import type i export type, to, jak opcja module decyduje o wyjściu jako ES module lub CommonJS, i dlaczego node16 i nodenext wymagają rozszerzeń .js w importach.
- NamespacesNamespace w TypeScript grupuje wartości i typy pod jedną nazwą i kompiluje się do zwykłego obiektu. Poznaj składnię, łączenie namespace'ów ze sobą oraz z funkcjami i klasami, powód, dla którego zastąpiły je ES modules, i miejsca, gdzie wciąż je spotkasz: pliki deklaracji i rozszerzanie globalnego zakresu.
- Pliki deklaracjiPlik .d.ts opisuje typy kodu JavaScript, nie zawierając go, a słowo kluczowe declare robi to samo wewnątrz pliku .ts. Zobacz, jak generuje się pliki deklaracji, gdzie pasują pakiety @types, jak otypować moduł bez typów i jak declare global oraz rozszerzanie modułów poszerzają istniejące typy.
- Tryb strictstrict: true w tsconfig.json włącza całą rodzinę sprawdzeń typów: noImplicitAny, strictNullChecks, strictPropertyInitialization i pięć kolejnych. Zobacz, co wyłapuje każde z nich, jak włączyć tryb strict w istniejącym projekcie i jakie przydatne flagi nie należą do strict.
- JSONJSON.parse zwraca any, więc TypeScript ufa każdemu typowi, który nadasz wynikowi. Dowiedz się, jak typować sparsowany JSON, walidować go przez type guard, zamienić próbkę JSON w interfejs, importować pliki .json i co JSON.stringify robi z Date, Set i undefined.
Idąc dalej
- Dobre praktykiOsiem nawyków w TypeScript, które zapobiegają prawdziwym błędom: zostaw strict włączone, używaj unknown zamiast any, pozwól działać wnioskowaniu, wybieraj unie zamiast enumów, sprawdzaj konfigurację przez satisfies, modeluj stan uniami dyskryminowanymi, unikaj ! i as, a dane oznaczaj jako readonly. Każda zasada ma uruchamialny przykład przed i po.
- Pytania rekrutacyjne25 pytań rekrutacyjnych z TypeScript z krótkimi, poprawnymi odpowiedziami i kodem, od poziomu początkującego do zaawansowanego: any kontra unknown, interface kontra type, generyki, zawężanie, utility types, mapped i conditional types, typowanie strukturalne, tsconfig i TypeScript 7.
