TypeScript Academy · درس

تعريف توقيعات الفهارس

صِفوا الكائنات التي لا تُعرف مفاتيحها مسبقًا

الدرس 1 من 413 خطوة

تعريف توقيعات الفهارس درس مجاني في TypeScript Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في TypeScript Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة TypeScript Academy 4 دروس في المجموع.

الكائنات ذات المفاتيح غير المعروفة

أحيانًا لا تعرفون أسماء الخصائص مسبقًا — مثل قاموس للدرجات، أو ذاكرة تخزين مؤقت، أو جدول بحث. يتيح لكم توقيع الفهرسة في TypeScript وصف كائن تكون مفاتيحه عشوائية، لكن قيمه تشترك في نوع واحد.

الصياغة الأساسية لتوقيع الفهرسة

يُكتب توقيع الفهرسة بالشكل { [key: string]: number }. وهذا يعني أن أي مفتاح نصي يرتبط بقيمة رقمية. الاسم key مجرد تسمية — ويمكنكم تسميته بأي اسم.

type Scores = { [name: string]: number }

const game: Scores = { alice: 10, bob: 7 }
console.log(game.alice) // 10

إضافة المفاتيح ديناميكيًا

بما أن كل مفتاح نصي مسموح، يمكنكم إسناد خصائص جديدة تمامًا في وقت التشغيل من دون أن يعترض TypeScript. هذه هي الفكرة الأساسية من توقيع الفهرسة.

type Scores = { [name: string]: number }

const game: Scores = {}
game.charlie = 5     // allowed
game["dave"] = 9     // also allowed
console.log(game.charlie + game.dave) // 14

الوصول إلى المفاتيح العشوائية

يمكنكم قراءة أي مفتاح، حتى المفتاح الذي لم يُعيَّن قط. يثق نظام الأنواع بتوقيع الفهرسة، لذلك يكون نوع القيمة هو number — لكن المفتاح غير الموجود يكون undefined في وقت التشغيل. لذا توخَّوا الحذر.

type Scores = { [name: string]: number }

const game: Scores = { alice: 10 }
const missing = game.zara // typed as number, but actually undefined
console.log(missing) // undefined

يجب أن تتوافق جميع القيم

يجب أن تتوافق كل خاصية في الكائن مع نوع القيمة المحدد في توقيع الفهرسة. لا يمكنكم مزج قيمة رقمية في قاموس قيمه نصية.

type Labels = { [key: string]: string }

const ok: Labels = { id: "a1", role: "admin" }
// const bad: Labels = { id: "a1", count: 5 } // Error: 5 not a string

توقيعات الفهرسة في الواجهات

تعمل الصياغة نفسها داخل interface. ويشيع استخدامها لوصف حاويات الإعدادات أو خرائط الاستجابات القادمة من API.

interface Dictionary {
  [word: string]: string
}

const defs: Dictionary = {
  cat: "a small animal",
  ts: "a typed superset of JavaScript",
}
console.log(defs.ts)

يمكن أن تكون أنواع القيم أي شيء

لا يقتصر جانب القيمة على الأنواع البدائية. يمكنكم ربط المفاتيح بمصفوفات أو كائنات أو اتحادات — أيًا كان ما تتطلبه بياناتكم.

type Groups = { [team: string]: string[] }

const roster: Groups = {
  red: ["ana", "leo"],
  blue: ["sam"],
}
console.log(roster.red.length) // 2

التكرار على كائنات توقيع الفهرسة

تزور حلقة for...in كل مفتاح ديناميكي. وداخل الحلقة تكون القيمة مكتوبة النوع بشكل صحيح وفقًا لتوقيع الفهرسة.

type Scores = { [name: string]: number }
const game: Scores = { alice: 10, bob: 7 }

for (const name in game) {
  console.log(name + ": " + game[name])
}

فجوة الأمان الخاصة بـ undefined

تخفي توقيعات الفهرسة حقيقة أن عمليات البحث قد تفشل. يؤدي تفعيل noUncheckedIndexedAccess في tsconfig إلى إضافة | undefined إلى كل عملية وصول، مما يجبركم على معالجة المفاتيح المفقودة.

// with noUncheckedIndexedAccess on:
type Scores = { [name: string]: number }
const game: Scores = { alice: 10 }
const v = game.bob // type: number | undefined
console.log(v ?? 0)

توقيعات الفهرسة للقراءة فقط

أضيفوا البادئة readonly إلى التوقيع لمنع الكتابة عبر أي مفتاح. وهكذا يصبح القاموس بنية مخصصة للبحث فقط.

type Frozen = { readonly [key: string]: number }

const rates: Frozen = { usd: 1, eur: 1.1 }
// rates.usd = 2 // Error: read-only
console.log(rates.eur)

متى تكون توقيعات الفهرسة مفيدة

استخدموا توقيع الفهرسة عندما تكون مجموعة المفاتيح مفتوحة النهاية ويُكتشف محتواها في وقت التشغيل، مثل ذاكرات التخزين المؤقت والعدادات المفهرسة بالمعرّفات ومعلمات الاستعلام المحللة. أما إذا كانت مجموعة المفاتيح ثابتة ومعروفة، ففضّلوا الخصائص الصريحة أو Record.

type Counter = { [event: string]: number }
const clicks: Counter = {}
function track(e: string) { clicks[e] = (clicks[e] ?? 0) + 1 }
track("open"); track("open")
console.log(clicks.open) // 2

تحقق سريع

اختبروا فهمكم لتوقيعات الفهرسة.

أجب عليها في الدرس التفاعلي

مراجعة

تعلّمتم أن { [key: string]: T } يصف كائنات ذات مفاتيح عشوائية، تشترك قيمها جميعًا في النوع T. ويمكن إضافة المفاتيح ديناميكيًا، ويجب أن تتوافق كل قيمة مع توقيع الفهرسة، بينما تكون عمليات البحث عن المفاتيح المفقودة بقيمة undefined في وقت التشغيل. استخدموا readonly للخرائط غير القابلة للتغيير، وفعّلوا noUncheckedIndexedAccess للوصول الأكثر أمانًا.

البدء مجانًا

تعلم TypeScript مع معلم ذكاء اصطناعي — مجانًا

اكتب وقم بتشغيل أكوادك الفعلية في المتصفح، واحصل على مساعدة فورية من معلم ذكاء اصطناعي متاح 24/7، واستمر من حيث توقفت على الويب أو في التطبيق.

الدورات: 101
الدروس: 352

ابدأ التعلم مجانًا عرض الدورة الكاملة

الأسئلة الشائعة

هل درس «تعريف توقيعات الفهارس» مجاني؟

نعم — نص درس «تعريف توقيعات الفهارس» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة TypeScript Academy، انتقل إلى CoddyKit PRO. تتضمن دورة TypeScript Academy 4 دروس في المجموع.

ماذا ستتعلم في «تعريف توقيعات الفهارس»؟

صِفوا الكائنات التي لا تُعرف مفاتيحها مسبقًا تتمرن على TypeScript Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ TypeScript Academy؟

لا تُشترط خبرة سابقة. TypeScript Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «تعريف توقيعات الفهارس»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس TypeScript Academy هذا؟

نعم. كل درس في TypeScript Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى TypeScript Academy