السمات الموجهة المدمجة ​

v-text ​

تقوم بتحديث محتوى النص الخاص بالعنصر.

• تتوقع قيمة من نوع: string

• التفاصيل

v-text تعمل عن طريق تعيين خاصية textContent للعنصر، لذا ستقوم بالكتابة فوق أي محتوى موجود بالفعل داخل العنصر. إذا كنت بحاجة إلى تحديث جزء من textContent، يجب عليك استخدام الاقحام النص باستخدام الأقواس المعقوفة بدلاً من ذلك.

• مثال

  template

  <span v-text="msg"></span>
  <!-- مماثل لـ
  <span>{{msg}}</span>

• اطلع أيضاً على صيغة القالب - الاقحام النصي

v-html ​

تقوم بتحديث خاصية innerHTML للعنصر.

• تتوقع قيمة من نوع: string

• التفاصيل

محتويات v-html تُقحم كـ HTML خام - لن تُعالج صيغة القالب لـ Vue. إذا وجدت نفسك تحاول تركيب قوالب باستخدام v-html، حاول إعادة التفكير في الحل باستخدام المكونات بدلاً من ذلك.

::: تنبيه ملاحظة أمان تصيير HTML عشوائي بشكل ديناميكي على موقعك الإلكتروني يمكن أن يكون خطيرًا للغاية لأنه يمكن أن يؤدي بسهولة إلى هجمات XSS. استخدم v-html فقط على محتوى موثوق به ولا تستخدمه أبدًا على محتوى يقدمه المستخدم. :::

في المكونات أحادية الملف، لن تُطبَّق الأنماط المحددة على محتوى داخل v-html، لأن هذا الـ HTML لا يُعالج بواسطة مصرف قوالب Vue. إذا كنت تريد استهداف محتوى v-html بـ CSS محدد، يمكنك بدلاً من ذلك استخدام وحدات CSS أو عنصر <style> إضافي عام مع استراتيجية تحديد يدوية مثل BEM.

• مثال

  template

  <div v-html="html"></div>

• اطلع أيضاً على صيغة القالب - الـHTML الخام

v-show ​

تقوم بتبديل عرض العنصر استنادًا إلى قيمة العبارة.

• تتوقع قيمة من نوع: any

• التفاصيل

  v-show تعمل عن طريق تعيين خاصية CSS display عبر التنسيقات السطرية، وستحاول احترام قيمة display الأولية عندما يكون العنصر مرئيًا. كما أنها تُشغِّل الانتقالات عندما تتغير حالتها.

• اطلع أيضاً على التصيير الشرطي - v-show

v-if ​

تقوم بتصيير عنصر أو قالب مقطعي استنادًا إلى قيمة العبارة.

• تتوقع قيمة من: any

• التفاصيل

  عند تبديل عنصر v-if، يُتلف العنصر والمُوجهات/المكونات الموجودة بداخله وإعادة بنائها. إذا كانت الحالة الأولية غير صحيحة، فلن يصير المحتوى الداخلي على الإطلاق.

  يمكن استخدامها على <template> للدلالة على كتلة شرطية تحتوي على نص أو عناصر متعددة.

  تُشغِّل هذه الموجهة الانتقالات عندما تتغير حالتها.

عند استخدامها بجانب v-if ، فإن v-if لها أولوية أعلى من v-for. لا نوصي باستخدام هاتين الموجهتين معًا على عنصر واحد — انظر إلى دليل تصيير القوائم للحصول على التفاصيل.

• اطلع أيضاً على التصيير الشرطي - v-if

v-else ​

تدل على "طرف آخر من كتلة شرطية" لـ v-if أو سلسلة v-if / v-else-if.

• لا تتوقع أي عبارة أوقيمة

• التفاصيل

  • تقييد: يجب أن يحتوي العنصر السابق على v-if أو v-else-if.

  • يمكن استخدامها على <template> للدلالة على كتلة شرطية تحتوي على نص أو عناصر متعددة.

• مثال

  template

  <div v-if="Math.random() > 0.5">
    يمكنك رؤيتي الآن
  </div>
  <div v-else>
    لا يمكنك رؤيتي الآن
  </div>

• اطلع أيضاً على التصيير الشرطي - v-else

v-else-if ​

