قوانین اولویت B : به شدت توصیه می‌شوند ​

این قوانین برای بهبود خوانایی و یا تجربه توسعه‌ دهنده در اکثر پروژه‌ها، ایجاد شده اند. اگر این قوانین را نقض کنید، کد شما هنوز اجرا خواهد شد، اما نقض‌ها باید نادر و به خوبی توجیه شده باشند.

فایل‌های کامپوننت ​

هرگاه یک سیستم ساخت (build system) برای ادغام فایل‌ها موجود باشد، هر کامپوننت باید در یک فایل جداگانه قرار گیرد.

این کمک می‌کند تا هنگامی که نیاز به ویرایش یک کامپوننت دارید یا می‌خواهید نحوه استفاده از آن را بررسی کنید، با سرعت بیشتری آن کامپوننت را پیدا کنید.

app.component('TodoList', {
  // ...
})

app.component('TodoItem', {
  // ...
})

components/
|- TodoList.js
|- TodoItem.js

components/
|- TodoList.vue
|- TodoItem.vue

فرمت نامگذاری کامپوننت‌های تک فایلی ​

نام‌ فایل‌ کامپوننت‌های تک فایلی (Single-File Components) باید همیشه به صورت PascalCase یا همیشه kebab-case باشند.

PascalCase بهترین عملکرد را در تکمیل خودکار در ویرایشگرهای کد دارد، زیرا با نحوه ارجاع به کامپوننت‌ها در JS یا JSX و تمپلیت‌ها تا جای ممکن هماهنگ است. با این حال، نام‌ فایل با مخلوط حروف بزرگ و کوچک ممکن است گاهی مشکلاتی را در سیستم‌های حساس به حروف بزرگ و کوچک ایجاد کند، به همین دلیل kebab-case هم کاملاً قابل قبول است.

components/
|- mycomponent.vue

components/
|- myComponent.vue

components/
|- MyComponent.vue

components/
|- my-component.vue

نامگذاری کامپوننت‌های پایه ​

کامپوننت های پایه (همچنین به عنوان presentational، dumb، یا pure components شناخته می شوند) که از استایل و قراردادهای خاص برنامه برخوردارند، همگی باید با یک پیشوند خاص شروع شوند، مانند Base، App یا V.

components/
|- MyButton.vue
|- VueTable.vue
|- Icon.vue

components/
|- BaseButton.vue
|- BaseTable.vue
|- BaseIcon.vue

components/
|- AppButton.vue
|- AppTable.vue
|- AppIcon.vue

components/
|- VButton.vue
|- VTable.vue
|- VIcon.vue

نامگذاری کامپوننت‌های تک نمونه‌ای ​

کامپوننت هایی که تنها باید یک نمونه فعال داشته باشند، باید با پیشوند The شروع شوند تا نشان دهند که تنها می‌تواند یک نمونه از آن وجود داشته باشد.

این به این معنا نیست که این کامپوننت تنها در یک صفحه استفاده می‌شود، بلکه تنها یک بار برای هر صفحه استفاده خواهد شد. این کامپوننت‌ها هرگز پراپ‌ها را قبول نمی‌کنند، زیرا بطور خاص برای برنامه‌ی شما ساخته شده‌اند نه اینکه محتوایشان در برنامه‌ی شما هم استفاده شود. اگر نیاز به افزودن پراپ پیدا کنید، این نشانگر خوبی است که در واقع این یک کامپوننت قابل استفاده مجدد است که در حال حاضر فقط یکبار برای هر صفحه استفاده می‌شود.

components/
|- Heading.vue
|- MySidebar.vue

components/
|- TheHeading.vue
|- TheSidebar.vue

نام‌گذاری کامپوننت های مرتبط ​

کامپوننت های فرزندی که به شدت با والد خود ارتباط دارند، باید نام والد را به عنوان پیشوند شامل شوند.

اگر دلیل وجود یک کامپوننت، فقط استفاده در بخشی از یک کامپوننت والد باشد، این رابطه باید در نام آن واضح باشد. از آنجا که ویرایشگرها معمولاً فایل‌ها را به ترتیب الفبا مرتب می‌کنند، این همچنین باعث می‌شود تا این فایل‌های مرتبط در کنار یکدیگر قرار گیرند.

components/
|- TodoList/
   |- Item/
      |- index.vue
      |- Button.vue
   |- index.vue

components/
|- TodoList/
   |- Item/
      |- Button.vue
   |- Item.vue
|- TodoList.vue

components/
|- TodoList.vue
|- TodoItem.vue
|- TodoButton.vue

