TypeScript Interface: תחביר, מאפיינים אופציונליים, מתודות ודוגמאות

interface נותן שם למבנה של אובייקט: המאפיינים שחייבים להיות לו והטיפוס של כל אחד. אחרי ההצהרה משתמשים בשם כטיפוס, והקומפיילר בודק מולו כל אובייקט שמעבירים, מחזירים או משימים.

interface User {
  id: number;
  name: string;
  email?: string; // optional
}

function describe(user: User): string {
  return `#${user.id} ${user.name} <${user.email ?? "no email"}>`;
}

const ada: User = { id: 1, name: "Ada Lovelace", email: "ada@example.com" };

console.log(describe(ada));                       // #1 Ada Lovelace <ada@example.com>
console.log(describe({ id: 2, name: "Alan Turing" })); // #2 Alan Turing <no email>

// @ts-expect-error: Property 'name' is missing in type '{ id: number; }' but required in type 'User'.
describe({ id: 3 });

הקריאה האחרונה היא שגיאת הקומפילציה TS2741. interfaces נמחקים כשהקוד מתקמפל: בפלט ה-JavaScript אין שום זכר ל-User, ושום דבר לא בודק את המבנה בזמן ריצה.

הצהרה על interface

התחביר הוא מילת המפתח interface, שם (לפי המוסכמה ב-PascalCase), וגוף שמפרט איברים. אפשר להפריד בין איברים בנקודה-פסיק, בפסיקים או סתם בשורות חדשות; נקודה-פסיק היא הסגנון הנפוץ.

interface Product {
  sku: string;               // required property
  price: number;
  tags: string[];            // array property
  dimensions: {              // nested object type
    width: number;
    height: number;
  };
  discount?: number;         // optional property
  readonly createdAt: Date;  // cannot be reassigned
  label(): string;           // method
}

interface הוא טיפוס, לא ערך. אי אפשר ליצור ממנו מופע עם new, אין לו ערכי ברירת מחדל, ו-obj instanceof Product היא השגיאה TS2693 ('Product' only refers to a type, but is being used as a value here). כדי לבדוק מבנה בזמן ריצה, כתבו type guard.

טיפוסיות מבנית ובדיקת מאפיינים עודפים

TypeScript משווה מבנים, לא שמות. כל אובייקט עם המאפיינים הנדרשים מתאים ל-interface, בין אם הוא הוצהר איתו ובין אם לא. מאפיינים נוספים מותרים, עם חריג אחד: ליטרל אובייקט שנכתב ישירות במקום שבו מצופה ה-interface עובר בדיקת מאפיינים עודפים, כי מפתח לא מוכר שם הוא כמעט תמיד שגיאת כתיב.

interface Point {
  x: number;
  y: number;
}

function distance(p: Point): number {
  return Math.hypot(p.x, p.y);
}

const saved = { x: 3, y: 4, label: "A" }; // never declared as a Point
console.log(distance(saved));             // 5: the shape matches

// @ts-expect-error: Object literal may only specify known properties, and 'label' does not exist in type 'Point'.
distance({ x: 3, y: 4, label: "A" });

השגיאה הזו (TS2353) היא מה שתופס את { id: 1, name: "a", emial: "x" } עבור User: הקומפיילר אפילו מציע Did you mean to write 'email'? (TS2561).

מאפיינים אופציונליים ו-readonly

? אחרי השם הופך מאפיין לאופציונלי: האובייקט יכול להשמיט אותו, וקריאה שלו נותנת T | undefined. readonly אוסר להשים מחדש את המאפיין אחרי שהאובייקט נוצר.

interface Config {
  readonly apiUrl: string;
  readonly hosts: readonly string[];
  timeoutMs?: number;
}

const config: Config = { apiUrl: "https://api.example.com", hosts: ["a", "b"] };

// @ts-expect-error: Cannot assign to 'apiUrl' because it is a read-only property.
config.apiUrl = "http://localhost";
// @ts-expect-error: Property 'push' does not exist on type 'readonly string[]'.
config.hosts.push("c");

console.log(config.timeoutMs ?? 5000); // 5000: optional, so check or default it

const local = { ...config, apiUrl: "http://localhost" }; // a changed copy is fine
console.log(local.apiUrl); // http://localhost

// readonly is a compile-time rule attached to this type only:
const writable: { apiUrl: string } = config; // allowed
writable.apiUrl = "changed";
console.log(config.apiUrl); // changed

כאן רואים שתי מגבלות. ראשית, readonly קיים רק בזמן הקומפילציה: שתי השורות שמסומנות ב-@ts-expect-error עדיין רצות כשלוחצים על Run, והן מצליחות, והשורות האחרונות משנות את apiUrl דרך הפניה שהטיפוס שלה בלי readonly. שנית, הוא רדוד: readonly hosts: string[] היה מונע השמה מחדש של hosts אבל עדיין מאפשר hosts.push(...), ולכן המערך עצמו מקבל את הטיפוס readonly string[]. הוא מתעד ואוכף כוונה בקוד עם טיפוסים; הוא לא מקפיא שום דבר. ה-utility type Readonly<T> הופך בבת אחת כל מאפיין של interface קיים ל-readonly.

