Pick في TypeScript: اختيار خصائص من نوع (أمثلة)

Pick<T, K> نوع أداة مدمج ينشئ نوع كائن لا يحتوي إلا خصائص T المذكورة في K. استخدمه عندما تحتاج دالة أو مكوّن إلى بضعة حقول من نوع أكبر:

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

type UserPreview = Pick<User, "id" | "name">;
// { id: number; name: string }

function renderPreview(user: UserPreview): string {
  return `#${user.id} ${user.name}`;
}

const ada: User = {
  id: 1, name: "Ada", email: "ada@example.com",
  passwordHash: "x9f...", lastLogin: "2024-03-15",
};

console.log(renderPreview(ada));                  // #1 Ada
console.log(renderPreview({ id: 2, name: "Linus" })); // #2 Linus

تقبل renderPreview كائن User كاملًا وتقبل أيضًا كائنًا بسيطًا { id, name }، لأنها لا تطلب إلا ما تستخدمه. وهذا يسهّل استدعاءها واختبارها. Pick خاص بالأنواع فقط: ما زال كائن ada الكامل يملك خصائصه الخمس وقت التشغيل.

الصياغة وفحص المفاتيح

Pick<Type, Keys>

Keys مفتاح واحد أو union من المفاتيح، ويجب أن يكون كل منها موجودًا في Type. والتعريف في المكتبة القياسية لـ TypeScript يجعل ذلك قيدًا:

type Pick<T, K extends keyof T> = {
  [P in K]: T[P];
};

بسبب K extends keyof T يكون المفتاح المكتوب خطأً أو المفقود خطأ ترجمة، ويستطيع محررك إكمال أسماء المفاتيح تلقائيًا:

interface Product {
  sku: string;
  title: string;
  price: number;
  stock: number;
}

type PriceTag = Pick<Product, "title" | "price">;

const tag: PriceTag = { title: "Lamp", price: 39 };
console.log(`${tag.title}: $${tag.price}`); // Lamp: $39

// @ts-expect-error: Type '"cost"' does not satisfy the constraint 'keyof Product'
type Broken = Pick<Product, "cost">;

الخطأ هو error TS2344: Type '"cost"' does not satisfy the constraint 'keyof Product'. وهذا فرق عن Omit الذي لا تُفحص مفاتيحه.

Pick يحافظ على readonly والخصائص الاختيارية

يمر Pick على مفاتيح T، فتحتفظ كل خاصية مختارة بمُعدِّلاتها:

interface Account {
  readonly id: number;
  email?: string;
  plan: "free" | "pro";
}

type AccountRef = Pick<Account, "id" | "email">;
// { readonly id: number; email?: string }

const ref: AccountRef = { id: 7 }; // email is still optional
// @ts-expect-error: Cannot assign to 'id' because it is a read-only property
ref.id = 8;

console.log(ref); // { id: 8 }

يُظهر السطر الأخير { id: 8 } لأن readonly فحص وقت الترجمة فقط: بُلّغ عن الإسناد، ثم كُتم بـ @ts-expect-error، ومع ذلك نُفّذ. لتغيير المُعدِّلات أثناء الاختيار، غلّف النتيجة: Partial<Pick<Account, "plan">> أو Required<Pick<Account, "email">>.

Pick أم Omit

يسمّي Pick ما يُبقى؛ ويسمّي Omit ما يُحذف. كلاهما يعطي النتيجة نفسها اليوم، لكنهما يتصرفان بشكل مختلف عندما يكبر النوع المصدر:

interface Order {
  id: number;
  total: number;
  cardLast4: string;
  // added later: internalNotes: string;
}

type Receipt = Pick<Order, "id" | "total">;   // stays { id; total }
type AdminView = Omit<Order, "cardLast4">;    // will include internalNotes too

