0Pricing
TypeScript Academy · Lekcja

// @ts-check w JS; JSDoc do uzyskiwania typów

Włączanie sprawdzania typów w plikach .js za pomocą // @ts-check i JSDoc, dodawanie @param/@returns, @type/@typedef oraz @template dla wzorców generycznych i konfigurowanie tsconfig na potrzeby stopniowej migracji

// @ts-check w JS; JSDoc do uzyskiwania typów to bezpłatna lekcja TypeScript Academy na CoddyKit. To lekcja 1 z 1. 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 1 lekcji w sumie.

Wprowadzenie

Cel: Korzystać z zalet TypeScriptu wewnątrz plików .js. Należy włączyć // @ts-check, dodać typy JSDoc i skonfigurować tsconfig na potrzeby stopniowego wdrażania.

  • Sprawdzanie na poziomie pliku i całego projektu
  • @param, @returns, @type, @typedef
  • @template dla pomocników przypominających generyczne

Włączanie sprawdzania

Na początku pliku .js należy dodać // @ts-check. Adnotacje @param/@returns służą do dokumentowania i typowania funkcji.

// calculator.js
// @ts-check

/**
 * Adds two numbers.
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
export function add(a, b) {
  return a + b
}

// Usage: type errors appear if you pass non-numbers
// add("2", 3) // TS will flag this in JS

Typedef i type

Należy używać @typedef do definiowania wielokrotnie używanej struktury, a @type do opisywania typów zmiennych. Pola opcjonalne oznacza się za pomocą ?.

// models.js
// @ts-check

/** @typedef {{ id: string; name: string; age?: number }} User */

/** @type {User} */
export const currentUser = { id: "u1", name: "Ada" }

/**
 * Greets a user.
 * @param {User} u
 * @returns {string}
 */
export function greet(u) {
  return `Hello, ${u.name}!`
}

Parametry template

@template wprowadza parametry typów dla funkcji przypominających generyczne w JS. Wnioskowanie działa w miejscach wywołania.

// helpers.js
// @ts-check

/**
 * Maps items with a function, preserving types.
 * @template T,U
 * @param {T[]} items
 * @param {(x: T) => U} f
 * @returns {U[]}
 */
export function map(items, f) {
  const out = []
  for (const x of items) out.push(f(x))
  return out
}

// Inference: T=number, U=string
// map([1,2], n => n.toFixed(2))

tsconfig dla JS

W całym projekcie należy włączyć checkJs dla wszystkich plików .js. Ustawienie allowJs pozwala dołączyć pliki JS do programu. Należy użyć noEmit, gdy za generowanie wyników odpowiada bundler.

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "checkJs": true,
    "allowJs": true,
    "strict": true,
    "noEmit": true
  },
  "include": ["./**/*.js"],
  "exclude": ["node_modules"]
}

Wskazówki dotyczące migracji

Wskazówki dotyczące migracji:

  • Należy zacząć od kluczowych plików, używając // @ts-check.
  • Dla współdzielonych struktur należy tworzyć niewielkie deklaracje @typedef.
  • Po ustabilizowaniu typów warto stopniowo zmieniać rozszerzenie newralgicznych ścieżek na .ts.

Sprawdzenie ts-check

Szybkie sprawdzenie: Jak włączyć sprawdzanie TS w pliku .js?

Podsumowanie

Podsumowanie: Należy włączyć // @ts-check, dodać @param/@returns/@typedef/@template i zaostrzyć tsconfig dla projektów JS przed migracją do .ts.

Często zadawane pytania

Czy lekcja „// @ts-check w JS; JSDoc do uzyskiwania typów” jest bezpłatna?

Tak — pełny tekst „// @ts-check w JS; JSDoc do uzyskiwania typów” 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 1 lekcji w sumie.

Co nauczysz się w „// @ts-check w JS; JSDoc do uzyskiwania typów”?

Włączanie sprawdzania typów w plikach .js za pomocą // @ts-check i JSDoc, dodawanie @param/@returns, @type/@typedef oraz @template dla wzorców generycznych i konfigurowanie tsconfig na potrzeby stopn… Ć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 1 z 1.

Ile czasu zajmuje lekcja „// @ts-check w JS; JSDoc do uzyskiwania typów”?

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.

← Powrót do TypeScript Academy