متد $.param

متد $.param در jQuery یک شیء یا آرایه را به رشته ای از جفت های نام و مقدار تبدیل می کند؛ رشته ای که معمولا برای ساخت پارامترهای یک نشانی اینترنتی یا ارسال داده در درخواست های وب به کار می رود. هر جفت با علامت مساوی از هم جدا می شود و جفت های مختلف با علامت & کنار هم قرار می گیرند.

برای نمونه، اگر شیئی شامل سه ویژگی با نام های prop1، prop2 و prop3 داشته باشیم، خروجی آن می تواند به شکل زیر باشد. توجه کنید که متد برای ایمن ماندن داده در URL، بعضی نویسه ها را نیز به صورت رمزگذاری شده نمایش می دهد.

prop1=value1&prop2=value2&prop3=value3

این رشته می تواند در بخش query نشانی صفحه قرار بگیرد یا به عنوان داده در درخواست Ajax ارسال شود. بنابراین، $.param رابطی بین داده های ساختارمند جاوااسکریپت و قالب متنی مورد نیاز برای انتقال در وب فراهم می کند؛ اما خودش درخواست ارسال نمی کند و فقط داده را آماده می سازد.

پارامتر اصلی $.param داده ای است که می خواهید به رشته تبدیل کنید. در ساده ترین حالت، این داده یک شیء جاوااسکریپت با چند ویژگی و مقدار است. نام هر ویژگی به نام پارامتر و مقدار آن به مقدار پارامتر تبدیل می شود.

برای مثال، اطلاعات یک فرم جست وجو را می توان در شیئی مانند queryData نگه داشت و سپس آن را به $.param داد. اگر داده از قبل به صورت رشته ای آماده شده باشد، دیگر نیازی به تبدیل دوباره آن نیست. انتخاب ورودی روشن و ساده، خوانایی کد و عیب یابی درخواست را آسان تر می کند.

const queryData = {
  term: "طراحی سایت",
  page: 2
};

const queryString = $.param(queryData);

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

ساختار معمول خروجی شامل جفت هایی مانند name=value است. اگر چند ویژگی در شیء وجود داشته باشد، متد آن ها را با علامت & از یکدیگر جدا می کند. این همان قالب متداولی است که مرورگرها و سرورها برای پارامترهای URL می شناسند.

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

const filters = {
  category: "books",
  page: 2
};

const query = $.param(filters);
// category=books&page=2

اگر مقدارها شامل فاصله یا نویسه های ویژه باشند، شکل نهایی خروجی ممکن است با متن خام تفاوت داشته باشد؛ این رفتار برای سازگاری با قواعد انتقال URL است. از این رو، بهتر است خروجی را با هدف خواندن انسانی قضاوت نکنید و آن را داده ای رمزگذاری شده برای انتقال در نظر بگیرید.

در برنامه های واقعی، داده همیشه به چند ویژگی ساده محدود نیست. ممکن است یک شیء شامل شیء دیگری باشد یا مقداری از نوع آرایه داشته باشد. در این شرایط، قالب بندی پارامترهای تو در تو به تنظیم سنتی سازی وابسته است و می تواند بر نام هایی که سرور دریافت می کند اثر بگذارد.

برای نمونه، یک فهرست از برچسب ها ممکن است به صورت چند کلید هم نام یا به شکل کلیدی با نشانه های براکت نمایش داده شود. هیچ یک از این قالب ها برای همه پروژه ها برتر نیست؛ مهم این است که قالب تولیدشده با چارچوب، زبان سمت سرور و قرارداد API شما هماهنگ باشد.

const requestData = {
  user: {
    name: "Sara"
  },
  tags: ["jquery", "web"]
};

const query = $.param(requestData);

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

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

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

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

یکی از برداشت های نادرست این است که اجرای $.param به تنهایی اطلاعات را به سرور می فرستد. در عمل، این متد فقط رشته پارامترها را می سازد. برای ارسال داده باید از سازوکاری مانند $.ajax استفاده کنید یا رشته را در نشانی مورد نظر قرار دهید.

برای نمونه، می توانید رشته ساخته شده را به عنوان داده درخواست GET به کار ببرید. در این حالت، مسئولیت ارسال، مدیریت پاسخ و رسیدگی به خطا بر عهده تابع درخواست است، نه $.param. جدا نگه داشتن این دو مسئولیت باعث می شود کد ساده تر و قابل نگهداری تر باشد.

const data = {
  category: "books",
  page: 2
};

$.ajax({
  url: "/search",
  method: "GET",
  data: data
});

در بسیاری از موارد، کتابخانه درخواست می تواند شیء داده را خودش به قالب مناسب تبدیل کند. اگر پیش از ارسال به رشته نهایی نیاز دارید، $.param انتخاب مناسبی است؛ با این حال، مطمئن شوید که داده را دوبار سریال سازی نمی کنید.

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

$.param(object);

در کد قدیمی تر ممکن است با متغیری به نام obj روبه رو شوید. این نام فقط یک نام قراردادی برای پارامتر است و می توانید به جای آن نامی معنادار مانند formData، filters یا requestData انتخاب کنید. نام گذاری روشن کمک می کند نقش داده در کد مشخص باشد.