تدل على "طرف آخر من كتلة شرطية" لـ v-if. يمكن ربطها.

• تتوقع قيمة من نوع: any

• *التفاصيل

  • تقييد: يجب أن يحتوي العنصر السابق على v-if أو v-else-if.

  • يمكن استخدامها على <template> للدلالة على كتلة شرطية تحتوي على نص أو عناصر متعددة.

• مثال

  template

  <div v-if="type === 'A'">
    A
  </div>
  <div v-else-if="type === 'B'">
    B
  </div>
  <div v-else-if="type === 'C'">
    C
  </div>
  <div v-else>
    لا A/B/C
  </div>

• اطلع أيضاً على التصيير الشرطي - v-else-if

v-for ​

بتصيير العنصر أو كتلة القالب عدة مرات استنادًا إلى البيانات المصدرية.

• تتوقع قيم من نوع: Array | Object | number | string | Iterable

• التفاصيل

  يجب أن تستخدم قيمة الموجهة الصيغة الخاصة التسمية البديلة داخل العبارة لتوفير تسمية بديلة للعنصر الحالي الذي يُكرَّر:

  template

  <div v-for="item in items">
    {{ item.text }}
  </div>

  بدلاً من ذلك، يمكنك أيضًا تحديد تسمية بديلة للمؤشر (أو المفتاح إذا استخدمت على كائن):

  template

  <div v-for="(item, index) in items"></div>
  <div v-for="(value, key) in object"></div>
  <div v-for="(value, name, index) in object"></div>

  السلوك الافتراضي لـ v-for سيحاول تصليح العناصر في مكانها دون نقلها. لإجباره على إعادة ترتيب العناصر، يجب عليك توفير تلميح ترتيب باستخدام السمة الخاصة key:

  template

  <div v-for="item in items" :key="item.id">
    {{ item.text }}
  </div>

v-for يمكن أن تعمل أيضًا على القيم التي تنفذ بروتوكول قابلية hلتكرار، بما في ذلك Map و Set الأصليتين.

• اطلع أيضاً على
  • تصيير القوائم

v-on ​

تقوم بإرفاق مستمع حدث بالعنصر.

• الاختصار: @

• تتوقع قيمة من نوع: Function | Inline Statement | Object (without argument)

• الوسيط: event (إختياري إذا استخدمت صيغة الكائن)

• المعدلات

  • .stop - تستدعي event.stopPropagation().
  • .prevent - تستدعي event.preventDefault().
  • .capture - تضيف مستمع حدث في وضع الالتقاط.
  • .self - تُشغِّل المعالج فقط إذا تم إرسال الحدث من هذا العنصر.
  • .{keyAlias} - تُشغِّل المعالج فقط على مفاتيح معينة.
  • .once - تُشغِّل المعالج مرة واحدة على الأكثر.
  • .left - تُشغِّل المعالج فقط لأحداث الفأرة للزر الأيسر.
  • .right - تُشغِّل المعالج فقط لأحداث الفأرة للزر الأيمن.
  • .middle - تُشغِّل المعالج فقط لأحداث الفأرة للزر الأوسط.
  • .passive - تُرفق حدث DOM مع { passive: true }.

• التفاصيل

يستنتج نوع الحدث عن طريق الوسيط. يمكن أن تكون العبارة اسم دالة تابعة، أو عبارة سطرية، أو محذوفة إذا كانت هناك معدلات موجودة.

عند استخدامها على عنصر عادي، فهي تستمع إلى حدث DOM أصلي فقط. عند استخدامها على مكون عنصر مخصص، فهي تستمع إلى الأحداث المخصصة المُرسلة على هذا المكون الابن.

عند الاستماع إلى أحداث DOM الأصلية، تستقبل الدالة الحدث الأصلي كوسيط وحيد. إذا كنت تستخدم عبارة سطرية، فإن العبارة لديها وصول إلى خاصية event$ الخاصة: v-on:click="handle('ok', $event)".

v-on تدعم أيضًا ربط كائن من أزواج المستمع/الحدث بدون وسيط. تجدر الملاحظة عند استخدام صيغة الكائن، فهي لا تدعم أي معدلات.

