في صفحة الدفع في Cartwheel نموذج للعنوان. نوع العنوان بسيط:
\ntype Address = { line1: string; city: string; country: string; postcode?: string };لكن النموذج يحتاج إلى أكثر من العنوان. يحتاج لكل حقل إلى قيمته الحالية، وخطأ التحقّق، وما إذا كان المستخدم قد لمسه. ويحتاج الـ endpoint الخاص بـ PATCH إلى نسخة كل حقولها اختيارية. وتحتاج شاشة المراجعة إلى نسخة مجمّدة. يمكنك كتابة ثلاثة أنواع أخرى يدويًا، كلٌّ منها يكرّر أسماء الحقول الأربعة، وتحديثها كلها كلما تغيّر Address. أو يمكنك كتابة كلٍّ منها مرة واحدة، كتحويل. هذا هو الـ mapped type (النوع المحوَّل): حلقة تكرار على المفاتيح، على مستوى الأنواع.
type FieldState<T> = {\n [K in keyof T]: { value: T[K]; error: string | null; touched: boolean };\n};\n\ntype AddressForm = FieldState<Address>;\n// {\n// line1: { value: string; error: string | null; touched: boolean };\n// city: { value: string; … };\n// country: { value: string; … };\n// postcode?: { value: string | undefined; … };\n// }اقرأ [K in keyof T] هكذا: “لكل مفتاح K من T”. يُقيَّم الطرف الأيمن مرة لكل مفتاح، مع ربط K بذلك المفتاح، فيكون T[K] نوع تلك الخاصية. أضف phone إلى Address فيكتسب AddressForm مدخلًا لـ phone، دون أي تعديل.
لاحظ أن postcode بقيت اختيارية. حين يمرّ الـ mapped type على keyof T مباشرة، يعامله TypeScript على أنه تماثليّ الشكل (homomorphic): ينسخ معدِّلَي ? وreadonly لكل خاصية من T. وهذا ما تريده عادة، وهو سبب احتفاظ الـ utility types المدمجة بالاختيارية.
لست مضطرًا إلى المرور على keyof. أي union من المفاتيح يعمل، وهذا كل ما في Record:
type MyRecord<K extends PropertyKey, V> = { [P in K]: V };\n\ntype CountsByStatus = MyRecord<'processing' | 'shipped' | 'delivered', number>;ضع ? أو readonly أمام الخاصية لإضافتها، وابدأ بـ - لإزالتها. بهذا تصبح معظم الـ utility types في الـ lib سطرًا واحدًا لكلٍّ منها:
type MyPartial<T> = { [K in keyof T]?: T[K] };\ntype MyReadonly<T> = { readonly [K in keyof T]: T[K] };\ntype MyRequired<T> = { [K in keyof T]-?: T[K] };\ntype Mutable<T> = { -readonly [K in keyof T]: T[K] };\ntype MyPick<T, K extends keyof T> = { [P in K]: T[P] };MyPartial<Address> هو نوع جسم طلب PATCH. وMyReadonly<Address> هو النسخة المجمّدة لشاشة المراجعة. و-? تفعل شيئًا إضافيًا قد لا تتوقّعه: تُزيل أيضًا الـ undefined الذي تحمله الخاصية الاختيارية ضمنيًا، فيكون MyRequired<Address>['postcode'] هو string، لا string | undefined.
MyPick يستحق نظرة ثانية. إنه يمرّ على K لا على keyof T، لكن لأن K مقيَّد بـ keyof T، يظل TypeScript يعامله كتماثليّ الشكل ويحتفظ بمعدِّلات الخصائص المختارة.
منذ TypeScript 4.1، يستطيع الـ mapped type إعادة تسمية كل مفتاح بجملة as. يمكن أن يكون الاسم الجديد أي تعبير نوعي يتضمّن K، وعادةً ما يكون template literal:
type Setters<T> = {\n [K in keyof T as `set${Capitalize<K & string>}`]: (value: T[K]) => void;\n};\n\ntype AddressSetters = Setters<Address>;\n// { setLine1: (value: string) => void; setCity: …; setCountry: …; setPostcode?: … }K & string ضرورية لأن keyof T قد يتضمّن مفاتيح number وsymbol، وCapitalize لا تعمل إلا على النصوص. سترى الـ template literal types كما ينبغي في الـ Template Literal Types.
ولجملة as قوة ثانية: المفتاح المحوَّل إلى never يُحذف. وهكذا بالضبط يُعرَّف Omit:
type MyOmit<T, K extends PropertyKey> = { [P in keyof T as Exclude<P, K>]: T[P] };\n\ntype NewAddress = MyOmit<Address, 'postcode'>; // { line1; city; country }Exclude<P, K> تعطي never حين يكون P أحد المفاتيح المحذوفة، وP في غير ذلك. في الدرس القادم سترى كيف تعمل Exclude، وكيف تصفّي المفاتيح حسب نوع قيمتها لا حسب اسمها.
أنواع مثل FieldState تؤتي ثمارها في الدوال التي تستخدمها. إليك دالة تحديث النموذج، مكتوبة مرة واحدة لأي نموذج، لا للعناوين فقط:
function setField<T, K extends keyof T>(form: FieldState<T>, key: K, value: T[K]): FieldState<T> {\n return { ...form, [key]: { ...form[key], value, touched: true } };\n}\n\nsetField(addressForm, 'city', 'Dubai'); // ok\nsetField(addressForm, 'city', 42); // Error: Argument of type 'number' is not assignable to parameter of type 'string'.\nsetField(addressForm, 'cty', 'Dubai'); // Error: Argument of type '\"cty\"' is not assignable to parameter of type 'keyof Address'.هذا نمط pluck من القسم 2 مدموجًا مع mapped type. يُستنتج K من المفتاح الذي تمرّره، وتفحص T[K] القيمة مقابل نوع ذلك الحقل، ويضمن الـ mapped type أن للنموذج مدخلًا لكل حقل. وحين يُضاف حقل deliveryNotes إلى Address، يقبله نوع النموذج والـ setters وهذه الدالة فورًا، ويُعلَّم كل مكان يبني نموذجًا كاملًا إلى أن يتعامل مع الحقل الجديد.
في التمرين ستعيد بناء أربعة utility types وتبني أنواع نموذج العنوان منها. والدرس القادم يضيف القطعة الناقصة، الشروط، كي تستطيع تحويلاتك اتخاذ القرارات.
\n","toc":[{"id":"sec-1","text":"الحلقة","level":2},{"id":"sec-2","text":"إضافة المعدِّلات وإزالتها","level":2},{"id":"sec-3","text":"إعادة تسمية المفاتيح بـ as","level":2},{"id":"sec-4","text":"وضعها موضع التطبيق","level":2}],"takeaways":["الـ mapped type بالشكل{ [K in Keys]: … } يمرّ على union من المفاتيح ويبني خاصية واحدة لكل مفتاح.","المرور على keyof T تماثليّ الشكل (homomorphic)، فتُنسخ معدِّلات الاختيارية وreadonly من T ما لم تُضفها أو تُزلها أنت.","+? و-? و+readonly و-readonly تضيف المعدِّلات أو تنزعها؛ وRequired<T> ليس إلا { [K in keyof T]-?: T[K] }.","جملة as تعيد تسمية كل مفتاح، وتحويل مفتاح إلى never يحذفه، وهكذا يعمل Omit.","الـ mapped types المدمجة سطحية؛ الكائنات المتداخلة تحتفظ بمعدِّلاتها الأصلية."],"further":[{"title":"Mapped Types","url":"https://www.typescriptlang.org/docs/handbook/2/mapped-types.html"},{"title":"Utility Types","url":"https://www.typescriptlang.org/docs/handbook/utility-types.html"}],"quiz":[{"q":"ما هو Draft؟
type Address = { readonly line1: string; city: string; postcode?: string };\ntype Draft = { -readonly [K in keyof Address]-?: Address[K] };{ line1: string; city: string; postcode: string }","why":"صحيح. -readonly تنزع readonly عن line1، و-? تجعل postcode إلزامية، ويُزال أيضًا الـ undefined الذي جاء مع ?."},{"text":"{ readonly line1: string; city: string; postcode?: string }","why":"هذا ما ستحصل عليه دون معدِّلات -؛ فالمرور التماثلي ينسخها افتراضيًا."},{"text":"{ line1: string; city: string; postcode: string | undefined }","why":"-? تُزيل أيضًا الـ undefined الذي أضافه معدِّل الاختيارية، فيكون postcode من نوع string عادي."},{"text":"خطأ، لأن -? غير مسموحة إلا في Required.","why":"Required مجرّد mapped type عادي في الـ lib؛ والمعدِّل -? يعمل في أي mapped type."}],"answer":0},{"q":"أيّ تعريف يعيد بناء Omit<T, K>؟
{ [P in keyof T]: P extends K ? never : T[P] }","why":"هذا يُبقي كل المفاتيح ويجعل نوع المحذوفة منها never، فتبقى خصائص إلزامية لا يمكن لشيء أن يحقّقها."},{"text":"{ [P in K]: T[P] }","why":"هذا لا يُبقي إلا المفاتيح المدرَجة، وهذا هو Pick، بل إنه لا يمرّ في الترجمة دون K extends keyof T."},{"text":"{ [P in keyof T as Exclude<P, K>]: T[P] }","why":"صحيح. جملة as تحوّل المفاتيح المحذوفة إلى never، والمفتاح المحوَّل إلى never يُحذف من النتيجة."}],"answer":2},{"q":"type Setters<T> = { [K in keyof T as set${Capitalize]: (v: T[K]) => void } لا يمرّ في الترجمة. لماذا؟
as.","why":"إنها مسموحة؛ إعادة تسمية المفاتيح بالـ template literals هي الاستخدام الرئيسي لجمل as."},{"text":"keyof T قد يتضمّن مفاتيح number وsymbol، وCapitalize لا تقبل إلا النصوص، فاكتب Capitalize<K & string>.","why":"صحيح. التقاطع مع string لا يُبقي إلا المفاتيح النصية، التي تستطيع Capitalize التعامل معها."},{"text":"T[K] غير مسموحة بعد إعادة تسمية المفتاح.","why":"داخل الـ mapped type، يبقى K هو المفتاح الأصلي، فتعمل T[K] كالمعتاد."}],"answer":1},{"q":"طُبّق Readonly<Order> على type Order = { id: number; lines: { sku: string }[] }. أيّ إسناد ما زال مسموحًا؟
order.id = 1043","why":"id خاصية في المستوى الأعلى، وReadonly تجعل كل خاصية في المستوى الأعلى للقراءة فقط."},{"text":"order.lines = []","why":"lines نفسها خاصية في المستوى الأعلى، فإعادة الإسناد إليها مرفوضة."},{"text":"order.lines[0].sku = 'TENT-3P'","why":"صحيح. Readonly سطحية؛ المصفوفة وكائناتها تحتفظ بأنواعها الأصلية القابلة للتعديل."}],"answer":2}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"type Address = { line1: string; city: string; country: string; postcode?: string };\n\n// Re-implement these with mapped types (do not use the built-in utility types).\ntype MyPartialباستخدام الـ mapped types وحدها (بلا Partial أو Required أو Pick أو Omit أو Record المدمجة)، نفّذ:
MyPartial<T> وMyRequired<T> وMyPick<T, K> وMyOmit<T, K>، بسلوك يطابق المدمجة.FieldState<T>: لكل خاصية، { value: T[K]; error: string | null; touched: boolean }.Setters<T>: لكل خاصية name، خاصية setName هي دالة تأخذ نوع تلك الخاصية وتُعيد void.ثم اجعل initialState تمرّ في الترجمة بنوع إرجاعها الجديد.
{ [K in keyof T]: … }. أضف ? بعد المفتاح للاختيارية، و-? لإزالتها.","في MyOmit، أعِد تسمية المفاتيح بـ as وأرسل المحذوفة منها إلى never: as Exclude<P, K>. استخدام Exclude المدمجة مسموح.","في Setters، أعِد التسمية بـ template literal: as `set${Capitalize<K & string>}` . وفي initialState، تُعيد Object.fromEntries النوع { [k: string]: … }، فحوّل نتيجتها مرة واحدة إلى FieldState<T>."],"explanation":"كل utility type حلقة تكرار على المفاتيح. المرور على keyof T ينسخ المعدِّلات، فتضيف MyPartial الرمز ?، وتُزيله MyRequired بـ -? (التي تُسقط أيضًا الـ undefined الضمني)، وتحتفظ MyPick بالمعدِّلات الأصلية لأن K مقيَّد بـ keyof T. وتعمل MyOmit لأن المفتاح المحوَّل إلى never يختفي. أما Setters فتُظهر الاستخدام الآخر لـ as: إعادة تسمية كل مفتاح بـ template literal، حيث تصفّي K & string مفاتيح number وsymbol التي لا تستطيع Capitalize التعامل معها. ولا تستطيع Object.fromEntries معرفة مفاتيحك، فيمنح تحويلٌ واحد موثّق داخل initialState المستدعين نوعًا دقيقًا.
initialState تبني لكل حقل حالة غير ملموسة وخالية من الأخطاء"}},"words":615,"readMinutes":4}