در مثال زیر، کلیک روی دکمه باعث می شود رشته حاصل از تبدیل در یک عنصر div نمایش داده شود. فرض شده است که متغیر personObj پیش از اجرای این کد تعریف شده و حاوی اطلاعات مورد نظر است.

const personObj = {
  name: "Sara",
  city: "Tehran"
};

$("button").click(function() {
  $("div").text($.param(personObj));
});

استفاده از text برای نمایش خروجی در صفحه، از تفسیر ناخواسته آن به عنوان HTML جلوگیری می کند. برای آزمایش بهتر، یک عنصر مشخص برای نمایش نتیجه در نظر بگیرید تا انتخابگر عمومی div محتوای سایر بخش های صفحه را تغییر ندهد.

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

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

ساخت دستی query string ممکن است با مقدارهایی دارای فاصله، حروف فارسی یا نویسه های ویژه مشکل پیدا کند. استفاده از متد، آماده سازی این مقدارها را به روشی استانداردتر انجام می دهد و احتمال اشتباه در جدا کردن نام پارامتر از مقدار آن را کمتر می کند.

این مزیت به معنای بی نیازی از آزمون نیست. باید بررسی کنید که سرور همان داده و ساختاری را دریافت می کند که انتظار دارید؛ به خصوص وقتی مقدارها شامل آرایه، شیء تو در تو یا داده های واردشده توسط کاربر هستند.

در پروژه هایی که داده های فرم ابتدا به یک شیء تبدیل می شوند، $.param می تواند مرحله سریال سازی را روشن و قابل پیگیری کند. جدا بودن داده از رشته نهایی، بررسی مقدارها پیش از ارسال را آسان تر می سازد.

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

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

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

پارامترهای موجود در URL می توانند وضعیت یک صفحه را بازتاب دهند؛ برای مثال، عبارت جست وجو یا فیلتر انتخاب شده. آماده کردن این پارامترها با $.param، ساخت یک query منظم را ساده می کند و کاربر می تواند نشانی شامل وضعیت مورد نظر را باز کند یا با دیگران به اشتراک بگذارد.

البته اطلاعات حساس نباید در URL قرار بگیرند؛ نشانی ها ممکن است در تاریخچه مرورگر، گزارش سرور یا ابزارهای تحلیلی ثبت شوند. برای داده های حساس باید روش انتقال و سطح دسترسی مناسب را با توجه به نیاز برنامه انتخاب کنید.

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

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

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

همچنین رشته های query را به عنوان جایگزین اعتبارسنجی سمت سرور در نظر نگیرید. هر داده ای که از مرورگر می رسد باید در سرور بررسی شود؛ حتی اگر در فرانت اند به شکل درست ساخته شده باشد.

$.param به تنهایی ارتباط شبکه ای برقرار نمی کند. اگر خروجی ساخته شود اما به درخواست یا URL اضافه نشود، داده ای به سرور نمی رسد. از طرف دیگر، برخی توابع ارسال درخواست می توانند شیء را مستقیما دریافت و سریال سازی کنند؛ در این شرایط تبدیل جداگانه ممکن است غیرضروری باشد.

انتخاب روش مناسب به API و نیاز پروژه بستگی دارد. کد را طوری بنویسید که مشخص باشد کدام بخش داده را آماده می کند و کدام بخش درخواست را ارسال می کند. این تفکیک، بررسی خطا و تغییر رفتار برنامه را آسان تر می سازد.

نمونه زیر شیئی شامل اطلاعات یک فرد را تعریف می کند. سپس با کلیک روی دکمه، $.param آن را به رشته تبدیل می کند و نتیجه را در عنصری با شناسه output نمایش می دهد. انتخاب یک شناسه مشخص، از تغییر ناخواسته سایر divهای صفحه جلوگیری می کند.

const personObj = {
  name: "Sara",
  city: "Tehran"
};

$("button").click(function() {
  $("#output").text($.param(personObj));
});

برای اجرای نمونه، مطمئن شوید کتابخانه jQuery در صفحه بارگذاری شده و عناصر مورد استفاده در DOM وجود دارند. اگر کد پیش از ساخته شدن دکمه اجرا شود، رویداد کلیک به آن متصل نخواهد شد. در چنین شرایطی، زمان اجرای اسکریپت یا شیوه اتصال رویداد را بررسی کنید.

متد $.param در jQuery راهی ساده برای تبدیل شیء یا آرایه به رشته ای از پارامترهای مناسب URL است. این متد در آماده سازی داده های فرم، فیلترهای جست وجو و ساخت query string کاربرد دارد و مدیریت رمزگذاری مقدارها را آسان تر می کند.

برای استفاده درست، ورودی را با دقت انتخاب کنید، خروجی را با قرارداد سرور تطبیق دهید و به یاد داشته باشید که ساخت رشته با ارسال درخواست تفاوت دارد. اگر این نکته ها رعایت شوند، $.param می تواند کد را خواناتر کند و آماده سازی داده برای انتقال را قابل پیش بینی تر سازد.