المعاملات الاختيارية في TypeScript: القيم الافتراضية وrest

أضف ? بعد اسم المعامل لجعله اختياريًا. يمكن للمستدعين تركه، وداخل الدالة يتضمن نوعه undefined.

function greet(name: string, title?: string): string {
  // title is string | undefined here
  return title ? `Hello, ${title} ${name}` : `Hello, ${name}`;
}

console.log(greet("Lovelace"));          // Hello, Lovelace
console.log(greet("Lovelace", "Lady"));  // Hello, Lady Lovelace

تفحص TypeScript عدد الوسائط، لذلك دون ? كان الاستدعاء الأول سيكون خطأ ترجمة: Expected 2 arguments, but got 1. (TS2554).

المعاملات الاختيارية قد تكون undefined

لأن المستدعي يستطيع حذفه، يكون نوع المعامل الاختياري داخل الدالة T | undefined. وتحت strictNullChecks يجب أن تعالج حالة undefined قبل استخدامه كـ T.

function formatPrice(amount: number, currency?: string): string {
  // currency.toUpperCase() here would fail: 'currency' is possibly 'undefined'. (TS18048)
  const code = currency?.toUpperCase() ?? "USD";
  return `${amount.toFixed(2)} ${code}`;
}

console.log(formatPrice(9.5));        // 9.50 USD
console.log(formatPrice(12, "eur"));  // 12.00 EUR

الأداتان المعتادتان هنا هما optional chaining (?.) وnullish coalescing (??). وعندما تكون القيمة البديلة ثابتة، يكون المعامل الافتراضي أقصر.

القيم الافتراضية للمعاملات

تجعل القيمة الافتراضية المعامل اختياريًا للمستدعين وتعطيه نوعًا بلا undefined داخل الدالة. يُستنتج النوع من القيمة الافتراضية، فكثيرًا ما يكون التعليق غير ضروري.

function repeat(text: string, times = 2, separator: string = " "): string {
  // times: number, separator: string (never undefined here)
  return Array.from({ length: times }, () => text).join(separator);
}

console.log(repeat("ha"));              // ha ha
console.log(repeat("ha", 3, "-"));      // ha-ha-ha
console.log(repeat("ha", undefined, "")); // haha

يرى المستدعي التوقيع repeat(text: string, times?: number, separator?: string). تتبع القيم الافتراضية قاعدة JavaScript: تُطبَّق عندما يكون الوسيط undefined، سواء حُذف أو مُرر صراحة، ولا تُطبَّق عندما يكون null. ويمكن لتعبير القيمة الافتراضية استخدام المعاملات السابقة: function range(start: number, end = start + 10).

قواعد ترتيب المعاملات

المعامل ذو القيمة الافتراضية قبل معامل إلزامي قانوني لكنه مزعج. يصبح نوعه عند المستدعين number | undefined، ولا أحد يحب كتابة undefined كعنصر نائب. إذا احتجت إلى معامل أول مرن، فاستخدم كائن خيارات أو تحميل الدوال الزائد بدلًا من ذلك.

المحذوف مقابل undefined

يتشابه x?: number وx: number | undefined ولهما النوع نفسه داخل الدالة. ويختلفان عند المستدعي: الأول يمكن حذفه، والثاني يجب تمريره.

function a(x?: number) { return x; }
function b(x: number | undefined) { return x; }

console.log(a());          // undefined
console.log(b(undefined)); // undefined
// @ts-expect-error: Expected 1 arguments, but got 0.
b();

استخدم | undefined لوسيط إلزامي يُسمح بأن يكون بلا قيمة، حتى يضطر كل مستدعٍ إلى التفكير فيه. واستخدم ? عندما يكون تركه استدعاءً عاديًا. (تقول الرسالة فعلًا "1 arguments": هذه صياغة TypeScript.)

معاملات Rest

يجمع معامل rest، ...name: T[]، أي عدد من الوسائط في مصفوفة. يجب أن يكون المعامل الأخير.

function sum(...values: number[]): number {
  return values.reduce((total, v) => total + v, 0);
}

function tag(name: string, ...classes: string[]): string {
  return `<${name} class="${classes.join(" ")}">`;
}

console.log(sum());             // 0
console.log(sum(1, 2, 3));      // 6
const scores = [4, 8, 15];
console.log(sum(...scores));    // 27
console.log(tag("div", "card", "wide")); // <div class="card wide">

نشر مصفوفة في معاملات ثابتة أكثر صرامة. يقبل معامل rest نشر أي number[]، لكن الدالة المعلنة (a: number, b: number) لا تقبل إلا نشر tuple، لأن TypeScript يجب أن تعرف الطول:

function point(x: number, y: number) { return { x, y }; }

const list = [3, 4];            // number[]
point(...list);
// error TS2556: A spread argument must either have a tuple type or be passed to a rest parameter.

const pair = [3, 4] as const;   // readonly [3, 4]
point(...pair);                 // fine

يمكن أن يكون لمعامل rest أيضًا نوع tuple، يحدد نوع كل موضع: ...args: [name: string, age?: number].

كائنات الخيارات

عندما يكون لدالة أكثر من معاملين أو ثلاثة اختيارية، يفقد المستدعون تتبع المواضع. كائن خيارات مع قيم افتراضية يعطي وسائط مسماة لا يهم ترتيبها.

interface FetchOptions {
  retries?: number;
  timeoutMs?: number;
  verbose?: boolean;
}

function fetchData(url: string, { retries = 3, timeoutMs = 5000, verbose = false }: FetchOptions = {}): string {
  return `${url} retries=${retries} timeout=${timeoutMs} verbose=${verbose}`;
}

console.log(fetchData("/a"));
// /a retries=3 timeout=5000 verbose=false
console.log(fetchData("/b", { verbose: true }));
// /b retries=3 timeout=5000 verbose=true

يجعل = {} في النهاية الكائن كله اختياريًا. دونه يكون fetchData("/a") خطأ ترجمة (Expected 2 arguments, but got 1.، TS2554)، وفي JavaScript العادية كان الاستدعاء نفسه سيرمي TypeError وقت التشغيل، لأن التفكيك يحتاج إلى كائن يقرأ منه.

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

في نوع الدالة، تعني ? «قد لا يمرره مستدعي هذا الـ callback». ولا تعني «قد يتخطاه الـ callback»: يستطيع الـ callback دائمًا تجاهل المعاملات الأخيرة. لذلك لا تعلّم معاملات الـ callback كاختيارية لمجرد السماح للمعالجات بأخذ وسائط أقل.

// Too loose: every handler must now cope with index being undefined
type Visit = (item: string, index?: number) => void;

// Right: the caller always passes both; handlers may use only item
type VisitStrict = (item: string, index: number) => void;
const log: VisitStrict = (item) => console.log(item);