components/
|- SearchSidebar.vue
|- NavigationForSearchSidebar.vue

components/
|- TodoList.vue
|- TodoListItem.vue
|- TodoListItemButton.vue

components/
|- SearchSidebar.vue
|- SearchSidebarNavigation.vue

ترتیب کلمات در نامگذاری کامپوننت ها ​

نام‌های کامپوننت‌ها باید با کلمات سطح بالا (معمولاً کلمات عمومی‌تر) شروع شده و با کلمات توصیفی و اصلاح کننده به پایان برسند.

components/
|- ClearSearchButton.vue
|- ExcludeFromSearchInput.vue
|- LaunchOnStartupCheckbox.vue
|- RunSearchButton.vue
|- SearchInput.vue
|- TermsCheckbox.vue

components/
|- SearchButtonClear.vue
|- SearchButtonRun.vue
|- SearchInputExcludeGlob.vue
|- SearchInputQuery.vue
|- SettingsCheckboxLaunchOnStartup.vue
|- SettingsCheckboxTerms.vue

components/
|- ClearSearchButton.vue
|- ExcludeFromSearchInput.vue
|- LaunchOnStartupCheckbox.vue
|- RunSearchButton.vue
|- SearchInput.vue
|- TermsCheckbox.vue

components/
|- SearchButtonClear.vue
|- SearchButtonRun.vue
|- SearchInputQuery.vue
|- SearchInputExcludeGlob.vue
|- SettingsCheckboxTerms.vue
|- SettingsCheckboxLaunchOnStartup.vue

کامپوننت های خود بسته شونده ​

کامپوننت های بدون محتوا درون تگ html خود، باید در کامپوننت های تک فایلی (Single-File Components)، تمپلیت‌های رشته‌ای و JSX بصورت خود بسته شونده (self-closing) باشند، اما در تمپلیت‌های تعریف شده درون DOM ها هرگز.

کامپوننت هایی که خود بسته می شوند این پیام را می‌رسانند که نه تنها محتوایی ندارند، بلکه قرار است محتوایی نداشته باشند. این تفاوت میان یک صفحه خالی در یک کتاب و یک صفحه با برچسب "این صفحه عمدا خالی مانده است" می باشد. همچنین کد شما بدون تگ‌های بسته غیرضروری تمیزتر خواهد بود.

متأسفانه، HTML اجازه نمی‌دهد که عناصر سفارشی خودشان به صورت خودکار بسته شوند. - تنها official "void" elements این قابلیت را دارند. به همین دلیل است که این استراتژی فقط زمانی امکان‌پذیر است که کامپایلر تمپلیت Vue قادر به دسترسی به تمپلیت قبل از DOM باشد و سپس HTML مطابق با استاندارد DOM را ارائه دهد.

<!-- JSX در کامپوننت های تک فایلی، تمپلیت‌های رشته‌ای و -->
<MyComponent></MyComponent>

<!-- DOM در تمپلیت‌های داخل -->
<my-component/>

<!-- JSX در کامپوننت های تک فایلی، تمپلیت‌های رشته‌ای و -->
<MyComponent/>

<!-- DOM در تمپلیت‌های داخل -->
<my-component></my-component>

فرمت نامگذاری کامپوننت ها در تمپلیت‌ها ​

در بیشتر پروژه‌ها، نام کامپوننت ها باید در Single-File Components و تمپلیت‌های رشته‌ای به صورت PascalCase باشد، اما در تمپلیت‌های داخل DOM به صورت kebab-case باشد.

PascalCase در مقایسه با kebab-case مزایایی دارد :

• ویرایشگرها می‌توانند در تمپلیت‌ها نام کامپوننت ها را به صورت خودکار تکمیل کنند، زیرا PascalCase در جاوااسکریپت هم استفاده می‌شود.

• <MyComponent> (فرم PascalCase) از لحاظ بصری بیشتر از <my-component> (فرم kebab-case) از عناصر خود HTML مجزا است، زیرا به اندازه دو کاراکتر میان آنها تفاوت وجود دارد (دو حرف بزرگ در حالت PascalCase) در حالی که در حالت kebab-case تنها یک تفاوت وجود دارد (خط فاصله).

• اگر شما از هرگونه عنصر غیر Vue در تمپلیت خود استفاده کنید، مانند یک کامپوننت وب، PascalCase اطمینان حاصل می کند که کامپوننت های Vue شما به صورت مجزا قابل رویت باقی می‌مانند.

متاسفانه، بنابر عدم حساسیت HTML به حروف بزرگ و کوچک (case insensitivity)، در تمپلیت‌های داخل DOM بایستی همچنان از kebab-case استفاده نماییم.