מתודות ומאפיינים של פונקציות

אפשר לכתוב מתודה כחתימת מתודה, name(params): ReturnType, או כמאפיין שמחזיק פונקציה, name: (params) => ReturnType. מי שקורא להן משתמש בשתיהן באותה דרך.

interface Counter {
  count: number;
  increment(by?: number): void; // method signature
  reset: () => void;            // property holding a function
}

function createCounter(): Counter {
  return {
    count: 0,
    increment(by = 1) {
      this.count += by; // this is typed as Counter
    },
    reset() {
      this.count = 0;
    },
  };
}

const c = createCounter();
c.increment();
c.increment(5);
console.log(c.count); // 6
c.reset();
console.log(c.count); // 0

ההבדל עדין: תחת strictFunctionTypes (חלק מ-strict), פרמטרים של מאפיינים מטיפוס פונקציה נבדקים בקפדנות, ואילו חתימות מתודה נבדקות בצורה רופפת יותר (bivariantly), ולכן צורת המאפיין תופסת עוד כמה טעויות. תחביר המתודה קצר יותר והוא הסגנון הנפוץ יותר; שניהם בסדר.

interface יכול גם לתאר משהו שאפשר לקרוא לו או לבנות אותו, עם חתימת קריאה או חתימת בנייה:

interface Formatter {
  (value: number): string; // call signature: the object is a function
  locale: string;          // and it also has a property
}

interface PointConstructor {
  new (x: number, y: number): { x: number; y: number }; // construct signature
}

Index signatures

כששמות המאפיינים לא ידועים מראש, index signature מתארת את כולם בבת אחת: [key: string]: T אומר "כל מפתח מחרוזת, וכל אחד מחזיק T".

interface Scores {
  [player: string]: number;
}

const scores: Scores = { ada: 90, alan: 85 };
scores.grace = 95; // any string key is allowed
scores["linus"] = 70;

for (const [player, score] of Object.entries(scores)) {
  console.log(player, score);
}

const missing = scores.nobody; // typed number, actually undefined
console.log(missing);          // undefined

השורות האחרונות מראות את המלכודת: קריאה של מפתח שלא קיים מקבלת את הטיפוס number, לא number | undefined. אפשרות הקומפיילר noUncheckedIndexedAccess מוסיפה | undefined לכל קריאה כזו.

מאפיינים עם שם יכולים לשבת ליד index signature, אבל הם חייבים להתאים לה. interface Dict { [key: string]: number; name: string } היא השגיאה TS2411, Property 'name' of type 'string' is not assignable to 'string' index type 'number'. הרחיבו את טיפוס האינדקס ([key: string]: number | string) או העבירו את החלק הדינמי למאפיין משלו. למפות פשוטות של מפתח וערך, Record<string, number> אומר את אותו דבר בשורה אחת.

הרחבה של interface

extends בונה interface חדש מתוך interface קיים אחד או יותר. לילד יש כל איבר של ההורה, ובנוסף האיברים שלו:

interface Animal {
  name: string;
}

interface Pet extends Animal {
  owner: string;
}

interface Trained {
  commands: string[];
}

interface ServiceDog extends Pet, Trained {
  certifiedUntil: Date;
}

// ServiceDog requires: name, owner, commands, certifiedUntil

ילד יכול להצהיר מחדש על מאפיין של ההורה רק עם טיפוס תואם (צר יותר), כמו kind: "dog" כשההורה אומר kind: string. הכללים, ואיך מרחיבים type aliases, נמצאים בעמוד על extends.

מימוש interface במחלקה

class X implements Shape מבקש מהקומפיילר לבדוק שיש למחלקה את כל מה שה-interface דורש. איבר חסר הוא שגיאה בהצהרת המחלקה:

// This does not compile: Circle is missing area()
interface Shape {
  name: string;
  area(): number;
}

class Circle implements Shape {
  name = "circle";
  constructor(public radius: number) {}
}

console.log(new Circle(2).name);

index.ts(7,7): error TS2420: Class 'Circle' incorrectly implements interface 'Shape'.
  Property 'area' is missing in type 'Circle' but required in type 'Shape'.

אחרי שמוסיפים את area(), כמה מחלקות ואפילו אובייקט רגיל יכולים כולם לשמש כ-Shape:

interface Shape {
  name: string;
  area(): number;
}

class Circle implements Shape {
  name = "circle";
  constructor(public radius: number) {}
  area() {
    return Math.PI * this.radius ** 2;
  }
}

class Rect implements Shape {
  name = "rect";
  constructor(public w: number, public h: number) {}
  area() {
    return this.w * this.h;
  }
}

// A plain object with the right shape is a Shape too: no class needed.
const unitSquare: Shape = { name: "unit square", area: () => 1 };

