Treci la conținutul principal

Tipuri literale în TypeScript

Un tip literal este un tip care permite exact o singură valoare — de exemplu șirul "north" sau numărul 1 — în loc de orice șir sau orice număr.


Cum funcționează tipurile literale în TypeScript

Tipurile literale îți permit să spui exact ce valori poate avea o variabilă. Ele sunt mai precise decât tipurile generale string, number sau boolean.

Ele sunt cărămizile de bază pentru cod precis și sigur din punctul de vedere al tipurilor.

Concepte cheie:

  • Literali de tip șir: valori de șir exacte, precum "success" | "error"
  • Literali numerici: numere specifice, precum 1 | 2 | 3
  • Literali booleeni: fie true, fie false
  • Tipuri literale șablon: tipuri literale de șir construite cu sintaxa șirurilor șablon

Cazuri frecvente de utilizare:

  • Definirea unui set fix de valori permise
  • Crearea de uniuni discriminate
  • Tratarea evenimentelor în siguranță din punctul de vedere al tipurilor
  • Tiparea răspunsurilor de la un API
  • Obiecte de configurare

Tipuri literale de șir

Un tip literal de șir reprezintă o singură valoare de șir. De obicei, mai multe astfel de tipuri se combină cu | într-o uniune de valori permise.

Exemplu

direction poate conține doar unul dintre cele patru șiruri. Orice alt șir, cum ar fi "northeast", este o eroare de compilare, atât la atribuirea către variabilă, cât și la apelarea funcției move.

Prompt
Arată un tip uniune de literali de șir folosit pentru o variabilă și pentru un parametru de funcție. Declară direction cu tipul "north" | "south" | "east" | "west", atribuie-i "north" și apoi "south" și lasă comentate atribuirile de "northeast" și "up", împreună cu erorile pe care le-ar produce. Scrie o funcție move care primește aceeași uniune de literali și afișează Deplasare spre <direction>, apeleaz-o cu "east" și lasă comentat move("up") ca apel invalid.
Ieșire: program TypeScript și rezultatul capturat

Tipuri literale numerice

La fel ca literalii de șir, tipurile literale numerice reprezintă valori numerice specifice.

Exemplu

diceRoll acceptă doar numerele de la 1 la 6. Pentru că Math.random() returnează un number obișnuit, funcția rollDice are nevoie de o aserțiune de tip prin care promite că returnează unul dintre cei șase literali. Valoarea afișată se schimbă la fiecare rulare.

Prompt
Arată un tip uniune de literali numerici pentru valoarea unui zar. Declară diceRoll cu tipul 1 | 2 | 3 | 4 | 5 | 6, atribuie-i 1 și apoi 6 și lasă comentate atribuirile de 0, 7 și 2.5, împreună cu erorile lor. Scrie rollDice(), al cărei tip de retur este aceeași uniune și care returnează Math.floor(Math.random() * 6) + 1 convertit la acea uniune, apoi afișează Ai obținut un <result> (numărul este aleatoriu la fiecare rulare).
Ieșire: program TypeScript și rezultatul capturat

Tipuri literale booleene

Tipurile literale booleene se folosesc mai rar, pentru că există doar două valori booleene, dar sunt utile în anumite situații — de exemplu pentru a spune că o funcție returnează întotdeauna true.

Exemplu

alwaysSucceed trebuie să returneze literalul true. SuccessFlag și FailureFlag combină literali booleeni, de șir și numerici, iar processResult îi deosebește prin verificări simple de egalitate.

Prompt
Arată tipurile literale booleene folosite singure și combinate cu alți literali. Declară type YesOnly = true și o funcție alwaysSucceed() al cărei tip de retur este literalul true. Apoi declară SuccessFlag = true | "success" | 1 și FailureFlag = false | "failure" | 0, precum și o funcție processResult care primește oricare dintre ele și afișează Operațiunea a reușit atunci când valoarea este true, "success" sau 1, iar altfel afișează Operațiunea a eșuat. Apeleaz-o cu true, "success", 1 și false.
Ieșire: program TypeScript și rezultatul capturat

Tipuri literale cu obiecte

Tipurile literale pot fi folosite ca tipuri de proprietăți în interiorul tipurilor obiect. Astfel obții forme de obiect foarte precise.

