jQuery ajax - روش ajax()

دستورالعمل jQuery Ajax

مثال

با استفاده از AJAX یک متن را بارگذاری کنید:

کد jQuery:}

$(document).ready(function(){
  $("#b01").click(function(){
  htmlobj=$.ajax({url:"/jquery/test1.txt",async:false});
  $("#myDiv").html(htmlobj.responseText);
  });
});

کد HTML:

<div id="myDiv"><h2>با استفاده از AJAX این متن را تغییر دهید</h2></div>
<button id="b01" type="button">تغییر محتوا</button>

آزمایش کنید

تعریف و استفاده

مетод ajax() داده‌های دور را از طریق درخواست‌های HTTP بارگذاری می‌کند.

این روش پیاده‌سازی پایه‌ای jQuery برای AJAX است. پیاده‌سازی‌های ساده‌تر و قابل استفاده‌تر در $.get، $.post و غیره وجود دارند. تابع $.ajax() شیء XMLHttpRequest ایجاد شده توسط خودش را برمی‌گرداند. در بیشتر موارد، شما نیازی به عمل مستقیم با این تابع ندارید، مگر اینکه نیاز به دسترسی به گزینه‌های غیرمعمول داشته باشید تا بیشتر انعطاف‌پذیری داشته باشید.

در ساده‌ترین حالت، $.ajax() می‌تواند بدون هیچ پارامتری مستقیماً استفاده شود.

توجه داشته باشید:همه گزینه‌ها می‌توانند از طریق تابع $.ajaxSetup() به صورت جهانی تنظیم شوند.

قوانین دستور زبان

jQuery.ajax([settings])
پارامترها توضیحات
settings

اختیاری. مجموعه‌ای از کلید-مقدار برای پیکربندی درخواست Ajax.

می‌توان با استفاده از $.ajaxSetup() هر گزینه‌ای را به عنوان مقدار پیش‌فرض تنظیم کرد.

پارامترها

options

نوع: Object

اختیاری. تنظیمات درخواست Ajax. همه گزینه‌ها اختیاری هستند.

async

نوع: Boolean

مقدار پیش‌فرض: true. در تنظیمات پیش‌فرض، همه درخواست‌ها به صورت غیرهمزمان هستند. اگر نیاز به ارسال درخواست همزمان دارید، این گزینه را به false تنظیم کنید.

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

beforeSend(XHR)

نوع: Function

قبل از ارسال درخواست می‌توانند تابع‌هایی برای تغییر شیء XMLHttpRequest استفاده شوند، مانند اضافه کردن سربرگ‌های HTTP سفارشی.

شیء XMLHttpRequest تنها پارامتر است.

این یک رویداد Ajax است. اگر return false شود، می‌توان از این درخواست Ajax جلوگیری کرد.

cache

نوع: Boolean

مقدار پیش‌فرض: true،dataType به عنوان script و jsonp مقدار پیش‌فرض false است. تنظیم مقدار false این صفحه را به صورت غیرقابل ذخیره می‌کند.

نکات جدید jQuery 1.2

complete(XHR, TS)

نوع: Function

توابع بازگشت بعد از تکمیل درخواست (پس از موفقیت یا شکست درخواست فراخوانی می‌شوند).

پارامترها: شیء XMLHttpRequest و رشته‌ای که نوع درخواست را توصیف می‌کند.

این یک رویداد Ajax است.

contentType

نوع: String

مقدار پیش‌فرض: "application/x-www-form-urlencoded". نوع کدگذاری محتوای ارسالی به سرور هنگام ارسال اطلاعات.

مقدار پیش‌فرض مناسب بیشتر موارد است. اگر شما به صورت مستقیم یک content-type به $.ajax() ارسال کنید، آن به طور حتم به سرور ارسال خواهد شد (حتی اگر داده‌ای برای ارسال وجود نداشته باشد).

context

نوع: Object

این شیء برای تنظیم تابع‌های بازگشت Ajax استفاده می‌شود. به عبارت دیگر، این امکان را فراهم می‌کند که تابع بازگشت این شیء به این شیء اشاره کند (اگر این پارامتر تنظیم نشود، این شیء به پارامتر options که در زمان فراخوانی AJAX ارسال شده اشاره می‌کند). به عنوان مثال، اگر یک عنصر DOM به عنوان پارامتر context مشخص شود، اینگونه تنظیم می‌شود که تابع بازگشت success به این عنصر DOM اشاره کند.

