استانداردهای JavaScript (JSS)

این سند استانداردها و قراردادهای JavaScript مورد استفاده در پروژه را تشریح می‌کند. پیروی از این استانداردها کد JavaScript سازگار و قابل نگهداری در سراسر اپلیکیشن را تضمین می‌کند.

مدیریت فرم AJAX

ما از data attribute ها برای تعریف رفتارهای JavaScript برای فرم‌ها و عناصر دیگر استفاده می‌کنیم. این رویکرد HTML ما را تمیز نگه می‌دارد و رفتار را از ساختار جدا می‌کند.

1. data-jsc="ajax-form" برای رویداد onsubmit

از این attribute روی عناصر form برای مدیریت ارسال فرم از طریق AJAX استفاده کنید:

<form action="/api/users" method="POST" data-jsc="ajax-form">
    <!-- فیلدهای فرم -->
    <button type="submit">ارسال</button>
</form>

این کار:

• از ارسال پیش‌فرض فرم جلوگیری می‌کند
• داده‌های فرم را serialize می‌کند
• درخواست AJAX به URL عمل فرم ارسال می‌کند
• پاسخ را به طور مناسب مدیریت می‌کند

2. data-jsc="ajax-form-onChange" برای رویداد onchange

از این attribute روی عناصر form که باید هنگام تغییر هر فیلد ارسال شوند استفاده کنید:

<form action="/api/filter-results" method="GET" data-jsc="ajax-form-onChange">
    <select name="category">
        <option value="">همه دسته‌بندی‌ها</option>
        <option value="1">دسته‌بندی 1</option>
        <option value="2">دسته‌بندی 2</option>
    </select>
    <!-- سایر فیلدهای فیلتر -->
</form>

این کار:

• تغییرات هر فیلد فرم را تشخیص می‌دهد
• هنگام وقوع تغییر، فرم را به طور خودکار از طریق AJAX ارسال می‌کند
• UI را با پاسخ به‌روزرسانی می‌کند

3. data-jsc="ajax-request" برای رویداد onclick

از این attribute روی عناصر قابل کلیک (مانند دکمه‌ها یا لینک‌ها) برای راه‌اندازی درخواست‌های AJAX استفاده کنید:

<button 
    data-jsc="ajax-request" 
    data-url="/api/like-post/123" 
    data-method="POST"
>
    پسندیدن
</button>

این کار:

• از عمل پیش‌فرض کلیک جلوگیری می‌کند
• درخواست AJAX به URL مشخص شده با متد مشخص شده ارسال می‌کند
• پاسخ را به طور مناسب مدیریت می‌کند

Attribute های اضافی

می‌توانید از data attribute های اضافی برای سفارشی‌سازی رفتار استفاده کنید:

• data-confirm="آیا مطمئن هستید؟" - نمایش دیالوگ تأیید قبل از ادامه
• data-method="PUT" - مشخص کردن متد HTTP (پیش‌فرض GET برای لینک‌ها، متد فرم برای فرم‌ها)
• data-redirect="/success-page" - هدایت به URL مشخص پس از ارسال موفق
• data-target="#result-container" - به‌روزرسانی عنصر مشخص با پاسخ

نکته:

هنگام پیاده‌سازی این رفتارها، اطمینان حاصل کنید که:

• تمام درخواست‌های AJAX شامل توکن‌های CSRF برای Laravel هستند
• پاسخ‌های خطا به درستی مدیریت و به کاربر نمایش داده می‌شوند
• وضعیت‌های بارگذاری برای ارائه بازخورد در طول درخواست‌ها نشان داده می‌شوند
• پیام‌های موفقیت و خطا به طور مناسب نمایش داده می‌شوند

کامپوننت‌های Vue.js

برای عناصر تعاملی پیچیده‌تر، از کامپوننت‌های Vue.js استفاده می‌کنیم. هنگام ایجاد کامپوننت‌های Vue:

1. از کامپوننت‌های تک فایل (.vue files) استفاده کنید
2. از راهنمای سبک Vue.js پیروی کنید
3. از props برای انتقال داده به کامپوننت‌ها استفاده کنید
4. برای ارتباط با کامپوننت‌های والد، رویدادها emit کنید
5. در صورت مناسب بودن، از Vuex برای مدیریت state استفاده کنید

مثال کامپوننت Vue:

<template>
  <div class="user-card">
    <h3>{{ user.name }}</h3>
    <p>{{ user.email }}</p>
    <button @click="$emit('edit', user.id)">ویرایش</button>
  </div>
</template>

<script>
export default {
  name: 'UserCard',
  props: {
    user: {
      type: Object,
      required: true
    }
  }
}
</script>

<style scoped>
.user-card {
  padding: 1rem;
  border: 1px solid #ccc;
  border-radius: 4px;
}
</style>

بهترین شیوه‌های JavaScript

1. در صورت امکان از ویژگی‌های ES6+ استفاده کنید
2. از متغیرهای سراسری اجتناب کنید
3. به جای var از const و let استفاده کنید
4. برای callback ها از arrow function ها استفاده کنید
5. برای عملیات ناهمزمان از async/await استفاده کنید
6. مدیریت خطای مناسب برای تمام عملیات ناهمزمان اضافه کنید
7. برای کد تمیزتر از destructuring استفاده کنید
8. منطق پیچیده را کامنت کنید
9. از نام‌های معنادار برای متغیرها و توابع استفاده کنید
10. توابع را کوچک و متمرکز بر یک مسئولیت نگه دارید