Exemplu

HTTPSuccess și HTTPError limitează status și statusText la câteva valori literale fiecare. O simplă verificare de interval pe status nu restrânge uniunea, așa că exemplul folosește o mică gardă de tip isSuccess; în interiorul fiecărei ramuri, data sau error poate fi apoi folosit în siguranță.

Prompt
Arată tipuri literale folosite ca tipuri de proprietăți în interiorul tipurilor obiect, pentru a modela răspunsuri HTTP. Declară HTTPSuccess (status: 200 | 201 | 204, statusText: "OK" | "Created" | "No Content", data: any) și HTTPError (status: 400 | 401 | 403 | 404 | 500, literalii statusText corespunzători, error: string), plus HTTPResponse ca uniune a lor. Scrie o gardă de tip isSuccess (response is HTTPSuccess) care verifică dacă statusul este în intervalul 200 și o funcție handleResponse care o folosește pentru a afișa Succes: <statusText> și datele în caz de succes, iar altfel afișează Eroare <status>: <statusText> și Mesaj: <error>. Apeleaz-o cu un răspuns 200 "OK" care transportă { username: "john_doe", email: "[email protected]" } și cu un răspuns 404 "Not Found" cu eroarea Utilizatorul nu a fost găsit în baza de date.
Ieșire: program TypeScript și rezultatul capturat

Tipuri literale șablon

Începând cu TypeScript 4.1 poți construi tipuri literale de șir noi, combinându-le pe cele existente cu sintaxa șirurilor șablon, folosind accente grave și substituenți ${...}. Fiecare combinație a uniunilor din substituenți devine un membru al noii uniuni.

Exemplu

Exemplul pornește de la o uniune simplă DirectionAndDistance și ajunge la utilizări mai avansate: Capitalize pentru a construi nume de evenimente, un tip mapat care creează nume de getteri, infer pentru a extrage nume de parametri dintr-un șir de rută, un tip CssValue format din număr plus unitate și un constructor de interogări SQL tipat. Fișierul se încheie cu export {}, pentru ca tipul local EventTarget să nu intre în conflict cu tipul DOM încorporat.

Prompt
Arată tipuri literale șablon construite din uniuni de literali de șir, de la simplu la avansat. Combină uniunile Direction și Distance în DirectionAndDistance (`${Direction}-${Distance}`) și atribuie rute valide, cum ar fi "north-5km", unei variabile route. Apoi construiește EventName cu Capitalize, un tip mapat GetterName<T>/UserGetters peste un tip User, un tip recursiv ExtractRouteParams<T> care extrage numele :param dintr-o cale folosind infer, un tip CssValue de forma `${number}${CssUnit}`, un tip ApiUrl și o funcție query<T extends Table> al cărei tip de retur este `SELECT * FROM ${T}${string}`, apelată pentru tabelul users cu o WhereCondition. Lasă comentate atribuirile invalide. Nu se afișează nimic. Adaugă export {}; la final, pentru ca tipul local EventTarget să nu intre în conflict cu globala DOM încorporată.
Ieșire: program TypeScript și rezultatul capturat

Bune practici

Recomandat:

  • Folosește tipuri literale pentru seturi fixe de valori (opțiuni de tip enumerare, valori de configurare)
  • Combină-le cu tipuri uniune pentru mai multă siguranță a tipurilor
  • Folosește tipuri literale șablon pentru potrivirea tiparelor de șiruri
  • Lasă inferența de tip să lucreze pentru tine acolo unde se poate
  • Documentează ce înseamnă fiecare tip literal

De evitat:

  • Folosirea excesivă a tipurilor literale atunci când un tip mai general ar fi mai potrivit
  • Crearea de uniuni extrem de mari, care încetinesc verificarea tipurilor
  • Folosirea literalilor de șir atunci când o enumerare ar fi mai potrivită

Considerații de performanță

  • Uniunile mari de tipuri pot încetini verificarea tipurilor
  • Tipurile literale șablon complexe pot crește timpul de compilare
  • Folosește alias-uri de tip pentru a denumi tipurile literale complexe, în loc să le repeți
  • Ține cont de limitele de adâncime a recursivității din TypeScript pentru tipurile literale șablon recursive