keyof في TypeScript: مفاتيح الكائن كنوع مع أمثلة

يأخذ keyof نوع كائن وينتج union من أسماء خصائصه. في المثال التالي keyof User هو النوع "id" | "name" | "email"، فلا يستطيع متغير من هذا النوع أن يحمل إلا أحد هذه النصوص الثلاثة.

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

type UserKey = keyof User; // "id" | "name" | "email"

const key: UserKey = "name"; // OK
// @ts-expect-error: "age" is not one of the keys of User
const wrong: UserKey = "age";

function printField(user: User, field: keyof User) {
  console.log(`${field}: ${user[field]}`);
}

const ada: User = { id: 1, name: "Ada", email: "ada@example.com" };
printField(ada, "email"); // email: ada@example.com
printField(ada, key);     // name: Ada

يوجد keyof في نظام الأنواع فقط. يُحذف عند ترجمة الكود، فلا يفحص شيئًا وقت التشغيل أبدًا. ما يعطيك إياه ضمان وقت الترجمة بأن المفتاح يسمّي خاصية حقيقية: أعد تسمية email في الـ interface فيصبح كل "email" نوعه keyof User خطأً.

keyof typeof: مفاتيح كائن عادي

يعمل keyof على الأنواع، لا على القيم. لكائن كتبته كقيمة، احصل على نوعه أولًا بـ typeof، ثم خذ المفاتيح:

const colors = {
  red: "#ff0000",
  green: "#00ff00",
  blue: "#0000ff",
};

type Color = keyof typeof colors; // "red" | "green" | "blue"

function hex(color: Color): string {
  return colors[color];
}

console.log(hex("green")); // #00ff00
// hex("purple") would be error TS2345:
// Argument of type '"purple"' is not assignable to parameter of type '"blue" | "green" | "red"'.

اقرأه من الداخل إلى الخارج: typeof colors هو { red: string; green: string; blue: string }، وkeyof لهذا النوع هو union المفاتيح. كتابة keyof colors دون typeof تفشل بالخطأ error TS2749: 'colors' refers to a value, but is being used as a type here. Did you mean 'typeof colors'?.

هذه هي الطريقة المعتادة لاشتقاق union من جدول بحث: أضف لونًا إلى الكائن فيكبر النوع Color معه. ولـ typeof معنى ثانٍ وقت التشغيل أيضًا؛ وتشرح صفحة typeof المعنيين.

الوصول إلى الخصائص بأنواع دقيقة عبر الـ Generics

أشيع استخدام لـ keyof هو قيد الـ generic. يقول K extends keyof T إن «K أحد مفاتيح T»، وT[K] هو نوع الخاصية عند ذلك المفتاح:

function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

const book = { title: "Dune", pages: 412, inStock: true };

const pages = getProperty(book, "pages"); // number
const title = getProperty(book, "title"); // string

console.log(pages + 1);           // 413
console.log(title.toUpperCase()); // DUNE
// getProperty(book, "author") would be error TS2345

معامل النوع الثاني مهم. مع key: keyof T دون K يكون نوع القيمة المُعادة T[keyof T]، أي union أنواع كل الخصائص (string | number | boolean هنا)، فيفشل title.toUpperCase() بالخطأ error TS2339: Property 'toUpperCase' does not exist on type 'string | number | boolean'. أما التقاط المفتاح الدقيق في K فيحافظ على نوع الخاصية الدقيق. وT[K] نوع وصول مفهرس (indexed access type)، تشرحه صفحة أنواع الوصول المفهرس.

الفهرسة بنص عادي

يظهر خطأ شائع جدًا حين تفهرس كائنًا بقيمة string جاءت من مكان آخر:

// This does not compile: a plain string is not a key of Settings
interface Settings {
  theme: string;
  fontSize: number;
}

const settings: Settings = { theme: "dark", fontSize: 14 };

function read(name: string) {
  return settings[name];
}

console.log(read("theme"));

يطبع المترجم:

index.ts(10,10): error TS7053: Element implicitly has an 'any' type because expression of type 'string' can't be used to index type 'Settings'.
  No index signature with a parameter of type 'string' was found on type 'Settings'.

قد يصل أي نص إلى read، بما في ذلك "colour"، وSettings لا يقول شيئًا عن هذا المفتاح. هناك حلان: اقبل المفاتيح الحقيقية فقط، أو افحص النص غير المعروف قبل استخدامه.

