0Pricing
TypeScript Academy · Lekcja

Adnotacje typów JSDoc jako pomost

Dodawaj typy do plików JS za pomocą JSDoc przed konwersją.

Adnotacje typów JSDoc jako pomost to bezpłatna lekcja TypeScript Academy na CoddyKit. To lekcja 2 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej TypeScript Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs TypeScript Academy zawiera 4 lekcji w sumie.

JSDoc jako pomost do TypeScriptu

TypeScript może odczytywać adnotacje typów JSDoc w plikach JavaScript, gdy włączona jest opcja checkJs: true. Dzięki temu można dodawać typy do kodu JS bez zmiany nazw plików.

/** @type {string} */
let name = "Alice"; // TypeScript checks this as string

@param i @returns

Opisuj parametry funkcji i typy zwracanych wartości za pomocą tagów JSDoc.

/**
 * @param {string} name
 * @param {number} age
 * @returns {string}
 */
function greet(name, age) {
  return `${name} is ${age}`;
}

@typedef dla typów obiektów

Używaj @typedef, aby definiować wielokrotnego użytku aliasy typów w JSDoc.

/**
 * @typedef {Object} User
 * @property {string} id
 * @property {string} name
 * @property {boolean} isActive
 */

/** @type {User} */
const user = { id: "1", name: "Alice", isActive: true };

@template dla generyków

Używaj @template, aby zapisywać funkcje generyczne w JSDoc.

/**
 * @template T
 * @param {T[]} arr
 * @returns {T | undefined}
 */
function first(arr) {
  return arr[0];
}
// TypeScript infers: first<T>(arr: T[]): T | undefined

Importowanie typów z plików .ts

JSDoc obsługuje zapis @type {import("./types").User} służący do importowania typów TypeScriptu do plików JS.

/** @type {import("./types").User} */
const admin = { id: "admin", name: "Admin", isActive: true };

@ts-check do sprawdzania pojedynczych plików

Dodaj // @ts-check na początku pliku JS, aby włączyć sprawdzanie TypeScriptu tylko dla tego pliku, bez globalnego ustawiania checkJs: true.

// @ts-check
/** @type {number} */
const count = "oops"; // Error: string not assignable to number

@ts-ignore i @ts-expect-error

Pomijaj konkretne błędy typów JSDoc za pomocą dyrektyw umieszczanych w kodzie, bez wyłączania sprawdzania całego pliku.

// @ts-ignore
const x = badFunction(); // single error suppressed

// @ts-expect-error
const y = anotherBad(); // error expected here

Enumy w JSDoc

Symuluj enumy TypeScriptu w JSDoc za pomocą @enum.

/** @enum {string} */
const Direction = { Left: "left", Right: "right", Up: "up" };

Asercje typów w JSDoc

Używaj /** @type {SomeType} */ (expression) do tworzenia asercji typów JSDoc, odpowiedników as SomeType w TypeScript.

const el = /** @type {HTMLInputElement} */ (document.getElementById("input"));
el.value; // el: HTMLInputElement — typed

Kiedy przejść na .ts

Adnotacje JSDoc są pomostem, a nie celem. Gdy plik jest w pełni opisany adnotacjami i stabilny, zmień jego nazwę na .ts i usuń komentarze z typami JSDoc na rzecz natywnej składni TypeScriptu.

// Rename: utils.js → utils.ts
// Replace JSDoc: /** @param {string} x */ → (x: string)

Podsumowanie: JSDoc jako pomost

Adnotacje typów JSDoc umożliwiają sprawdzanie TypeScriptu w plikach JS bez zmiany ich nazw. Używaj @type, @param, @typedef i @template, aby stopniowo zwiększać bezpieczeństwo typów przed konwersją do natywnego TypeScriptu.

Szybkie sprawdzenie

Który tag JSDoc włącza sprawdzanie TypeScriptu w pojedynczym pliku bez globalnego checkJs?

Czego się Państwo nauczyli

Adnotacje typów JSDoc łączą JavaScript i TypeScript: używaj @type, @param, @typedef i @template, aby dodawać typy do plików JS. Włącz sprawdzanie dla pojedynczego pliku za pomocą // @ts-check, a następnie, gdy plik będzie gotowy, przekonwertuj go do natywnego TypeScriptu.

Często zadawane pytania

Czy lekcja „Adnotacje typów JSDoc jako pomost” jest bezpłatna?

Tak — pełny tekst „Adnotacje typów JSDoc jako pomost” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu TypeScript Academy, przejdź na CoddyKit PRO. Kurs TypeScript Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Adnotacje typów JSDoc jako pomost”?

Dodawaj typy do plików JS za pomocą JSDoc przed konwersją. Ćwiczysz TypeScript Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć TypeScript Academy?

Nie wymagamy żadnego doświadczenia. TypeScript Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 2 z 4.

Ile czasu zajmuje lekcja „Adnotacje typów JSDoc jako pomost”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji TypeScript Academy?

Tak. Każda lekcja TypeScript Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

  1. Rozpoczęcie migracji: allowJs i checkJs
  2. Adnotacje typów JSDoc jako pomost
  3. Strategia konwersji plik po pliku
  4. Praca z nietypowanymi bibliotekami firm trzecich
← Powrót do TypeScript Academy