الدوال في TypeScript: أنواع المعاملات والقيمة المُعادة وvoid

الدالة في TypeScript دالة JavaScript مع أنواع على معاملاتها، وعلى قيمتها المُعادة اختياريًا. يحصل كل معامل على تعليق نوع، ويأتي نوع القيمة المُعادة بعد قائمة المعاملات، ويفحص المترجم كل استدعاء مقابل الاثنين.

function area(width: number, height: number): number {
  return width * height;
}

console.log(area(3, 4)); // 12

// @ts-expect-error: Argument of type 'string' is not assignable to parameter of type 'number'.
area("3", 4);

// @ts-expect-error: Expected 2 arguments, but got 1.
area(3);

الاستدعاءان الخاطئان كلاهما خطأ وقت الترجمة (TS2345 وTS2554). تخبر تعليقات // @ts-expect-error المترجم بأن خطأ متوقع في السطر التالي، فيعمل بقية الملف. احذف أحدها وشغّل من جديد لترى الرسالة الحقيقية.

أنواع المعاملات

يُكتب كل معامل name: Type. تحت strict، المفعّل افتراضيًا في TypeScript 7، يكون المعامل الذي بلا تعليق نوع ولا سياق يُستنتج منه خطأ: Parameter 'x' implicitly has an 'any' type. (TS7006). لذلك عمليًا يُحدد نوع كل معامل في الدالة المستقلة.

أي نوع يصلح نوعًا لمعامل: الأنواع البدائية، والمصفوفات، وأنواع الكائنات، وunion، والدوال الأخرى.

type User = { name: string; tags: string[] };

function describe(user: User, maxTags: number): string {
  const shown = user.tags.slice(0, maxTags).join(", ");
  return `${user.name} (${shown})`;
}

function formatId(id: string | number): string {
  return typeof id === "number" ? id.toFixed(0).padStart(5, "0") : id.toUpperCase();
}

console.log(describe({ name: "Ada", tags: ["math", "code", "tea"] }, 2)); // Ada (math, code)
console.log(formatId(42));      // 00042
console.log(formatId("ab-7"));  // AB-7

تفحص TypeScript عدد الوسائط أيضًا. تمرير عدد أكثر أو أقل مما تعلنه الدالة خطأ، على خلاف JavaScript العادية التي تملأ الناقص بـ undefined وتتجاهل الزائد. لجعل معامل اختياريًا أو إعطائه قيمة افتراضية، انظر المعاملات الاختيارية.

أنواع القيم المُعادة: كتابتها أو استنتاجها

يأتي نوع القيمة المُعادة بعد القوس الختامي: function f(): Type. وهو اختياري. دونه تستنتج TypeScript النوع من كل return في الجسم.

// Inferred: (n: number) => "even" | "odd"
function parity(n: number) {
  return n % 2 === 0 ? "even" : "odd";
}

// Annotated: the contract is written down
function average(values: number[]): number {
  if (values.length === 0) return 0;
  const sum = values.reduce((acc, v) => acc + v, 0);
  return sum / values.length;
}

const p = parity(7);
console.log(p, average([2, 4, 9])); // odd 5

يستحق التعليق مكانه عندما تكون الدالة مصدَّرة، أو عندما تكون لها عدة مسارات إعادة، أو عندما تكون تعاودية. عندها يظهر الخطأ داخل الدالة، عند return الخاطئة، بدل أن يظهر عند مستدعٍ. حالة نموذجية هي فرع ينسى الإعادة:

// This does not compile: one path falls off the end of the function.
function grade(score: number): string {
  if (score >= 90) return "A";
  if (score >= 80) return "B";
}

console.log(grade(85));

يبلّغ المترجم index.ts(2,32): error TS2366: Function lacks ending return statement and return type does not include 'undefined'. أضف return "C"; أخيرة فيعمل. دون التعليق : string كانت الدالة ستُترجم بالنوع المستنتج "A" | "B" | undefined، وستنتقل المشكلة إلى من يستخدم الناتج.

void: الدوال التي لا تعيد شيئًا

الدالة التي تكتفي بفعل شيء (تسجيل أو كتابة أو تعديل) نوع قيمتها المُعادة void. وهو ما تستنتجه TypeScript عندما لا توجد return بقيمة، ويمكنك كتابته صراحة.

function logLine(label: string, value: number): void {
  console.log(`${label.padEnd(8)}${value}`);
}