مثل این:

$.ajax({ url: "test.html", context: document.body, success: function(){
        $(this).addClass("done");
      }});
data

نوع: String

داده‌هایی که به سرور ارسال می‌شوند. به صورت خودکار به فرمت رشته درخواست تبدیل می‌شود. در درخواست‌های GET به عنوان بخشی از URL اضافه می‌شود. برای جلوگیری از این تبدیل خودکار به دنبال توضیحات گزینه processData بگردید. باید به فرمت Key/Value باشد. اگر یک آرایه باشد، jQuery به طور خودکار نام مشابهی برای هر مقدار ایجاد می‌کند. به عنوان مثال، {foo: ["bar1", "bar2"]} به '&foo=bar1&foo=bar2' تبدیل می‌شود.

dataFilter

نوع: Function

تابعی است که داده‌های اصلی که از Ajax باز می‌گردد را پیش‌پردازش می‌کند. دو پارامتر data و type را ارائه می‌دهد: data داده‌های اصلی که از Ajax باز می‌گردد است و type پارامتر dataType که در زمان فراخوانی jQuery.ajax ارائه می‌شود است. مقدار بازگشتی این تابع توسط jQuery به طور بیشتر پردازش می‌شود.

dataType

نوع: String

توضیح نوع داده‌ای که سرور انتظار دارد. اگر مشخص نشود، jQuery به صورت خودکار بر اساس اطلاعات MIME HTTP بسته HTTP به طور هوشمندانه تشخیص می‌دهد، به عنوان مثال، نوع MIME XML به عنوان XML تشخیص داده می‌شود. در نسخه 1.4، JSON یک شیء JavaScript ایجاد می‌کند و script آن را اجرا می‌کند. سپس داده‌های سرور بر اساس این مقدار پردازش می‌شوند و به تابع بازگشت داده می‌شوند. مقادیر قابل استفاده:

  • "xml": مستند XML را بازمی‌گرداند، که می‌توان آن را با jQuery پردازش کرد.
  • "html": اطلاعات HTML ساده را بازمی‌گرداند؛ تگ‌های script در زمان وارد کردن به DOM اجرا می‌شوند.
  • "script": کد JavaScript ساده را بازمی‌گرداند. نتایج به طور خودکار ذخیره نمی‌شود. مگر اینکه پارامتر "cache" تنظیم شده باشد. توجه داشته باشید: در درخواست‌های از راه دور (در خارج از حوزه)، همه درخواست‌های POST به درخواست‌های GET تبدیل می‌شوند. (زیرا از تگ script DOM استفاده خواهد شد).
  • "json": داده‌های JSON را بازمی‌گرداند.
  • "jsonp": فرمت JSONP. در حالی که فرمت JSONP فراخوانی می‌شود، به عنوان مثال "myurl?callback=?"، jQuery به طور خودکار ? را با نام صحیح کاربرگزار جایگزین می‌کند تا کاربرگزار فراخوانی شود.
  • "text": رشته متن ساده را بازمی‌گرداند
error

نوع: Function

مقدار پیش‌فرض: خودکار تشخیص (xml یا html). این تابع در صورت عدم موفقیت در درخواست فراخوانی می‌شود.

این سه پارامتر وجود دارد: شی XMLHttpRequest، اطلاعات خطا، (اختیاری) شی مورد استفاده برای استثنا.

در صورت بروز خطا، اطلاعات خطا (دومین پارامتر) علاوه بر null می‌تواند "timeout", "error", "notmodified" و "parsererror" باشد.

این یک رویداد Ajax است.

global

نوع: Boolean

آیا باید رویدادهای AJAX جهانی را تحریک کنید. مقدار پیش‌فرض: true. تنظیم به false باعث می‌شود که رویدادهای AJAX جهانی مانند ajaxStart یا ajaxStop تحریک نشوند، که می‌توانند برای کنترل رویدادهای مختلف Ajax استفاده شوند.