همچنین توجه داشته باشید که اگر قبلاً روی kebab-case سرمایه گذاری زیادی کرده اید، سازگاری با قراردادهای HTML و امکان استفاده از پوشش یکسان در تمام پروژه های شما ممکن است مهمتر از مزایای ذکر شده در بالا باشد. در آن حالت ها، استفاده از kebab-case در همه جا هم قابل قبول است.

<!-- در کامپوننت های تک فایلی و تمپلیت‌های رشته‌ای -->
<mycomponent/>

<!-- در کامپوننت های تک فایلی و تمپلیت‌های رشته‌ای -->
<myComponent/>

<!-- DOM در تمپلیت‌های داخل -->
<MyComponent></MyComponent>

<!-- در کامپوننت های تک فایلی و تمپلیت‌های رشته‌ای -->
<MyComponent/>

<!-- DOM در تمپلیت‌های داخل -->
<my-component></my-component>

<!-- همه جا -->
<my-component></my-component>

نامگذاری کامپوننت ها و فرمت آن در JS/JSX ​

نامگذاری کامپوننت ها در JS/JSX باید همواره به صورت PascalCase باشد، گرچه ممکن است آنها در داخل رشته‌ها در برنامه‌های ساده‌تر که تنها از کامپوننت سراسری app.component استفاده می‌کنند به صورت kebab-case باشند.

app.component('myComponent', {
  // ...
})

import myComponent from './MyComponent.vue'

export default {
  name: 'myComponent'
  // ...
}

export default {
  name: 'my-component'
  // ...
}

app.component('MyComponent', {
  // ...
})

app.component('my-component', {
  // ...
})

import MyComponent from './MyComponent.vue'

export default {
  name: 'MyComponent'
  // ...
}

نام گذاری کامل کامپوننت‌ها ​

در نامگذاری کامپوننت‌ها واژگان بصورت کامل باید به واژگان اختصاری ترجیح داده شوند.

کامل کردن خودکار کلمات در ویرایشگرها، زحمت نوشتن نام‌های طولانی‌تر را خیلی کم می‌کند، در حالی که وضوحی که ایجاد می‌کند بسیار ارزشمند است. همواره باید از اختصارهای غیر رایج پرهیز نمود.

components/
|- SdSettings.vue
|- UProfOpts.vue

components/
|- StudentDashboardSettings.vue
|- UserProfileOptions.vue

فرمت نام گذاری prop ها ​

نامگذاری prop ها باید همواره با استفاده از فرمت camelCase (کلمه اول حرف کوچک، کلمه دوم حرف بزرگ) در حین تعریف کردن صورت بپذیرد. وقتی که از prop در تمپلیت‌های داخل DOM استفاده می شود، آنها باید به صورت kebab-case باشند. تمپلیت‌های کامپوننت های تک فایلی و JSX می توانند هم از prop ها به صورت kebab-case و هم camelCase استفاده نمایند. فرمت باید به صورت ثابت و استوار باشد. اگر شما انتخاب کردید که از prop ها به صورت camelCase استفاده کنید، اطمینان حاصل کنید که در طول برنامه خود از حالت kebab-case استفاده نمی‌کنید.

props: {
  'greeting-text': String
}

const props = defineProps({
  'greeting-text': String
})

// DOM برای تمپلیت‌های داخل
<welcome-message greetingText="hi"></welcome-message>

props: {
  greetingText: String
}

const props = defineProps({
  greetingText: String
})

// برای کامپوننت های تک فایلی، لطفا اطمینان حاصل کنید که فرمت در تمام پروژه ثابت می‌ماند
// شما می‌توانید از هر قراردادی استفاده کنید ولی ما ترکیب کردن دو نوع فرمت استایل دهی را پیشنهاد نمی‌کنیم
<WelcomeMessage greeting-text="hi"/>
// یا
<WelcomeMessage greetingText="hi"/>

// DOM برای تمپلیت‌های داخل
<welcome-message greeting-text="hi"></welcome-message>

عناصر چند صفتی ​

عناصر (elements) با چند صفت (attribute) باید در چند خط گسترده شوند، به صورت یک attribute در هر خط.

در جاوااسکریپت، جدا کردن پراپرتی‌ها در چند خط در آبجکت‌های دارای چند پراپرتی به طور گسترده‌ای به عنوان یک قرارداد خوب در نظر گرفته می‌شود، زیرا خواندن آن آسان‌تر است. این موضوع برای تمپلیت‌های ما در Vue و JSX نیز همین گونه در نظر گرفته می‌شود.

<img src="https://vuejs.org/images/logo.png" alt="Vue Logo">

