مواصفات صيغة المكونات أحادية الملف ​

نظرة عامة ​

المكونات أحادية الملف في Vue، يصطلح عليها باستخدام امتداد الملف vue.*، هي صيغة ملف مخصصة تستخدم صيغة على نحو شبيه بـ HTML لوصف مكون Vue. المكونات أحادية الملف في Vue تتوافق من حيث الصيغة مع HTML.

كل ملف *.vue يتكون من ثلاثة أنواع من الكتل اللغوية ذات المستوى الأعلى: <template>، <script>، و <style>، واختياريًا كتل مخصصة إضافية:

<template>
  <div class="example">{{ msg }}</div>
</template>

<script>
export default {
  data() {
    return {
      msg: 'مرحبًا'
    }
  }
}
</script>

<style>
.example {
  color: red;
}
</style>

<custom1>
  يمكن أن يكون هذا على سبيل المثال توثيق للمكون.
</custom1>

الكتل اللغوية ​

<template> ​

• كل ملف *.vue يمكن أن يحتوي على كتلة <template> ذات مستوى أعلى واحد على الأكثر.

• ستُستخرج المحتويات وتُمرر إلى vue/compiler-dom@، وتصييرها مسبقًا إلى دوال تصيير، وتعليقها على المكون المصدر داخل خيار render.

<script> ​

• كل ملف *.vue يمكن أن يحتوي على كتلة <script> ذات مستوى أعلى واحد على الأكثر (باستثناء <script setup>).

• تشغل الشيفرة كوحدة ES.

• التصدير الافتراضي يجب أن يكون كائن خيارات مكون Vue، إما ككائن عادي أو كقيمة إرجاع من defineComponent.

<script setup> ​

• كل ملف *.vue يمكن أن يحتوي على كتلة <script setup> ذات مستوى أعلى واحد على الأكثر (باستثناء <script> العادي).

• تعالج الشيفرة مسبقًا وتستخدم كدالة ()setup للمكون، وهذا يعني أنها ستُشغل في كل نسخة من المكون. يُعرض الربط الأعلى مستوى في <script setup> تلقائيًا للقالب. لمزيد من التفاصيل، اطلع على التوثيق المخصص لـ <script setup>.

<style> ​

• يمكن أن يحتوي ملف *.vue واحد على عدة عناصر <style>.

• يمكن أن يحتوي عنصر <style> على سمات scoped أو module (انظر ميزات صيغة المكونات أحادية الملف للمزيد من التفاصيل) للمساعدة في تغليف التنسيقات للمكون الحالي. يمكن مزج عدة عناصر <style> ذات أوضاع تغليف مختلفة في نفس المكون.

كتل مخصصة ​

يمكن تضمين كتل مخصصة إضافية في ملف *.vue لأي احتياجات محددة للمشروع، على سبيل المثال كتلة <docs>. بعض الأمثلة العملية للكتل المخصصة تشمل:

• Gridsome: <page-query>
• vite-plugin-vue-gql: <gql>
• vue-i18n: <i18n>

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

الاستنباط التلقائي لإسم المكون ​

يستنبط اسم المكون أحادي الملف من اسم الملف في الحالات التالية:

• تنسيق تحذيرات التطوير
• فحص أدوات التطوير
• الإشارة الذاتية التكرارية، على سبيل المثال ملف يسمى FooBar.vue يمكن أن يشير إلى نفسه كـ <FooBar/> في قالبه. وهذا له أولوية أقل من المكونات المسجلة/المستوردة بشكل صريح.

المعالجات المسبقة ​

الكتل يمكنها التصريح بلغات المعالجة المسبقة باستخدام سمة lang. أكثر الحالات شيوعًا هي استخدام TypeScript مع كتلة <script>:

<script lang="ts">
  // استخدم TypeScript
</script>

يمكن تطبيق lang على أي كتلة - على سبيل المثال يمكننا استخدام <style> مع Sass و <template> مع Pug:

<template lang="pug">
p {{ msg }}
</template>

<style lang="scss">
  $primary-color: #333;
  body {
    color: $primary-color;
  }
</style>

لاحظ أن الدمج مع معالجات مسبقة مختلفة قد يختلف حسب سلسلة الأدوات. تحقق من الوثائق المعنية للحصول على أمثلة:

• Vite
• Vue CLI
• webpack + vue-loader

استيرادات src ​

إذا كنت تفضل تقسيم مكونات *.vue إلى ملفات متعددة، يمكنك استخدام سمة src لاستيراد ملف خارجي لكتلة لغوية:

<template src="./template.html"></template>
<style src="./style.css"></style>
<script src="./script.js"></script>

انتبه إلى أن استيرادات src تتبع نفس قواعد تحديد المسارات كطلبات وحدة webpack، وهذا يعني:

• يجب أن تبدأ المسارات النسبية بـ ./
• يمكنك استيراد موارد من اعتماديات npm:

<!--  استيراد ملف من حزمة npm المثبتة "todomvc-app-css" -->
<style src="todomvc-app-css/index.css" />

استيرادات src تعمل أيضًا مع الكتل المخصصة، على سبيل المثال:

<unit-test src="./unit-test.js">
</unit-test>

Comments ​

داخل كل كتلة يجب أن تستخدم الصيغة التعليقية للغة المستخدمة (HTML، CSS، JavaScript، Pug، إلخ). للتعليقات ذات المستوى الأعلى، استخدم الصيغة التعليقية لـ HTML: <!-- محتويات التعليق هنا -->