وثائق TypeScript قابلة للتشغيل: Omit

Q: ماذا يفعل Omit في TypeScript؟

يبني Omit نوع كائن جديدًا فيه كل خصائص T عدا تلك التي مفاتيحها في K. فـ Omit هو User دون password. إنه يغيّر النوع فقط؛ ولا يحذف شيئًا من الكائن وقت التشغيل.

Q: كيف أحذف عدة خصائص في TypeScript؟

مرّر union من المفاتيح كوسيط ثانٍ: Omit . يُحذف كل مفتاح في union.

Q: ما الفرق بين Omit وExclude؟

يحذف Omit خصائص من نوع كائن: Omit هو { b: 2 }. ويحذف Exclude أعضاء من نوع union: Exclude هو "b". وOmit منفّذ باستخدام Exclude: Pick >.

Q: لماذا لا يعطي Omit خطأ لمفتاح غير موجود؟

معامل المفاتيح فيه مقيّد بـ keyof any (أي string أو number أو symbol)، لا بـ keyof T، لذا فخطأ إملائي مثل Omit يُترجم ولا يحذف شيئًا. عرّف type StrictOmit = Omit لتحصل على خطأ عند المفاتيح المجهولة.

Q: كيف أحذف خاصية من كائن وقت التشغيل في TypeScript؟

استخدم التفكيك مع عنصر rest: const { password, ...rest } = user;. تعطي TypeScript المتغير rest نوع الكائن دون password، وهو الشكل نفسه لـ Omit ، والخاصية تختفي فعلًا من الكائن الجديد.

Omit<T, K> نوع أداة مدمج ينشئ نوع كائن فيه كل خصائص T عدا المفاتيح المذكورة في K. الاستخدام الكلاسيكي: نوع User فيه password، ونسخة عامة ليس فيها.

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

type PublicUser = Omit<User, "password">;
// { id: number; name: string; email: string }

function toPublic(user: User): PublicUser {
  const { password, ...rest } = user; // really remove it from the object
  return rest;
}

const ada: User = { id: 1, name: "Ada", email: "ada@example.com", password: "s3cret" };
console.log(toPublic(ada)); // { id: 1, name: 'Ada', email: 'ada@example.com' }

يبقى PublicUser متزامنًا مع User: أضف حقلًا إلى User فيظهر في PublicUser أيضًا، بينما يبقى password خارجه. يعمل Omit على الأنواع فقط؛ أما التفكيك في toPublic فهو ما يحذف الخاصية من الكائن الفعلي.

حذف عدة مفاتيح

الوسيط الثاني union، فاذكر ما تحتاج من المفاتيح مفصولة بـ |:

interface Post {
  id: number;
  title: string;
  body: string;
  createdAt: string;
  updatedAt: string;
}

// What a client sends to create a post: the server fills in the rest
type NewPost = Omit<Post, "id" | "createdAt" | "updatedAt">;

function createPost(input: NewPost, id: number): Post {
  const now = "2024-03-15T10:30:00.000Z";
  return { ...input, id, createdAt: now, updatedAt: now };
}

const post = createPost({ title: "Hello", body: "First post" }, 7);
console.log(post.id, post.title, post.createdAt); // 7 Hello 2024-03-15T10:30:00.000Z
// createPost({ title: "x", body: "y", id: 1 }, 7) would be error TS2353:
// Object literal may only specify known properties, and 'id' does not exist in type 'NewPost'.

«النوع دون الحقول التي يولّدها الخادم» هو أشيع استخدام لـ Omit في الكود الحقيقي: نوع نموذج واحد، ويشتق Omit منه شكل المُدخلات لنماذج الإنشاء وطلبات API.

كيف يُعرَّف Omit

يُبنى Omit من نوعي أداة آخرين:

type Omit<T, K extends keyof any> = Pick<T, Exclude<keyof T, K>>;

اقرأه من الداخل: keyof T هو union كل المفاتيح، وExclude<keyof T, K> يحذف المفاتيح غير المرغوبة من هذا union، وPick يُبقي المفاتيح المتبقية. لذا فإن Omit<User, "password"> هو Pick<User, "id" | "name" | "email">. ولأن Pick يمر على مفاتيح T، تبقى المُعدِّلات readonly و? على الخصائص المتبقية.

لاحظ القيد: K extends keyof any وليس K extends keyof T. هذه التفصيلة موضوع القسم التالي.

Omit لا يتحقق من وجود المفتاح

keyof any هو string | number | symbol، لذا يقبل Omit أي مفتاح على الإطلاق، بما فيه مفتاح لا يملكه T. فالخطأ الإملائي يُترجم ولا يحذف شيئًا:

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

type PublicUser = Omit<User, "pasword">; // typo: nothing is omitted