<MyComponent foo="a" bar="b" baz="c"/>

<img
  src="https://vuejs.org/images/logo.png"
  alt="Vue Logo"
>

<MyComponent
  foo="a"
  bar="b"
  baz="c"
/>

استفاده از عبارات ساده در تمپلیت‌ها ​

تمپلیت‌های کامپوننت باید تنها شامل عبارات ساده باشند، عبارات پیچیده تر در داخل method یا پراپرتی‌های computed (همان computed در Vue) نوشته می‌شوند.

عبارات پیچیده در تمپلیت‌های شما، آنها را کمتر قابل درک می سازد. ما باید تلاش کنیم تا مقداری که باید ظاهر شود را توصیف کنیم، نه چگونگی محاسبه آن مقدار را. method یا پراپرتی‌های computed کد‌های ما را قابل استفاده مجدد می‌کند.

{{
  fullName.split(' ').map((word) => {
    return word[0].toUpperCase() + word.slice(1)
  }).join(' ')
}}

<!-- داخل یک تمپلیت -->
{{ normalizedFullName }}

// عبارت پیچیده به داخل یک پراپرتی کامپیوتد منتقل شده است
computed: {
  normalizedFullName() {
    return this.fullName.split(' ')
      .map(word => word[0].toUpperCase() + word.slice(1))
      .join(' ')
  }
}

// عبارت پیچیده به داخل یک پراپرتی کامپیوتد منتقل شده است
const normalizedFullName = computed(() =>
  fullName.value
    .split(' ')
    .map((word) => word[0].toUpperCase() + word.slice(1))
    .join(' ')
)

پراپرتی‌های computed ساده ​

پراپرتی‌های computed پیچیده باید تا جای ممکن به تعدادی پراپرتی ساده تر تقسیم شوند.

computed: {
  price() {
    const basePrice = this.manufactureCost / (1 - this.profitMargin)
    return (
      basePrice -
      basePrice * (this.discountPercent || 0)
    )
  }
}

const price = computed(() => {
  const basePrice = manufactureCost.value / (1 - profitMargin.value)
  return basePrice - basePrice * (discountPercent.value || 0)
})

computed: {
  basePrice() {
    return this.manufactureCost / (1 - this.profitMargin)
  },

  discount() {
    return this.basePrice * (this.discountPercent || 0)
  },

  finalPrice() {
    return this.basePrice - this.discount
  }
}

const basePrice = computed(
  () => manufactureCost.value / (1 - profitMargin.value)
)

const discount = computed(
  () => basePrice.value * (discountPercent.value || 0)
)

const finalPrice = computed(() => basePrice.value - discount.value)

مقادیر attribute با علامت نقل و قول (" ") ​

مقادیر attribute عناصر HTML غیرخالی باید همواره در داخل علامت نقل و قول (" ") (به صورت تک کوت یا دابل کوت، هر کدام که در کد JS داخل آن استفاده نشده باشد) استفاده شوند.

در حالی که مقادیر attribute بدون داشتن هیچ فاصله (space) نیازی به داشتن کوت در HTML ندارند، این عادت که اغلب منجر به پرهیز از فاصله ها می‌شود، مقادیر attribute را ناخوانا می‌کند.

<input type=text>

<AppSidebar :style={width:sidebarWidth+'px'}>

<input type="text">

<AppSidebar :style="{ width: sidebarWidth + 'px' }">

دستورالعمل‌های کوتاه نویسی ​

دستورالعمل‌های کوتاه نویسی (Directive shorthands) (: برای :v-bind, @ برای :v-on برای # برای v-slot) باید یا همواره استفاده شده یا هیچوقت استفاده نشوند.

<input
  v-bind:value="newTodoText"
  :placeholder="newTodoInstructions"
>

<input
  v-on:input="onInput"
  @focus="onFocus"
>

<template v-slot:header>
  <h1>Here might be a page title</h1>
</template>

<template #footer>
  <p>Here's some contact info</p>
</template>

<input
  :value="newTodoText"
  :placeholder="newTodoInstructions"
>

<input
  v-bind:value="newTodoText"
  v-bind:placeholder="newTodoInstructions"
>

<input
  @input="onInput"
  @focus="onFocus"
>

<input
  v-on:input="onInput"
  v-on:focus="onFocus"
>

<template v-slot:header>
  <h1>Here might be a page title</h1>
</template>

<template v-slot:footer>
  <p>Here's some contact info</p>
</template>

<template #header>
  <h1>Here might be a page title</h1>
</template>

<template #footer>
  <p>Here's some contact info</p>
</template>