• مثال

  template

  <!-- دالة معالجة -->
  <button v-on:click="doThis"></button>
  
  <!-- حدث ديناميكي -->
  <button v-on:[event]="doThis"></button>
  
  <!-- تعليمة سطرية -->
  <button v-on:click="doThat('hello', $event)"></button>
  
  <!-- اختصار -->
  <button @click="doThis"></button>
  
  <!-- اختصار حدث ديناميكي -->
  <button @[event]="doThis"></button>
  
  <!-- إيقاف الانتشار -->
  <button @click.stop="doThis"></button>
  
  <!-- منع السلوك الافتراضي -->
  <button @click.prevent="doThis"></button>
  
  <!-- منع السلوك الافتراضي بدون عبارة -->
  <form @submit.prevent></form>
  
  <!-- ربط المعدلات -->
  <button @click.stop.prevent="doThis"></button>
  
  <!-- معدل المفتاح باستخدام keyAlias -->
  <input @keyup.enter="onEnter" />
  
  <!-- سيُشغل حدث النقر مرة واحدة على الأكثر -->
  <button v-on:click.once="doThis"></button>
  
  <!-- صيغة الكائن -->
  <button v-on="{ mousedown: doThis, mouseup: doThat }"></button>

الاستماع إلى الأحداث المخصصة على مكون ابن (يستدعى المعالج عند إرسال "my-event" على المكون الابن):

<MyComponent @my-event="handleThis" />

<!-- تعليمة سطرية -->
<MyComponent @my-event="handleThis(123, $event)" />

• اطلع أيضاً على
  • معالجة الأحداث
  • المكونات - الأحداث المخصصة

v-bind ​

تقوم بربط سمة واحدة أو أكثر بشكل ديناميكي، أو خاصية مكون بعبارة.

• اختصار: : أو . (عند استخدام المعدل .prop )

• تتوقع قيم من نوع: any (with argument) | Object (without argument)

• الوسيط: attrOrProp (optional)

• المعدلات

  • camel. - تحويل اسم السمة بتنسيق kebab-case إلى camelCase.
  • .prop - إجبار ربط ليُعين كخاصية DOM. ^3.2+
  • .attr - إجبار ربط ليُعين كسمة DOM. ^3.2+

• الاستخدام

  عند استخدامها لربط سمة class أو style، فإن v-bind تدعم أنواع قيم إضافية مثل Array أو Objects. انظر إلى القسم المرتبط بالدليل أدناه للحصول على مزيد من التفاصيل.

  عند تعيين ربط على عنصر، فإن Vue بشكل افتراضي يتحقق مما إذا كان العنصر يحتوي على المفتاح المحدد كخاصية باستخدام فحص مشغل in. إذا عُرِّفت الخاصية، فسيُعين Vue القيمة كخاصية DOM بدلاً من سمة. هذا السيناريو يجب أن يعمل في معظم الحالات، ولكن يمكنك تجاوز هذا السلوك عن طريق استخدام معدلات prop. أو attr. بشكل صريح. هذا ضروري في بعض الأحيان، خاصة عند العمل مع عناصر مخصصة.

  عند استخدامها لربط خاصية مكون، يجب أن تُعلن الخاصية بشكل صحيح في المكون الابن.

  عند استخدامها بدون وسيط، يمكن استخدامها لربط كائن يحتوي على اسم وقيمة السمة.