function toPublic(user: User): PublicUser {
  return user; // compiles, because PublicUser still has password
}

console.log(JSON.stringify(toPublic({ id: 1, name: "Ada", password: "s3cret" })));
// {"id":1,"name":"Ada","password":"s3cret"}

لا خطأ في أي مكان، وتخرج كلمة المرور في JSON. اختير القيد الفضفاض عن قصد عندما أُضيف Omit في TypeScript 3.5. أسباب الفريق: في الكود العام كثيرًا ما لا تأتي المفاتيح المحذوفة من T (فدالة تدمج كائنين قد تعطي وسيط rest فيها النوع Omit<T1, keyof T2>)، وExclude لا يقيّد معامله الثاني أيضًا، ونسخة مقيّدة كانت ستكسر كثيرًا من أنواع Omit المكتوبة يدويًا الموجودة في المشاريع. أما في الكود اليومي فنسخة أكثر صرامة تلتقط الخطأ الإملائي:

// This does not compile: StrictOmit only accepts real keys of User
type StrictOmit<T, K extends keyof T> = Omit<T, K>;

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

type PublicUser = StrictOmit<User, "pasword">;
const u: PublicUser = { id: 1, name: "Ada" };
console.log(u);

index.ts(10,36): error TS2344: Type '"pasword"' does not satisfy the constraint 'keyof User'.
index.ts(11,7): error TS2741: Property 'password' is missing in type '{ id: number; name: string; }' but required in type 'PublicUser'.

الخطأ الأول هو المهم: يُفحص المفتاح مقابل keyof User. والثاني ناتج عنه، لأنه لم يُحذف شيء وما زال PublicUser يشترط password. صحّح الإملاء إلى "password" فيُترجم الكود. تعرّفه مشاريع كثيرة مرة واحدة في ملف أنواع مشترك وتستخدمه بدلًا من Omit.

استبدال نوع خاصية

لا يستطيع interface أن يرث من آخر ويغيّر خاصية إلى نوع غير متوافق: interface ApiUser extends User { id: string } يفشل بالخطأ error TS2430: Interface 'ApiUser' incorrectly extends interface 'User'. احذف الخاصية أولًا، ثم صرّح بها من جديد:

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

// The JSON version: id is a string and dates are ISO strings
interface ApiUser extends Omit<User, "id" | "createdAt"> {
  id: string;
  createdAt: string;
}

function toApi(user: User): ApiUser {
  return { ...user, id: String(user.id), createdAt: user.createdAt.toISOString() };
}

const u: User = { id: 7, name: "Ada", createdAt: new Date("2024-03-15T10:30:00Z") };
console.log(toApi(u)); // { id: '7', name: 'Ada', createdAt: '2024-03-15T10:30:00.000Z' }

ومع type alias يكون الأمر نفسه intersection: type ApiUser = Omit<User, "id"> & { id: string }. ومن دون Omit كان الـ intersection User & { id: string } سيعطي id النوع number & string، وهو never.

Omit على أنواع union

Omit ليس توزيعيًا. على union يبدأ من keyof للـ union كله، وهو لا يحتوي إلا المفاتيح المشتركة بين كل الأعضاء، فتختفي الخصائص الخاصة بكل عضو:

// This does not compile: Omit collapsed the union into its shared keys
type Shape =
  | { kind: "circle"; radius: number; id: string }
  | { kind: "square"; size: number; id: string };

type NewShape = Omit<Shape, "id">;

const c: NewShape = { kind: "circle", radius: 2 };
console.log(c);

index.ts(8,39): error TS2353: Object literal may only specify known properties, and 'radius' does not exist in type 'NewShape'.

أصبح NewShape هو { kind: "circle" | "square" }. لتحذف من كل عضو على حدة، طبّق Omit داخل نوع شرطي توزيعي:

type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;

type Shape =
  | { kind: "circle"; radius: number; id: string }
  | { kind: "square"; size: number; id: string };

type NewShape = DistributiveOmit<Shape, "id">;
// Omit<circle, "id"> | Omit<square, "id">

function area(s: NewShape): number {
  return s.kind === "circle" ? Math.PI * s.radius ** 2 : s.size ** 2; // narrowing works
}

console.log(area({ kind: "square", size: 3 }));            // 9
console.log(area({ kind: "circle", radius: 1 }).toFixed(2)); // 3.14

الشرط T extends unknown ? ... : never صحيح دائمًا؛ وهو موجود فقط ليجعل النوع الشرطي يتوزع على union. تشرح صفحة الأنواع الشرطية سبب نجاح ذلك. استخدم DistributiveOmit كلما كان النوع الذي تحذف منه discriminated union.

حذف خاصية متداخلة

