Angular Academy · درس

واجهة ControlValueAccessor

اربط عنصر واجهة مخصصًا بنماذج Angular

واجهة ControlValueAccessor درس مجاني في Angular Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Angular Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Angular Academy 4 دروس في المجموع.

لماذا نحتاج إلى عناصر تحكم مخصصة

تعمل نماذج Angular مع حقول الإدخال الأصلية مباشرةً. ولجعل مكوّنك الخاص (مثل أداة تقييم، أو منتقي ألوان، أو مفتاح تبديل) قابلًا للاستخدام مع ngModel وformControlName، يجب أن يطبّق ControlValueAccessor.

الجسر

يُعد ControlValueAccessor (CVA) الجسر بين نموذج Angular للنموذج وعرض مكوّنك. وهو يحدد كيفية كتابة النموذج للقيم داخليًا، وكيف تنتقل تغييرات المستخدم إلى الخارج.

الواجهة

يتطلب CVA أربع دوال: writeValue وregisterOnChange وregisterOnTouched، إضافةً إلى setDisabledState الاختيارية.

interface ControlValueAccessor {
  writeValue(value: any): void;
  registerOnChange(fn: (v: any) => void): void;
  registerOnTouched(fn: () => void): void;
  setDisabledState?(isDisabled: boolean): void;
}

تسجيل الموفّر

أخبر Angular بأن مكوّنك موفّر قيم من خلال توفير NG_VALUE_ACCESSOR مع multi: true، واستخدام useExisting للإشارة إلى المكوّن.

import { NG_VALUE_ACCESSOR } from '@angular/forms';
import { forwardRef } from '@angular/core';

providers: [{
  provide: NG_VALUE_ACCESSOR,
  useExisting: forwardRef(() => RatingComponent),
  multi: true
}]

لماذا نستخدم forwardRef

نحتاج إلى forwardRef لأن الصنف يشير إلى نفسه في بياناته الوصفية قبل تعريف الصنف. ويؤجل ذلك حل المرجع حتى يصبح الصنف موجودًا.

هيكل المكوّن

يعلن عنصر التحكم المخصص عن الموفّر ويطبّق دوال الواجهة. ويحتفظ الصنف بالقيمة الحالية داخليًا.

@Component({
  selector: 'app-rating',
  providers: [/* NG_VALUE_ACCESSOR ... */]
})
export class RatingComponent implements ControlValueAccessor {
  value = 0;
  // writeValue, registerOnChange, registerOnTouched ...
}

استخدامه مثل عنصر أصلي

بعد تطبيق CVA، يندمج مكوّنك مع النماذج المعتمدة على القوالب والنماذج التفاعلية تمامًا مثل حقل الإدخال الأصلي.

<app-rating formControlName="stars"></app-rating>
<!-- or -->
<app-rating [(ngModel)]="stars"></app-rating>

اتجاها البيانات

يتدفق model-to-view عبر writeValue (يدفع Angular قيمة النموذج إلى الداخل). أما view-to-model فيتدفق عبر الاستدعاء المسجّل في registerOnChange (تدفع تغييرات المستخدم إلى الخارج).

تتبّع حالة اللمس

تعتمد تجربة المستخدم في التحقق من النموذج على حالة touched. وتُخطر Angular بذلك عبر الاستدعاء القادم من registerOnTouched، وعادةً عند فقدان التركيز.

الحالة المعطّلة

عندما يعطّل النموذج عنصر التحكم (control.disable())، تستدعي Angular الدالة setDisabledState حتى يتمكن مكوّنك من عكس الحالة بصريًا وتجاهل الإدخال.

خارطة الطريق

تطبّق الدروس التالية كل جزء على حدة: كتابة القيم وتسجيلها، ومعالجة حالتي التعطيل واللمس، وإضافة التحقق. وتجعل هذه الأجزاء مجتمعةً عنصر تحكم مخصصًا مدمجًا بالكامل.

تحقق سريع

تحقق من أساسيات CVA لديك.

مراجعة

تعلّمت أن ControlValueAccessor يربط المكوّنات المخصصة بنماذج Angular عبر أربع دوال، تُسجّل من خلال NG_VALUE_ACCESSOR باستخدام forwardRef وmulti: true. والخطوة التالية هي تطبيق كتابة القيم وتسجيلها.

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

هل درس «واجهة ControlValueAccessor» مجاني؟

نعم — نص درس «واجهة ControlValueAccessor» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Angular Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Angular Academy 4 دروس في المجموع.

ماذا ستتعلم في «واجهة ControlValueAccessor»؟

اربط عنصر واجهة مخصصًا بنماذج Angular تتمرن على Angular Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Angular Academy؟

لا تُشترط خبرة سابقة. Angular Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «واجهة ControlValueAccessor»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Angular Academy هذا؟

نعم. كل درس في Angular Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Angular Academy