• Example

  template

  <!-- ربط سمة -->
  <img v-bind:src="imageSrc" />
  
  <!-- اسم سمة ديناميكي -->
  <button v-bind:[key]="value"></button>
  
  <!-- اختصار -->
  <img :src="imageSrc" />
  
  <!-- اسم سمة ديناميكي مختصر -->
  <button :[key]="value"></button>
  
  <!-- مع التجميع النصي السطري -->
  <img :src="'/path/to/images/' + fileName" />
  
  <!-- ربط الفئة -->
  <div :class="{ red: isRed }"></div>
  <div :class="[classA, classB]"></div>
  <div :class="[classA, { classB: isB, classC: isC }]"></div>
  
  <!-- ربط التنسيقات -->
  <div :style="{ fontSize: size + 'px' }"></div>
  <div :style="[styleObjectA, styleObjectB]"></div>
  
  <!-- ربط كائن من السمات -->
  <div v-bind="{ id: someProp, 'other-attr': otherProp }"></div>
  
  <!-- ربط خاصية. يجب أن تُعلن "prop" في المكون الابن. -->
  <MyComponent :prop="someThing" />
  
  <!-- تمرير خاصيات المكون الأب المشتركة مع المكون الابن -->  
  <MyComponent v-bind="$props" />
  
  <!-- XLink -->
  <svg><a :xlink:special="foo"></a></svg>

  المعدل .prop لديه أيضًا اختصار مخصص، .:

  template

  <div :someProperty.prop="someObject"></div>
  
  <!-- مكافئ ل -->
  <div .someProperty="someObject"></div>

  المعدل camel. يسمح بتحويل اسم سمة v-bind إلى صيغو سنام الجمل عند استخدام قوالب in-DOM، على سبيل المثال سمة viewBox في ترميز الـSVG:

  template

  <svg :view-boxcamel.="viewBox"></svg>

  camel. ليست مطلوبة إذا كنت تستخدم قوالب سطرية، أو تقوم بترميز القالب مسبقًا مع خطوة بناء.

• اطلع أيضاً على

  • ربط الفئة والتنسيق
  • المكونات - تفاصيل تمرير الخاصية

v-model ​

تقوم بإنشاء ربط ذو اتجاهين على عنصر إدخال أو مكون.

• تتوقع قيمة من نوع: تختلف استنادًا إلى قيمة عنصر إدخال النموذج أو إخراج المكون

• Limited to:

  • <input>
  • <select>
  • <textarea>
  • المكونات

• المعدلات

  • .lazy - استمع إلى حدث change بدلاً من input
  • .number - يقوم بتحويل سلسلة الإدخال الصحيحة إلى أرقام
  • .trim - يقوم بحذف الفراغات من الإدخال

• اطلع أيضاً على

  • ربط إدخال النموذج
  • أحداث المكونات - الاستخدام مع v-model

v-slot ​

تدل على منافذ مسماة أو ذات نطاق تتوقع تلقي خاصيات.

• الاختصار: #

• تتوقع قيمة من نوع: عبارة JavaScript صالحة في موضع وسيط الدالة، بما في ذلك دعم التفكيك. اختياري - مطلوب فقط إذا كنت تتوقع تمرير خاصيات إلى المنفذ.

• الوسيط: اسم المنفذ (اختياري، بشكل افتراضي default)

• محصورة في:

  • <template>
  • المكونات (لمنفذ افتراضي وحيد مع خاصيات)

• مثال

  template

  <!-- منافذ مسماة -->
  <BaseLayout>
    <template v-slot:header>
      محتوى الترويسة
    </template>
  
    <template v-slot:default>
      محتوى المنفذ الافتراضي
    </template>
  
    <template v-slot:footer>
      محتوى التذييل
    </template>
  </BaseLayout>
  
  <!-- منفذ مسمى يتلقى خاصيات -->
  <InfiniteScroll>
    <template v-slot:item="slotProps">
      <div class="item">
        {{ slotProps.item.text }}
      </div>
    </template>
  </InfiniteScroll>
  
  <!-- منفذ افتراضي يتلقى خاصيات، مع التفكيك -->
  <Mouse v-slot="{ x, y }">
    Mouse position: {{ x }}, {{ y }}
  </Mouse>

• اطلع أيضاً على

  • المكونات - المنافذ

v-pre ​

تخطي التصريف لهذا العنصر وجميع مكوناته الأبناء.

• لا تتوقع أي عبارة أوقيمة

• التفاصيل

  داخل العنصر مع v-pre، سيُحافظ على جميع ترميزات قوالب Vue وتصييرها كما هي. أكثر حالة استخدام شائعة لهذا هي عرض علامات الاقحام النصي الخام.

• مثال

  template

  <span v-pre>{{هذا المحتوى لا يصرف }}</span>

v-once ​

تصيير العنصر والمكون مرة واحدة فقط، وتخطي التحديثات المستقبلية.

• لا تتوقع عبارات كقيم

