متد $.getJSON

متد $.getJSON یکی از روش های ساده جی کوئری برای ارسال درخواست HTTP از نوع GET و دریافت پاسخ JSON است. پس از دریافت پاسخ، جی کوئری داده را به شکل قابل استفاده در اختیار تابع موفقیت قرار می دهد؛ بنابراین در حالت معمول نیازی نیست رشته JSON را به صورت دستی تجزیه کنید.

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

در بسیاری از پروژه های جدید، توسعه دهندگان از Fetch API یا ابزارهای دیگر جاوااسکریپت استفاده می کنند؛ با این حال، اگر پروژه از جی کوئری بهره می برد، آشنایی با متد $.getJSON کمک می کند کدهای موجود را بهتر بخوانید و نگهداری کنید.

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

برای مثال، اگر اطلاعات کالاها در مسیر /api/products ارائه می شود، درخواست را می توان به این مسیر فرستاد. پیش از استفاده، مسیر را در ابزارهای توسعه مرورگر بررسی کنید تا از درست بودن آن و دریافت پاسخ مورد انتظار مطمئن شوید.

$.getJSON('/api/products', function(data) {
  console.log(data);
});

تابع موفقیت، داده دریافتی را در پارامتر خود می گیرد. اینکه چگونه به مقادیر دسترسی پیدا می کنید به ساختار پاسخ وابسته است: پاسخ ممکن است یک آرایه باشد، یک شیء ساده باشد یا شیئی داشته باشد که آرایه ای از نتایج را در یکی از ویژگی هایش نگه می دارد.

فرض کنید سرور چنین پاسخی می فرستد: { "items": [{ "name": "Book" }] }. در این حالت، برای رسیدن به نام نخستین مورد باید از مسیر data.items[0].name استفاده کنید. ابتدا پاسخ واقعی را در کنسول ببینید و سپس کد را با همان ساختار هماهنگ کنید.

$.getJSON('/api/products', function(data) {
  data.items.forEach(function(item) {
    console.log(item.name);
  });
});

داده ای که از سرور می آید را نباید بدون توجه به نوع آن مستقیما به عنوان HTML در صفحه قرار داد. اگر مقدار دریافتی متن است، استفاده از .text() برای قرار دادن آن در عنصر صفحه انتخاب مطمئن تری است؛ زیرا مرورگر آن را متن در نظر می گیرد، نه کد قابل اجرا.

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

$.getJSON('/api/products', function(data) {
  $('#product-name').text(data.name);
});

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

با افزودن .fail() می توانید برای وضعیت ناموفق پیام مناسبی نمایش دهید یا جزئیات را برای بررسی در کنسول ثبت کنید. پیام کاربر بهتر است ساده باشد و اطلاعات فنی حساس را در رابط عمومی نمایش ندهد.

$.getJSON('/api/products')
  .done(function(data) {
    console.log(data);
  })
  .fail(function() {
    $('#message').text('دریافت اطلاعات انجام نشد.');
  });

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

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

$.getJSON('/api/search', { q: 'jquery' }, function(data) {
  console.log(data);
});

ساختار پایه متد $.getJSON شامل نشانی درخواست، داده های اختیاری و تابعی برای پردازش پاسخ است. شکل خلاصه آن را در نمونه زیر می بینید. اگر داده ای برای ارسال ندارید، می توانید آرگومان داده را حذف کنید.

$.getJSON(url, data, success);

در این ساختار، url نشانی منبع، data پارامترهای اختیاری درخواست و success تابعی است که پس از دریافت موفق پاسخ اجرا می شود. تابع موفقیت معمولا داده را به عنوان آرگومان نخست دریافت می کند؛ آرگومان های دیگر نیز می توانند اطلاعاتی مانند وضعیت درخواست یا شیء درخواست را در اختیار شما بگذارند.

در نسخه های رایج جی کوئری، نتیجه متد یک شیء درخواست قابل زنجیره سازی است. این ویژگی اجازه می دهد مدیریت موفقیت و خطا را به جای تکیه بر آرگومان های جداگانه، با متدهایی مانند .done() و .fail() بنویسید. برای پروژه خود، نسخه جی کوئری و شیوه های سازگار با آن را بررسی کنید.

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

در کنار آن، استفاده موقت از console.log(data) کمک می کند ساختار واقعی پاسخ را ببینید. پس از پایان بررسی، گزارش های غیرضروری را حذف کنید یا آن ها را به سازوکار ثبت رویدادهای مناسب پروژه منتقل کنید.

اگر درخواست از صفحه ای به دامنه یا مبدأ دیگری فرستاده می شود، محدودیت های امنیتی مرورگر و تنظیمات دسترسی بین مبدأها می توانند بر نتیجه اثر بگذارند. در این شرایط، تنها تغییر کد سمت مرورگر کافی نیست و تنظیمات سرور نیز باید اجازه دسترسی لازم را فراهم کند.

در محیط توسعه، مسیر نسبی ممکن است با مسیر صفحه تغییر کند؛ به همین دلیل مسیر API را با دقت انتخاب کنید. در محیط انتشار هم نشانی ها، پروتکل امن و دسترسی کاربر به منبع را دوباره بررسی کنید.

درخواست شبکه ممکن است فوری پاسخ ندهد. نمایش یک پیام کوتاه در زمان بارگذاری، به کاربر نشان می دهد که برنامه در حال انجام کار است. پس از دریافت پاسخ، پیام را بردارید و محتوای تازه را جایگزین کنید.

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

متد $.getJSON برای سناریوی مشخصی ساخته شده است: ارسال درخواست GET و انتظار پاسخ JSON. این سادگی می تواند کد را خواناتر کند، به خصوص وقتی هدف فقط دریافت داده است. در مقابل، متد عمومی $.ajax() گزینه های بیشتری برای تنظیم نوع درخواست، هدرها، زمان انتظار و قالب داده در اختیار می گذارد.

اگر پروژه شما از جی کوئری استفاده می کند و به تنظیمات ویژه نیاز ندارید، $.getJSON() راه مستقیمی برای دریافت داده است. وقتی کنترل بیشتری لازم دارید، $.ajax() انتخاب انعطاف پذیرتری خواهد بود. در پروژه های بدون جی کوئری نیز می توانید از Fetch API استفاده کنید تا وابستگی تازه ای اضافه نشود.

متد $.getJSON راهی سرراست برای دریافت داده های JSON از سرور در پروژه های مبتنی بر جی کوئری است. با مشخص کردن مسیر درست، شناخت ساختار پاسخ و مدیریت حالت های موفق و ناموفق، می توانید از آن برای بارگذاری اطلاعات و به روزرسانی بخش هایی از صفحه استفاده کنید.

در پیاده سازی نهایی، پاسخ را در ابزارهای توسعه بررسی کنید، داده های متنی را به شکل امن نمایش دهید و برای وضعیت بارگذاری یا نتیجه خالی پیام مناسب در نظر بگیرید. اگر به تنظیمات گسترده تر نیاز دارید، روش هایی مانند $.ajax() یا Fetch API را نیز با نیاز پروژه مقایسه کنید.