ifModified

نوع: Boolean

تنها در صورت تغییر داده شدن داده‌های سرور، داده‌های جدید را دریافت کنید. مقدار پیش‌فرض: false. از سرور Last-Modified سربرگ HTTP برای تشخیص تغییر داده شدن داده‌ها استفاده می‌شود. در jQuery 1.4، همچنین بررسی می‌کند که سرور "etag" مشخص شده‌است تا اطمینان حاصل شود داده‌ها تغییر نکرده‌اند.

jsonp

نوع: String

نام کاربرگزار در درخواست jsonp بازنویسی شود. این مقدار برای جایگزینی بخش "callback" در URL پارامترهای درخواست GET یا POST مانند "callback=?" استفاده می‌شود، به عنوان مثال {jsonp:'onJsonPLoad'} باعث می‌شود که "onJsonPLoad=?" به سرور ارسال شود.

jsonpCallback

نوع: String

برای درخواست‌های jsonp یک نام تابع بازگشتی مشخص کنید. این مقدار برای جایگزینی نام تابع تصادفی خودکار jQuery استفاده می‌شود. این کار برای ایجاد نام‌های تابع منحصر به فرد انجام می‌شود تا مدیریت درخواست‌ها آسان‌تر شود و همچنین برای ارائه تابع بازگشتی و مدیریت خطاها استفاده می‌شود. همچنین می‌توانید این نام تابع بازگشتی را برای بازگرداندن درخواست‌های GET به صورت cache توسط مرورگر مشخص کنید.

password

نوع: String

برای پاسخ به درخواست‌های احراز هویت HTTP استفاده می‌شود.

processData

نوع: Boolean

مقدار پیش‌فرض: true. به طور پیش‌فرض، داده‌هایی که از طریق گزینه data ارسال می‌شوند و اگر یک شیء هستند (技术上 غیر از رشته)، به یک رشته کوچک تبدیل می‌شوند تا با نوع محتوای پیش‌فرض "application/x-www-form-urlencoded" هماهنگ شوند. برای ارسال اطلاعات درخت DOM یا اطلاعات دیگری که نمی‌خواهید تبدیل شوند، آن را به false تنظیم کنید.

scriptCharset

نوع: String

تنها زمانی که dataType درخواست "jsonp" یا "script" باشد و type "GET" باشد، برای تغییر ق强制性 charset استفاده می‌شود. معمولاً تنها در مواردی که کدگذاری محلی و دور از دسترس متفاوت است استفاده می‌شود.

success

نوع: Function

تابع بازگشتی پس از موفقیت درخواست.

پارامترها: داده‌هایی که توسط سرور بازگردانده می‌شوند و بر اساس پارامتر dataType پردازش می‌شوند؛ توصیف وضعیت.

این یک رویداد Ajax است.

traditional

نوع: Boolean

اگر می‌خواهید به روش سنتی داده‌ها را سریال‌سازی کنید، آن را به true تنظیم کنید. لطفاً به روش‌های موجود در دسته‌بندی ابزارهای jQuery مراجعه کنید.

timeout

نوع: Number

زمان انتظار درخواست را (در میلی‌ثانیه) تنظیم می‌کند. این تنظیمات پارامترهای تنظیم شده جهانی را پوشش می‌دهد.

type

نوع: String

مقدار پیش‌فرض: "GET"). روش درخواست ("POST" یا "GET")، به طور پیش‌فرض "GET" است. توجه: روش‌های دیگر HTTP درخواست مانند PUT و DELETE نیز می‌توانند استفاده شوند، اما تنها در برخی مرورگرها پشتیبانی می‌شوند.

url

نوع: String

مقدار پیش‌فرض: آدرس صفحه فعلی. آدرس ارسال درخواست.

username

نوع: String

برای پاسخ به درخواست‌های احراز هویت HTTP استفاده می‌شود.

xhr

نوع: Function

باید یک شیء XMLHttpRequest برگردانده شود. به طور پیش‌فرض در IE ActiveXObject است و در سایر موارد XMLHttpRequest است. برای نوشتن یا ارائه یک شیء XMLHttpRequest بهبود یافته استفاده می‌شود. این پارامتر در jQuery 1.3 قبل از آن موجود نبود.