const shapes: Shape[] = [new Circle(1), new Rect(2, 3), unitSquare];
for (const s of shapes) {
  console.log(s.name, s.area().toFixed(2));
}

implements הוא רק בדיקה. הוא לא מוסיף איברים למחלקה, והוא לא נותן בשבילכם טיפוסים לפרמטרים של המתודות במחלקה: greet(name) {} בתוך מחלקה שמממשת greet(name: string): string היא עדיין השגיאה TS7006, Parameter 'name' implicitly has an 'any' type. מחלקה יכולה לממש כמה interfaces: class A implements B, C.

Declaration merging

הצהרה על interface עם אותו שם פעמיים באותו scope ממזגת את השתיים לאחת. זה משהו ש-type aliases לא יכולים לעשות (type שני עם אותו שם הוא שגיאת duplicate identifier).

interface Settings {
  theme: string;
}

interface Settings {
  fontSize: number;
}

// Settings now requires both properties
const s: Settings = { theme: "dark", fontSize: 14 };

בקוד של אפליקציה זה רק לעתים רחוקות מה שרוצים, ומיזוג בטעות יכול לבלבל. השימוש האמיתי שלו הוא הוספת איברים לטיפוסים שאינם שלכם: אפשרויות של ספרייה, או משתנה גלובלי כמו Window. מתוך מודול, עטפו את ההצהרה ב-declare global:

declare global {
  interface Window {
    analytics: { track(event: string): void };
  }
}

export {};

אחרי זה window.analytics.track("signup") עובר בדיקת טיפוסים בכל מקום בפרויקט. חבילות של הגדרות טיפוסים נשענות על אותו מנגנון; ראו declaration files.

ערכי ברירת מחדל למאפיינים של interface

interface לא יכול להחזיק ערכי ברירת מחדל, כי הוא מתאר טיפוסים ונמחק בזמן ריצה. size?: "sm" | "md" = "md" היא השגיאה TS1246, An interface property cannot have an initializer. הפכו את המאפיין לאופציונלי ומלאו את ברירת המחדל במקום שבו משתמשים באובייקט:

interface ButtonOptions {
  label: string;
  size?: "sm" | "md" | "lg";
  disabled?: boolean;
}

// 1. Destructuring defaults: applied when the value is undefined
function render({ label, size = "md", disabled = false }: ButtonOptions): string {
  return `[${label}] size=${size} disabled=${disabled}`;
}

// 2. Spread a defaults object under the options
const DEFAULTS = { size: "md", disabled: false } as const;

function withDefaults(options: ButtonOptions) {
  return { ...DEFAULTS, ...options };
}

console.log(render({ label: "Save" }));                   // [Save] size=md disabled=false
console.log(render({ label: "Save", size: undefined }));  // [Save] size=md disabled=false
console.log(withDefaults({ label: "Save", size: "lg" }));  // { size: 'lg', disabled: false, label: 'Save' }
console.log(withDefaults({ label: "Save", size: undefined }));
// { size: undefined, disabled: false, label: 'Save' }

ערכי ברירת מחדל של destructuring הם הבחירה הבטוחה יותר: הם חלים בכל פעם שהערך הוא undefined, כולל size: undefined מפורש. גרסת ה-spread מעתיקה את ה-undefined המפורש מעל ברירת המחדל, והתוצאה שלה עדיין מקבלת טיפוס כאילו size תמיד מוגדר. אם אתם צריכים את ההבטחה הזו מהטיפוסים, הפעילו את exactOptionalPropertyTypes, שהופך את size: undefined לשגיאת קומפילציה עבור size?: ... אופציונלי. מחלקה עם שדות מאותחלים היא האפשרות השנייה כשהאובייקט צריך גם התנהגות.

interfaces גנריים

interface יכול לקבל פרמטרי טיפוס, וכך הצהרה אחת עובדת עם הרבה טיפוסים של תוכן:

interface ApiResponse<T> {
  ok: boolean;
  data: T;
  error?: string;
}

interface Page<T> {
  items: T[];
  nextCursor?: string;
}

interface User {
  id: number;
  name: string;
}

const res: ApiResponse<Page<User>> = {
  ok: true,
  data: { items: [{ id: 1, name: "Ada" }], nextCursor: "abc" },
};

ApiResponse<Page<User>> נקרא כ"תשובה שהנתונים שלה הם עמוד של משתמשים". הספרייה הסטנדרטית מלאה באלה: Array<T>, Promise<T> ו-Map<K, V> הם כולם interfaces גנריים.

Interface מול type alias

type alias יכול לתאר את אותו מבנה אובייקט, ובטיפוסי אובייקט פשוטים אפשר להחליף בין השניים. רק interface יכול להתמזג; רק type alias יכול לתת שם ל-union, ל-tuple או ל-mapped type או conditional type. כלל האצבע של ה-handbook של TypeScript הוא להשתמש ב-interface עד שצריך תכונה שיש רק ל-type. בעמוד interface מול type יש את ההשוואה המלאה, כולל ההבדל של Record<string, ...> שמפתיע את רוב האנשים.