• التفاصيل

  عند إعادة التصيير، سيتم التعامل مع العنصر/المكون وجميع أبنائه كمحتوى ثابت وتخطيه. يمكن استخدام هذا لتحسين أداء التحديث.

  template

  <!-- عنصر واحد -->
  <span v-once>This will never change: {{msg}}</span>
  <!-- العنصر لديه أبناء -->
  <div v-once>
    <h1>تعليق</h1>
    <p>{{msg}}</p>
  </div>
  <!-- مكون -->
  <MyComponent v-once :comment="msg"></MyComponent>
  <!-- مُوجِّهة `v-for` -->
  <ul>
    <li v-for="i in list" v-once>{{i}}</li>
  </ul>

  منذ 3.2، يمكنك أيضًا تخزين جزء من القالب مع شروط إبطال باستخدام v-memo.

• اطلع أيضاً على

  • صيغة ربط البيانات - الاقحامات
  • v-memo

v-memo ​

• تتوقع قيمة من نوع: any[]

• التفاصيل

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

<div v-memo="[valueA, valueB]">
  ...
</div>

عند إعادة تصيير المكون، إذا بقيت كل من valueA و valueB هي نفسها، فسيتم تخطي جميع التحديثات لهذا <div> وأبنائه. في الواقع، سيتم تخطي إنشاء عقد افتراضية للـDOM الافتراضي أيضًا لأنه يمكن إعادة استخدام نسخة الجزء المخزن من القالب.

من المهم تحديد مصفوفة التخزين بشكل صحيح، وإلا فقد نتخطى التحديثات التي يجب تطبيقها فعلًا. v-memo مع مصفوفة اعتماديات فارغة ("[]"=v-memo) ستكون مكافئة وظيفيًا لـ v-once.

الاستخدام مع v-for

وُفِّر v-memo فقط للتحسينات الدقيقة في السيناريوهات الحرجة من حيث الأداء ويجب أن يكون احتياجًا نادرًا. أكثر الحالات الشائعة التي قد تثبت أنها مفيدة هي عند تصيير قوائم v-for الكبيرة (حيث length > 1000):

<div v-for="item in list" :key="item.id" v-memo="[item.id === selected]">
  <p>المُعرف: {{ item.id }} - المعرف المختار: {{ item.id === selected }}</p>
  <p>...المزيد من العقد الأبناء</p>
</div>

عند تغيير حالة selected في المكون، سيُنشأ عدد كبير من العقد الافتراضية على الرغم من أن معظم العناصر لا تزال هي نفسها تمامًا. يقول استخدام v-memo هنا بشكل أساسي "قم بتحديث هذا العنصر فقط إذا غُيِّر من غير المحدد إلى محدد، أو العكس". هذا يسمح لكل عنصر غير متأثر بإعادة استخدام العقد الافتراضية السابقة وتخطي عملية المطابقة بالكامل. لاحظ أنه لا يلزمنا تضمين item.id في مصفوفة اعتماديات التخزين هنا لأن Vue يستنتجها تلقائيًا من الـkey: التابع للعنصر.

يمكن أيضًا استخدام v-memo على المكونات لمنع التحديثات غير المرغوب فيها يدويًا في الحالات الحدية المعينة حيث أُلغي تحسين فحص تحديث المكون الابن. ولكن مرة أخرى، فإنه من مسؤولية المطور تحديد مصفوفات الاعتماديات الصحيحة لتجنب تخطي التحديثات اللازمة.

• اطلع أيضاً على
  • v-once

v-cloak ​

يستخدم لإخفاء القالب غير المصرف في انتظار أن يكون جاهزًا.

• لا تتوقع أي عبارة أو قيمة

• التفاصيل

  هذه الموجهة مطلوبة فقط في إعدادات بدون عملية بناء.

  عند استخدام القوالب المدمجة في الـDOM، قد يكون هناك "وميض للقوالب غير المصرفة": قد يرى المستخدم علامات الاقحام النصي الخام حتى يقوم المكون المركب بتبديلها بالمحتوى المصيّر.

  سيظل v-cloak على العنصر حتى تُوصل نسخة المكون المرتبط. يمكن استخدامها مع قواعد CSS مثل [v-cloak] { display: none }، لإخفاء القوالب الخام حتى يكون المكون جاهزًا.

• مثال

  css

  [v-cloak] {
    display: none;
  }

  template

  <div v-cloak>
    {{ message }}
  </div>

  لن يكون العنصر <div> مرئيًا حتى يُصرَّف.