لا ينظر Omit إلا إلى مفاتيح المستوى الأعلى، لذا فإن Omit<Settings, "editor.wordWrap"> لا يحذف شيئًا (ولا يعترض، كما رأينا). لإسقاط خاصية في مستوى أدنى، احذف الأب ثم أضفه من جديد مع Omit خاص به:

interface Settings {
  theme: string;
  editor: { fontSize: number; tabSize: number; wordWrap: boolean };
}

type SettingsDraft = Omit<Settings, "editor"> & {
  editor: Omit<Settings["editor"], "wordWrap">;
};

const draft: SettingsDraft = { theme: "dark", editor: { fontSize: 14, tabSize: 2 } };
console.log(draft.editor); // { fontSize: 14, tabSize: 2 }
// Adding wordWrap: true to editor would be error TS2353

Settings["editor"] نوع وصول مفهرس (indexed access type): يسمّي نوع الكائن المتداخل لكي يعمل عليه Omit.

حذف الخصائص وقت التشغيل

يغيّر Omit النوع فقط. لإنتاج كائن دون تلك الخصائص، أخرجها بالتفكيك، أو اكتب دالة مساعدة generic صغيرة نوع قيمتها المُعادة Omit:

function omit<T extends object, K extends keyof T>(obj: T, ...keys: K[]): Omit<T, K> {
  const copy = { ...obj };
  for (const key of keys) delete copy[key];
  return copy;
}

const order = { id: 42, total: 99.5, cardNumber: "4111 1111", cvv: "123" };

const safe = omit(order, "cardNumber", "cvv"); // { id: number; total: number }
console.log(safe);        // { id: 42, total: 99.5 }
console.log(order.cvv);   // 123 (the original is untouched)
// safe.cvv would be error TS2339: Property 'cvv' does not exist on type ...

تقيّد الدالة المساعدة K بـ keyof T، فالمفتاح المكتوب خطأً يكون خطأ ترجمة في موضع الاستدعاء. والنسخة سطحية: الكائنات المتداخلة مشتركة مع الأصل.

Omit أم Pick أم Exclude

	يعمل على	يُبقي	مثال	النتيجة
`Omit<T, K>`	أنواع الكائنات	كل خاصية عدا `K`	`Omit<User, "password">`	`{ id; name; email }`
`Pick<T, K>`	أنواع الكائنات	الخصائص التي في `K` فقط	`Pick<User, "id" \| "name">`	`{ id; name }`
`Exclude<U, M>`	أنواع union	أعضاء union غير القابلة للإسناد إلى `M`	`Exclude<"a" \| "b" \| "c", "a">`	`"b" \| "c"`

اختر بين Omit وPick بحسب ما يجب أن يحدث عندما يكبر النوع المصدر. يضم Omit الخصائص الجديدة تلقائيًا، وهذا يناسب «كل شيء عدا السر». أما Pick فلا يضمها أبدًا، وهذا يناسب «هذه الحقول بالضبط» وهو أكثر أمانًا لكل ما يغادر خادمك. يفحص Pick مفاتيحه مقابل keyof T؛ أما Omit فلا.

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

ماذا يفعل Omit في TypeScript؟

يبني Omit<T, K> نوع كائن جديدًا فيه كل خصائص T عدا تلك التي مفاتيحها في K. فـ Omit<User, "password"> هو User دون password. إنه يغيّر النوع فقط؛ ولا يحذف شيئًا من الكائن وقت التشغيل.

كيف أحذف عدة خصائص في TypeScript؟

مرّر union من المفاتيح كوسيط ثانٍ: Omit<User, "password" | "createdAt" | "updatedAt">. يُحذف كل مفتاح في union.

ما الفرق بين Omit وExclude؟

يحذف Omit خصائص من نوع كائن: Omit<{ a: 1; b: 2 }, "a"> هو { b: 2 }. ويحذف Exclude أعضاء من نوع union: Exclude<"a" | "b", "a"> هو "b". وOmit منفّذ باستخدام Exclude: Pick<T, Exclude<keyof T, K>>.

لماذا لا يعطي Omit خطأ لمفتاح غير موجود؟

معامل المفاتيح فيه مقيّد بـ keyof any (أي string أو number أو symbol)، لا بـ keyof T، لذا فخطأ إملائي مثل Omit<User, "pasword"> يُترجم ولا يحذف شيئًا. عرّف type StrictOmit<T, K extends keyof T> = Omit<T, K> لتحصل على خطأ عند المفاتيح المجهولة.

كيف أحذف خاصية من كائن وقت التشغيل في TypeScript؟

استخدم التفكيك مع عنصر rest: const { password, ...rest } = user;. تعطي TypeScript المتغير rest نوع الكائن دون password، وهو الشكل نفسه لـ Omit<User, "password">، والخاصية تختفي فعلًا من الكائن الجديد.

مفاهيم ذات صلة