logLine("apples", 3);
logLine("pears", 12);

// A callback typed as returning void may return a value; it is ignored.
const lengths: number[] = [];
const push: (s: string) => void = (s) => lengths.push(s.length);
["a", "bcd"].forEach(push);
console.log(lengths); // [ 1, 3 ]

هذه القواعد المتعلقة بـ void تفاجئ الناس:

الصف الثاني مقصود. ولهذا يُترجم arr.forEach(x => list.push(x)) رغم أن push تعيد رقمًا. تعني void في نوع دالة «مهما أعادت، لا أحد يقرؤه». وللدالة التي لا تعود أبدًا (ترمي خطأ دائمًا أو تدور إلى الأبد)، يكون نوع القيمة المُعادة never.

الدوال السهمية وتعبيرات الدوال

تأخذ الدوال السهمية وتعبيرات الدوال التعليقات نفسها. يأتي نوع القيمة المُعادة بعد قائمة المعاملات، قبل =>.

const double = (n: number): number => n * 2;

const toUpper = function (s: string): string {
  return s.toUpperCase();
};

// Returning an object literal from an arrow needs parentheses.
const point = (x: number, y: number) => ({ x, y });

console.log(double(21), toUpper("ok")); // 42 OK
console.log(point(1, 2));               // { x: 1, y: 2 }

دون الأقواس يكون (x, y) => { x, y } كتلة بلا return، فتعيد الدالة undefined. قواعد وقت التشغيل للدوال السهمية (لا this خاص بها، ولا arguments) هي نفسها في JavaScript؛ انظر الدوال السهمية في JavaScript.

عندما تُكتب دالة مضمّنة كوسيط، لا تحدد عادة أنواع معاملاتها إطلاقًا. تعرف TypeScript ما تستقبله الدالة الممررة من الدالة التي تُمرر إليها (الأنواع السياقية): في [1, 2].map(n => n * 2) يكون n من نوع number أصلًا. أما كتابة نوع دالة كقيمة، (n: number) => string، فمشروحة في أنواع الدوال.

إعادة عدة قيم

تعيد الدالة قيمة واحدة، فأعد كائنًا أو tuple وفككه.

function minMax(values: number[]): { min: number; max: number } {
  return { min: Math.min(...values), max: Math.max(...values) };
}

function splitName(full: string): [first: string, last: string] {
  const i = full.indexOf(" ");
  return [full.slice(0, i), full.slice(i + 1)];
}

const { min, max } = minMax([7, 2, 9]);
const [first, last] = splitName("Grace Hopper");
console.log(min, max, first, last); // 2 9 Grace Hopper

نوع الـ tuple المُعاد يحتاج إلى التعليق. دونه يُستنتج [a, b] كـ string[]: يظل التفكيك يعمل، لكن النوع لم يعد يقول إن هناك عنصرين بالضبط.

الدوال غير المتزامنة

تعيد دالة async دائمًا Promise. اكتب نوع القيمة المُعادة كـ Promise<T>، حيث T ما تعيده الدالة في داخلها.

async function loadScore(id: number): Promise<number> {
  await new Promise((resolve) => setTimeout(resolve, 10));
  return id * 10;
}

async function main(): Promise<void> {
  const score = await loadScore(4); // score: number
  console.log("score", score);
}

main();

كتابة async function f(): number خطأ: The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'? (TS1064).

معامل this

تحدد JavaScript قيمة this وقت الاستدعاء. وتتيح لك TypeScript إعلان ما يجب أن يكون عليه this بمعامل أول وهمي اسمه this. يُحذف من كود JavaScript المترجم ولا يمرره المستدعون.

interface Counter {
  count: number;
}

function increment(this: Counter, by: number): void {
  this.count += by;
}

const c = { count: 0, increment };
c.increment(2); // fine: this is c

increment(2);
// error TS2684: The 'this' context of type 'void' is not assignable to method's 'this' of type 'Counter'.

دون معامل this، يكون this داخل دالة مستقلة any ضمنيًا، ويبلّغ الوضع الصارم عن 'this' implicitly has type 'any' because it does not have a type annotation. (TS2683). في دوال الأصناف يكون نوع this هو نسخة الصنف أصلًا، لذلك يفيد المعامل غالبًا مع الدوال المستقلة المربوطة بكائنات ومع callbacks التي تستدعيها المكتبات بـ this محدد.