گشودن Vue 3: راهنمای جامع API ترکیب

برای سال‌ها، API گزینه‌ای (Options API) روش استاندارد برای سازماندهی منطق در برنامه‌های Vue.js بود. اگرچه این روش برای کامپوننت‌های کوچک تا متوسط مؤثر بود، اما اغلب در پروژه‌های پیچیده منجر به «سوپی از گزینه‌ها» می‌شد—جایی که منطق مرتبط در ویژگی‌های data، methods و watchers پراکنده بود. با ورود API ترکیب (Composition API)، مجموعه‌ای از APIها معرفی شدند که به شما امکان می‌دهند کامپوننت‌های Vue را با استفاده از توابع وارد شده به جای اعلام گزینه‌ها، توسعه دهید.

در این پست، بررسی می‌کنیم که چرا API ترکیب برای برنامه‌های مقیاس‌پذیر تغییر بازی‌ساز است، چگونه می‌توان از اصول اولیه واکنش‌گرای آن استفاده کرد و مثال‌های کد عملی را برای کمک به تغییر گردش کار شما ارائه می‌دهیم.

چرا API ترکیب؟

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

علاوه بر این، API ترکیب بر پایه جاوااسکریپت استاندارد ساخته شده است. این روش پشتیبانی بهتری از استنتاج TypeScript ارائه می‌دهد و به توسعه‌دهندگان امکان می‌دهد منطق‌های قابل استفاده مجدد را در composableهای سفارشی استخراج کنند—که اساساً پاسخ Vue به React Hooks است، اما با ردیابی واکنش‌گرایی شهودی‌تر.

مفاهیم اصلی: Ref و Reactive

برای استفاده از API ترکیب، باید دو اصل اولیه واکنش‌گرایی آن را درک کنید: ref و reactive. اگرچه هر دو حالت را واکنش‌گرا می‌کنند، اما برای موارد استفاده متفاوتی طراحی شده‌اند.

ref برای نگهداری مقادیر اولیه (رشته‌ها، اعداد، بولین‌ها) یا اشیاء استفاده می‌شود. هنگامی که یک ref را در قالب (template) دسترسی می‌یابید، Vue به طور خودکار آن را باز می‌کند (unwrap). با این حال، در جاوااسکریپت، باید مقدار را از طریق ویژگی .value دسترسی پیدا کنید.

reactive یک پراکسی واکنش‌گرا از یک شیء ایجاد می‌کند. این روش برای ساختارهای داده پیچیده ایده‌آل است، اما نمی‌تواند مرجع شیء اصلی را جایگزین کند. معمولاً برای اشیاء و آرایه‌ها ترجیح داده می‌شود.

<script setup>
import { ref, reactive } from 'vue';

// استفاده از ref برای یک مقدار اولیه تک
const count = ref(0);

// استفاده از reactive برای یک شیء
const user = reactive({
  name: 'Alice',
  email: 'alice@example.com',
  role: 'developer'
});

function increment() {
  // دسترسی به .value برای تغییر ref
  count.value++;
}

function changeRole(newRole) {
  // دسترسی مستقیم برای اشیاء reactive
  user.role = newRole;
}
</script>

<template>
  <div>
    <p>شمارنده: {{ count }}</p>
    <p>نقش کاربر: {{ user.role }}</p>
    <button @click="increment">افزایش</button>
  </div>
</template>

Composableها: استخراج منطق

یکی از قدرتمندترین ویژگی‌های API ترکیب، امکان ایجاد composableها است. یک composable صرفاً یک تابع است که از APIهای ترکیب Vue برای بسته‌بندی و استفاده مجدد از منطق دارای حالت استفاده می‌کند. این امر معماری «یک نگرش در هر فایل» را ترویج می‌دهد.

برای مثال، به جای ترکیب منطق دریافت API درون کامپوننت خود، می‌توانید یک composable به نام useFetch ایجاد کنید.

useFetch.js
import { ref, onMounted } from 'vue';

export function useFetch(url) {
  const data = ref(null);
  const error = ref(null);
  const loading = ref(true);

  onMounted(async () => {
    try {
      const response = await fetch(url);
      if (!response.ok) throw new Error('پاسخ شبکه مطلوب نبود');
      data.value = await response.json();
    } catch (e) {
      error.value = e.message;
    } finally {
      loading.value = false;
    }
  });

  return { data, error, loading };
}

اکنون، در کامپوننت خود، می‌توانید به سادگی این منطق را وارد و استفاده کنید:

<script setup>
import { useFetch } from './useFetch';

const { data, error, loading } = useFetch('/api/users');
</script>

بهترین شیوه‌ها برای پذیرش

هنگام مهاجرت یا شروع پروژه‌های جدید، این بهترین شیوه‌ها را در نظر داشته باشید:

1. از <script setup> استفاده کنید: این ماکرو کامپایلر سینتکس مختصرتری برای استفاده از API ترکیب فراهم می‌کند و نیاز به بازگرداندن متغیرها از تابع setup را از بین می‌برد.
2. Composableها را متمرکز نگه دارید: هر composable باید یک مسئولیت واحد را مدیریت کند، مانند مدیریت حالت فرم، انجام تماس‌های API یا مدیریت رویدادهای کشیدن و رها کردن.
3. به صورت پیش‌فرض از Refها استفاده کنید: اگرچه reactive مفید است، اما refها انعطاف‌پذیرتر هستند زیرا می‌توانند کاملاً مجدداً اختصاص داده شوند. از reactive برای اشیاء پیچیده‌ای که در آن‌ها ویژگی‌ها را به صورت عمیق تغییر می‌دهید، استفاده کنید.

نتیجه‌گیری

API ترکیب Vue 3 تنها یک سینتکس جدید نیست؛ بلکه یک تغییر بنیادین در نحوه تفکر ما درباره معماری کامپوننت است. با امکان‌سازی سازماندهی بهتر کد، پشتیبانی تقویت‌شده از TypeScript و استفاده مجدد قدرتمند از منطق از طریق composableها، این API به توسعه‌دهندگان قدرت می‌دهد تا برنامه‌های مقیاس‌پذیر، قابل نگهداری و با عملکرد بالا بسازند.

چه در حال مهاجرت یک برنامه موجود Vue 2 باشید و چه از ابتدا با Vue 3 شروع کنید، تسلط بر API ترکیب یک گام ضروری در مسیر توسعه فرانت‌اند شماست. با بازسازی یک کامپوننت پیچیده در امروز شروع کنید و تفاوت را در وضوح و ساختار تجربه کنید.