interface Settings {
  theme: string;
  fontSize: number;
}

const settings: Settings = { theme: "dark", fontSize: 14 };

// Fix 1: only accept real keys
function read(name: keyof Settings) {
  return settings[name];
}
console.log(read("fontSize")); // 14

// Fix 2: narrow a string you do not control
function isSettingsKey(name: string): name is keyof Settings {
  return Object.hasOwn(settings, name);
}

for (const input of ["theme", "colour"]) {
  if (isSettingsKey(input)) {
    console.log(input, "=", settings[input]);
  } else {
    console.log(input, "is not a setting");
  }
}
// theme = dark
// colour is not a setting

name is keyof Settings هي type predicate: حين تعيد الدالة true تعامل TypeScript القيمة input على أنها مفتاح داخل if. تشرح صفحة type guards الـ predicates بالتفصيل.

keyof مع توقيعات الفهرسة: string | number

للنوع الذي له توقيع فهرسة، يعيد keyof نوع الفهرس، وتوقيع الفهرسة النصي يعطي string | number وليس string فقط:

type Scores = { [player: string]: number };

type ScoreKey = keyof Scores; // string | number

const scores: Scores = { ada: 3 };
scores[42] = 7; // allowed: a number key is a valid key

console.log(Object.keys(scores)); // [ '42', 'ada' ]

type OnlyStrings = Extract<keyof Scores, string>; // string
const k: OnlyStrings = "ada";
console.log(k);

تحوّل JavaScript كل مفتاح خاصية رقمي إلى نص، فيكون scores[42] وscores["42"] الخاصية نفسها. وتعبّر TypeScript عن ذلك بإدخال number. ويبيّن الناتج أيضًا قاعدة في JavaScript: المفاتيح الشبيهة بالأعداد الصحيحة تُسرد أولًا، بترتيب تصاعدي، قبل المفاتيح النصية الأخرى. حين تحتاج دالة عامة إلى المفاتيح النصية فقط، اكتب Extract<keyof T, string> أو string & keyof T؛ ولـ Exclude وExtract صفحة خاصة.

نتائج keyof في لمحة

يبدو صفا الـ union والـ intersection معكوسين في البداية. القيمة من نوع union قد تكون أيًا من العضوين، فالآمن فقط المفاتيح الموجودة في كليهما. أما القيمة من نوع intersection فتحمل كل ما في النوعين، فلها كل المفاتيح.

لماذا يعيد Object.keys النوع string[]

نوع Object.keys(obj) هو string[]، وليس (keyof T)[] أبدًا. والسبب هو الأنواع البنيوية (structural typing): قد تحمل القيمة خصائص أكثر من نوعها المُعلن.

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

const point3d = { x: 1, y: 2, z: 3 };
const p: Point = point3d; // allowed: extra properties are fine here

console.log(Object.keys(p)); // [ 'x', 'y', 'z' ]

// When you know the object has exactly its declared keys, cast:
const origin = { x: 0, y: 0 };
for (const key of Object.keys(origin) as (keyof typeof origin)[]) {
  console.log(key, origin[key]);
}
// x 0
// y 0

نوع p هو Point، ومع ذلك له المفتاح z وقت التشغيل. لو وعد Object.keys بالنوع ("x" | "y")[] لكان الكود المعتمد على ذلك خاطئًا مع p. التأكيد آمن مع كائنات الـ literal التي أنشأتها بنفسك؛ أما الكائنات القادمة من الخارج فأبقِ مفاتيحها string وافحصها.

keyof في الأنواع المعيّنة (Mapped Types)

keyof هو أيضًا طريقة المرور على مفاتيح نوع لبناء نوع جديد. هكذا كُتبت أنواع الأدوات المدمجة Partial وReadonly:

type MyPartial<T> = { [K in keyof T]?: T[K] };
type MyReadonly<T> = { readonly [K in keyof T]: T[K] };

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

type UserDraft = MyPartial<User>; // { id?: number; name?: string }

يزور [K in keyof T] كل مفتاح، ويقرأ T[K] نوع الخاصية عند ذلك المفتاح. وللأنواع المعيّنة صفحة خاصة تشرح المعدّلات وإعادة تسمية المفاتيح.