تابع‌های callback

برای پردازش داده‌هایی که از $.ajax() دریافت می‌شود، باید از تابع‌های callback استفاده کرد: beforeSend، error، dataFilter، success، complete.

beforeSend

قبل از ارسال درخواست فراخوانی می‌شود و XMLHttpRequest را به عنوان پارامتر ورودی انتقال می‌دهد.

error

در صورت بروز خطا در درخواست فراخوانی می‌شود. XMLHttpRequest، یک رشته توصیف‌کننده نوع خطا و یک شیء استثنا (در صورت وجود) را به عنوان پارامتر ورودی انتقال می‌دهد.

dataFilter

پس از موفقیت در درخواست فراخوانی می‌شود. داده‌های بازگردانده و مقدار پارامتر dataType را به عنوان پارامتر ورودی انتقال می‌دهد. و باید داده‌های جدید (پس از پردازش ممکن است) را به تابع success callback انتقال دهد.

success

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

complete

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

نوع داده

تابع $.ajax() از اطلاعات ارائه شده توسط سرور برای پردازش داده‌های بازگردانده وابسته است. اگر سرور گزارش دهد که داده‌های بازگردانده XML هستند، نتایج می‌توانند با استفاده از روش‌های XML معمول یا انتخابگرهای jQuery بررسی شوند. اگر نوع دیگری مانند HTML قابل مشاهده باشد، داده‌ها به عنوان متن در نظر گرفته می‌شوند.

از طریق گزینه dataType می‌توان نوع‌های مختلف پردازش داده را مشخص کرد. علاوه بر XML ساده، می‌توان html، json، jsonp، script یا text را نیز مشخص کرد.

در اینجا، داده‌های نوع text و xml بدون پردازش بازگردانده می‌شوند. داده‌ها به سادگی به عنوان responseText یا responseHTML XMLHttpRequest به تابع success callback منتقل می‌شوند.

توجه داشته باشید:ما باید اطمینان حاصل کنیم که نوع MIME گزارش شده توسط سرور وب با dataType انتخابی ما مطابقت دارد. به عنوان مثال، اگر XML باشد، سرور باید text/xml یا application/xml را برای دستیابی به نتایج مشابه اعلام کند.

اگر نوع html مشخص شود، هر JavaScript داخلی قبل از اینکه HTML به عنوان یک رشته بازگردانده شود، اجرا خواهد شد. به همین ترتیب، اگر نوع script مشخص شود، ابتدا JavaScript تولید شده توسط سرور اجرا خواهد شد و سپس به عنوان داده‌های متن بازگردانده می‌شود.

اگر مشخص شود که نوع json است، داده‌های دریافت شده به عنوان یک شیء JavaScript تحلیل خواهند شد و شیء ساخته شده به عنوان نتیجه بازگردانده می‌شود. برای دستیابی به این هدف، ابتدا تلاش می‌کند تا از JSON.parse() استفاده کند. اگر مرورگر پشتیبانی نمی‌کند، از یک تابع برای ساخت استفاده می‌شود.

داده‌های JSON یک داده‌های ساختاریافته هستند که می‌توانند به راحتی توسط JavaScript تحلیل شوند. اگر فایل داده در سرور‌های دوردست قرار دارد (یعنی از سرور‌های متفاوت، یعنی دریافت داده از سرور‌های متفاوت)، باید از نوع jsonp استفاده کرد. با استفاده از این نوع، یک پارامتر توالی جستجو callback=? ایجاد می‌شود که به URL درخواست اضافه می‌شود. سرور باید نام پیام‌رسان را قبل از داده‌های JSON اضافه کند تا درخواست JSONP معتبر باشد. برای تعیین نام پارامتر پیام‌رسان به جای callback پیش‌فرض، می‌توان پارامتر jsonp در $.ajax() را تنظیم کرد.

توجه داشته باشید:JSONP یک گسترش از فرمت JSON است. این نیاز به کد‌های سرور دارد تا پارامترهای توالی جستجو را شناسایی و پردازش کند.

