Parametry opcjonalne w TypeScript: wartości domyślne i rest

Dodaj ? po nazwie parametru, żeby był opcjonalny. Wywołujący mogą go pominąć, a wewnątrz funkcji jego typ zawiera undefined.

function greet(name: string, title?: string): string {
  // title is string | undefined here
  return title ? `Hello, ${title} ${name}` : `Hello, ${name}`;
}

console.log(greet("Lovelace"));          // Hello, Lovelace
console.log(greet("Lovelace", "Lady"));  // Hello, Lady Lovelace

TypeScript sprawdza liczbę argumentów, więc bez ? pierwsze wywołanie byłoby błędem kompilacji: Expected 2 arguments, but got 1. (TS2554).

Parametry opcjonalne mogą być undefined

Ponieważ wywołujący może go pominąć, typ parametru opcjonalnego wewnątrz funkcji to T | undefined. Przy strictNullChecks musisz obsłużyć przypadek undefined, zanim użyjesz go jako T.

function formatPrice(amount: number, currency?: string): string {
  // currency.toUpperCase() here would fail: 'currency' is possibly 'undefined'. (TS18048)
  const code = currency?.toUpperCase() ?? "USD";
  return `${amount.toFixed(2)} ${code}`;
}

console.log(formatPrice(9.5));        // 9.50 USD
console.log(formatPrice(12, "eur"));  // 12.00 EUR

Optional chaining (?.) i nullish coalescing (??) to tu typowe narzędzia. Gdy wartość zastępcza jest stała, parametr domyślny jest krótszy.

Domyślne wartości parametrów

Wartość domyślna czyni parametr opcjonalnym dla wywołujących i nadaje mu typ bez undefined wewnątrz funkcji. Typ jest wnioskowany z wartości domyślnej, więc adnotacja często jest zbędna.

function repeat(text: string, times = 2, separator: string = " "): string {
  // times: number, separator: string (never undefined here)
  return Array.from({ length: times }, () => text).join(separator);
}

console.log(repeat("ha"));              // ha ha
console.log(repeat("ha", 3, "-"));      // ha-ha-ha
console.log(repeat("ha", undefined, "")); // haha

Wywołujący widzi sygnaturę repeat(text: string, times?: number, separator?: string). Wartości domyślne działają według reguły JavaScriptu: stosuje się je, gdy argument to undefined, pominięty lub przekazany jawnie, a nie gdy to null. Wyrażenie domyślne może używać wcześniejszych parametrów: function range(start: number, end = start + 10).

Zasady kolejności parametrów

Parametr z wartością domyślną przed wymaganym jest legalny, ale niewygodny. Dla wywołujących jego typ staje się number | undefined, a nikt nie lubi pisać undefined jako wypełniacza. Jeśli potrzebujesz elastycznego pierwszego parametru, użyj obiektu opcji albo przeciążania funkcji.

Pominięcie a undefined

x?: number i x: number | undefined wyglądają podobnie i mają ten sam typ wewnątrz funkcji. Różnią się dla wywołującego: pierwszy można pominąć, drugi trzeba przekazać.

function a(x?: number) { return x; }
function b(x: number | undefined) { return x; }

console.log(a());          // undefined
console.log(b(undefined)); // undefined
// @ts-expect-error: Expected 1 arguments, but got 0.
b();

Użyj | undefined dla wymaganego argumentu, który może nie mieć wartości, żeby każdy wywołujący musiał o nim pomyśleć. Użyj ?, gdy pominięcie to normalne wywołanie. (Komunikat naprawdę mówi "1 arguments": tak to formułuje TypeScript.)

Parametry rest

Parametr rest, ...name: T[], zbiera dowolną liczbę argumentów w tablicę. Musi być ostatnim parametrem.

function sum(...values: number[]): number {
  return values.reduce((total, v) => total + v, 0);
}

function tag(name: string, ...classes: string[]): string {
  return `<${name} class="${classes.join(" ")}">`;
}

console.log(sum());             // 0
console.log(sum(1, 2, 3));      // 6
const scores = [4, 8, 15];
console.log(sum(...scores));    // 27
console.log(tag("div", "card", "wide")); // <div class="card wide">

Rozkładanie tablicy na stałe parametry jest bardziej rygorystyczne. Parametr rest przyjmuje rozłożenie dowolnej number[], ale funkcja zadeklarowana jako (a: number, b: number) przyjmuje tylko rozłożenie krotki, bo TypeScript musi znać długość:

function point(x: number, y: number) { return { x, y }; }

const list = [3, 4];            // number[]
point(...list);
// error TS2556: A spread argument must either have a tuple type or be passed to a rest parameter.

const pair = [3, 4] as const;   // readonly [3, 4]
point(...pair);                 // fine

Parametr rest może też mieć typ krotki, który typuje każdą pozycję: ...args: [name: string, age?: number].

Obiekty opcji

Gdy funkcja ma więcej niż dwa lub trzy parametry opcjonalne, wywołujący gubią się w pozycjach. Obiekt opcji z wartościami domyślnymi daje nazwane argumenty w dowolnej kolejności.

interface FetchOptions {
  retries?: number;
  timeoutMs?: number;
  verbose?: boolean;
}

function fetchData(url: string, { retries = 3, timeoutMs = 5000, verbose = false }: FetchOptions = {}): string {
  return `${url} retries=${retries} timeout=${timeoutMs} verbose=${verbose}`;
}

console.log(fetchData("/a"));
// /a retries=3 timeout=5000 verbose=false
console.log(fetchData("/b", { verbose: true }));
// /b retries=3 timeout=5000 verbose=true

= {} na końcu czyni cały obiekt opcjonalnym. Bez tego fetchData("/a") to błąd kompilacji (Expected 2 arguments, but got 1., TS2554), a w zwykłym JavaScripcie to samo wywołanie rzuciłoby TypeError w czasie działania, bo destrukturyzacja potrzebuje obiektu, z którego czyta.

Parametry opcjonalne w typach callbacków

W typie funkcji ? oznacza "wywołujący ten callback może go nie przekazać". Nie oznacza "callback może go pominąć": callback zawsze może zignorować końcowe parametry. Nie oznaczaj więc parametrów callbacku jako opcjonalnych tylko po to, żeby handlery mogły przyjmować mniej argumentów.

// Too loose: every handler must now cope with index being undefined
type Visit = (item: string, index?: number) => void;

// Right: the caller always passes both; handlers may use only item
type VisitStrict = (item: string, index: number) => void;
const log: VisitStrict = (item) => console.log(item);