أنواع Union في TypeScript: العامل | مع أمثلة

يسرد نوع union البدائل بـ |: قيمة من نوع string | number إما نص أو رقم. الـ unions هي طريقة TypeScript في وصف القيم التي يمكن أن تأخذ أكثر من شكل بشكل مشروع، ويجبرك المترجم على فحص الشكل الذي لديك قبل استخدام أي شيء خاص به.

function formatId(id: string | number): string {
  if (typeof id === "number") {
    return id.toString().padStart(6, "0"); // id is number here
  }
  return id.toUpperCase();                 // id is string here
}

console.log(formatId(42));     // 000042
console.log(formatId("ab-7")); // AB-7

داخل كل فرع من فحص typeof يكون لـ id نوع واحد. تُسمى هذه الخطوة التضييق (narrowing)، وهي ما يجعل الـ unions عملية.

الأعضاء المشتركة فقط مسموحة

قبل التضييق لا تستطيع استخدام إلا ما يدعمه كل عضو في الـ union. toString() موجودة في النصوص والأرقام، فلا مشكلة فيها؛ أما toUpperCase() فموجودة في النصوص فقط:

// This does not compile: numbers have no toUpperCase()
function shout(value: string | number) {
  return value.toUpperCase();
}

console.log(shout("hi"));

index.ts(3,16): error TS2339: Property 'toUpperCase' does not exist on type 'string | number'.
  Property 'toUpperCase' does not exist on type 'number'.

يسمّي السطر الثاني العضو الذي تنقصه الخاصية. وتنطبق القاعدة نفسها في الاتجاه الآخر: لا يمكن تمرير قيمة string | number إلى معامل نوعه string (TS2345)، لأنها قد تكون رقمًا. يقبل الـ union قيمًا أكثر، وفي المقابل يتيح لك فعل أقل بها حتى تفحص.

تضييق union

يستخدم التضييق فحوص JavaScript العادية. تتبع TypeScript مسار التحكم وتحذف الأعضاء كلما استُبعدت، فبعد آخر فحص لا يبقى إلا عضو واحد:

type Input = string | number | string[] | Date | null;

function normalize(input: Input): string {
  if (input === null) return "(empty)";
  if (typeof input === "string") return input.trim();
  if (typeof input === "number") return input.toFixed(1);
  if (Array.isArray(input)) return input.join(", ");
  return input.toISOString().slice(0, 10); // only Date is left
}

const samples: Input[] = ["  hi  ", 3, ["a", "b"], new Date("2024-03-15T10:30:00Z"), null];
for (const s of samples) console.log(normalize(s));
// hi
// 3.0
// a, b
// 2024-03-15
// (empty)

القائمة الكاملة لصيغ التضييق موجودة في صفحة تضييق الأنواع.

Union من الأنواع الحرفية

الـ union من القيم الحرفية مجموعة مغلقة من القيم المسموحة. وهو أكثر أنواع union شيوعًا في الكود الحقيقي:

type Status = "idle" | "loading" | "success" | "error";
type Dice = 1 | 2 | 3 | 4 | 5 | 6;
type Toggle = "on" | "off" | boolean; // boolean is itself true | false

let current: Status = "idle";
current = "loading";   // fine
current = "finished";  // error TS2322: Type '"finished"' is not assignable to type 'Status'.

المقارنة مع قيمة حرفية تضيّق: بعد if (current === "error") يعرف فرع else أن current واحدة من القيم الثلاث الأخرى. تحل الـ unions الحرفية محل enums في قواعد كود كثيرة؛ انظر الأنواع الحرفية لـ as const وطريقة اشتقاق union كهذا من مصفوفة.

Union من أنواع الكائنات

عندما تكون الأعضاء أنواع كائنات، تتاح الخصائص التي تشترك فيها كلها مباشرة. أما الباقي فافحص وجود الخاصية بـ in:

type Cat = { name: string; meow(): string };
type Fish = { name: string; swim(): string };

function act(pet: Cat | Fish): string {
  const intro = `${pet.name}: `; // name exists on both, so it is allowed
  if ("meow" in pet) {
    return intro + pet.meow();   // pet is Cat here
  }
  return intro + pet.swim();     // pet is Fish here
}

const tom: Cat = { name: "Tom", meow: () => "meow" };
const nemo: Fish = { name: "Nemo", swim: () => "swims away" };

console.log(act(tom));  // Tom: meow
console.log(act(nemo)); // Nemo: swims away

لـ unions من عدة أشكال كائنات، النمط الأنظف هو خاصية حرفية مشتركة مثل kind: "cat" / kind: "fish". فحص تلك الخاصية الواحدة يضيّق الكائن كله، ويمكن التحقق من شمولية switch عليها. هذا النمط هو discriminated union.

المصفوفات وأنواع union

مكان الأقواس يغيّر المعنى كليًا:

const mixed: (string | number)[] = [1, "two", 3]; // each element may be either
const eitherOr: string[] | number[] = ["a", "b"]; // all strings OR all numbers

// @ts-expect-error: Type '(string | number)[]' is not assignable to type 'string[] | number[]'.
const bad: string[] | number[] = ["a", 1];

const precedence: string | number[] = "not an array"; // | binds looser than []

console.log(mixed, eitherOr, precedence);
// [ 1, 'two', 3 ] [ 'a', 'b' ] not an array

const total = mixed.reduce<number>((sum, x) => sum + (typeof x === "number" ? x : 0), 0);
console.log(total); // 4

عند التكرار على (string | number)[] يكون كل عنصر هو الـ union ويحتاج إلى تضييق، كما في دالة reduce أعلاه. وتعمل دوال مثل map وfilter أيضًا على string[] | number[]، وتستقبل الدالة الممررة string | number.

Union مع null و undefined

أكثر أنواع union شيوعًا على الإطلاق هو «قيمة أو لا شيء»: string | null وUser | undefined. وهو ما تعيده Array.prototype.find وMap.prototype.get، والخاصية الاختيارية name?: string تُقرأ كـ string | undefined. ولمعالجتها بـ ?. و?? وفحوص null صفحة خاصة: null و undefined.

لحذف أعضاء من union موجود على مستوى الأنواع، استخدم الأدوات المدمجة: Exclude<"a" | "b" | "c", "a"> هو "b" | "c"، وNonNullable<string | null> هو string.