const receipt: Receipt = { id: 1, total: 49.9 };
const admin: AdminView = { id: 1, total: 49.9 };
console.log(receipt, admin); // { id: 1, total: 49.9 } { id: 1, total: 49.9 }

للبيانات التي تغادر خادمك، Pick هو الخيار الافتراضي الأكثر أمانًا: لا يظهر شيء في النوع ما لم يضفه أحد عن قصد.

الاختيار من أنواع متداخلة

لا يرى Pick إلا مفاتيح المستوى الأعلى: المسار المنقّط مثل Pick<Customer, "address.city"> خطأ (TS2344)، وليس اختيارًا متداخلًا. استخدم indexed access type للوصول إلى النوع المتداخل، ثم اختر منه:

interface Customer {
  id: number;
  name: string;
  address: {
    street: string;
    city: string;
    country: string;
  };
}

type City = Pick<Customer["address"], "city">; // { city: string }

// Keep the shape, trim the nested object
type ShippingLabel = Pick<Customer, "name"> & {
  address: Pick<Customer["address"], "city" | "country">;
};

const label: ShippingLabel = {
  name: "Ada",
  address: { city: "London", country: "UK" },
};

const city: City = { city: label.address.city };
console.log(label, city.city);
// { name: 'Ada', address: { city: 'London', country: 'UK' } } London

Customer["address"] هو نوع الخاصية address. والصياغة نفسها تصل إلى عناصر المصفوفات: لخاصية orders: Order[] يكون Customer["orders"][number] هو Order.

دالة pick() بأنواع صحيحة

لا يفعل Pick شيئًا وقت التشغيل. دالة generic صغيرة تنسخ الخصائص المختارة إلى كائن جديد وتعيد Pick<T, K> بالضبط:

function pick<T extends object, K extends keyof T>(obj: T, ...keys: K[]): Pick<T, K> {
  const result = {} as Pick<T, K>;
  for (const key of keys) {
    result[key] = obj[key];
  }
  return result;
}

const book = { id: 3, title: "Dune", author: "Herbert", pages: 412 };

const summary = pick(book, "title", "author"); // { title: string; author: string }
console.log(summary);          // { title: 'Dune', author: 'Herbert' }
console.log(Object.keys(summary)); // [ 'title', 'author' ]
// pick(book, "isbn") would be error TS2345: Argument of type '"isbn"' is not assignable
// to parameter of type '"author" | "id" | "pages" | "title"'.

يسمح K extends keyof T لـ TypeScript باستنتاج K من الوسائط النصية، فيكون لنوع القيمة المُعادة المفاتيح المختارة بالضبط. تأكيد النوع {} as Pick<T, K> ضروري لأن الكائن الفارغ لا يملك تلك الخصائص بعد؛ والحلقة تملؤها.

اختيار الخصائص حسب نوع قيمتها

يختار Pick حسب اسم المفتاح. للاختيار حسب نوع الخاصية، مثل «كل الحقول النصية»، اكتب mapped type مع مرشّح للمفاتيح:

type PickByValue<T, V> = {
  [P in keyof T as T[P] extends V ? P : never]: T[P];
};

interface Article {
  id: number;
  title: string;
  slug: string;
  views: number;
  published: boolean;
}

type TextFields = PickByValue<Article, string>;   // { title: string; slug: string }
type NumberFields = PickByValue<Article, number>; // { id: number; views: number }

const text: TextFields = { title: "Hello", slug: "hello" };
const nums: NumberFields = { id: 1, views: 120 };
console.log(text, nums); // { title: 'Hello', slug: 'hello' } { id: 1, views: 120 }

تحوّل جملة as كل مفتاح إلى نفسه عندما يطابق نوعه، وإلى never في غير ذلك، والمفاتيح never تُسقط. وهناك دقة واحدة: نوع الخاصية الاختيارية يتضمن undefined، لذا فالخاصية الاختيارية subtitle?: string لن تُحسب هنا من النوع string؛ اختبر مقابل string | undefined لتضمها.