اگر نوع script یا jsonp مشخص شده باشد، هنگام دریافت داده از سرور، در واقع از برچسب <script> استفاده می‌شود و نه شیء XMLHttpRequest. در این حالت، $.ajax() دیگر یک شیء XMLHttpRequest را بازمی‌گرداند و也不会 هیچ رویداد پردازش‌کننده‌ای مانند beforeSend را منتقل کند.

ارسال داده به سرور

به صورت پیش‌فرض، درخواست‌های Ajax از روش GET استفاده می‌کنند. برای استفاده از روش POST، می‌توان مقدار پارامتر type را تنظیم کرد. این گزینه همچنین بر نحوه ارسال محتوای گزینه data به سرور تأثیر می‌گذارد.

گزینه data می‌تواند شامل یک توالی از جستجو باشد، مانند key1=value1&key2=value2، یا می‌تواند یک نقشه باشد، مانند {key1: 'value1', key2: 'value2'}. اگر از شکل دوم استفاده شود، داده‌ها در فرستنده به یک توالی از جستجو تبدیل خواهند شد. این فرآیند می‌تواند با تنظیم گزینه processData به false جلوگیری شود. اگر بخواهیم یک شیء XML را به سرور ارسال کنیم، این پردازش ممکن است مناسب نباشد. و در این حالت نیز باید مقدار گزینه contentType را تغییر دهیم، تا جایگزین MIME مناسب‌تری از application/x-www-form-urlencoded استفاده شود.

گزینه‌های پیشرفته

گزینه global برای جلوگیری از ثبت کاربردهای بازخورد درخواست‌ها، مانند .ajaxSend، یا ajaxError و روش‌های مشابه استفاده می‌شود. این کار در برخی مواقع مفید است، مانند زمانی که درخواست‌ها بسیار زیاد و کوتاه هستند، می‌توان این کار را در ajaxSend غیرفعال کرد.

اگر سرور نیاز به تأیید هویت HTTP دارد، می‌توان از نام کاربری و رمز عبور از طریق گزینه‌های username و password استفاده کرد.

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

به صورت پیش‌فرض، درخواست همیشه ارسال می‌شود، اما مرورگر ممکن است داده‌ها را از حافظه پنهان خود بازیابی کند. برای جلوگیری از استفاده از نتایج حافظه پنهان، می‌توان پارامتر cache را به false تنظیم کرد. اگر می‌خواهید در صورت تغییر نداشتن داده‌ها از آخرین درخواست، خطایی گزارش شود، می‌توان پارامتر ifModified را به true تنظیم کرد.

scriptCharset اجازه می‌دهد تا یک مجموعه کاراکتر خاص برای درخواست‌های <script> تنظیم شود، که برای داده‌های script یا jsonp استفاده می‌شود. زمانی که مجموعه کاراکتر اسکریپت با مجموعه کاراکتر صفحه متفاوت باشد، این بسیار مفید است.

حرف اول Ajax حرف اول کلمه asynchronous است، که به این معناست که همه عملیات‌ها به صورت موازی هستند و ترتیب انجام آن‌ها هیچ اهمیتی ندارد. پارامتر async توابع $.ajax() همیشه به true تنظیم می‌شود، که نشان‌دهنده این است که پس از شروع درخواست، کد دیگر نیز می‌تواند اجرا شود. این گزینه به هیچ وجه توصیه نمی‌شود که به false تنظیم شود، زیرا این کار باعث می‌شود که همه درخواست‌ها دیگر غیرمستقل نباشند و این می‌تواند منجر به قفل شدن مرورگر شود.

توابع $.ajax یک شیء XMLHttpRequest ایجاد شده توسط خود را بازمی‌گرداند. معمولاً jQuery این شیء را به صورت داخلی پردازش کرده و ایجاد می‌کند، اما کاربران نیز می‌توانند یک شیء xhr خودساخته را از طریق گزینه xhr ارسال کنند. شیء بازگردانده شده معمولاً به دور انداخته می‌شود، اما یک رابط پایه‌ای برای مشاهده و کنترل درخواست ارائه می‌دهد. به عنوان مثال، فراخوانی .abort() روی شیء می‌تواند درخواست را قبل از تکمیل آن متوقف کند.

دستورالعمل jQuery Ajax