XML DOM - شیء XMLHttpRequest

اشیاء XMLHttpRequest

شیء XMLHttpRequest دسترسی کامل به پروتکل HTTP را فراهم می‌کند، از جمله توانایی ایجاد درخواست‌های POST و HEAD و درخواست‌های معمول GET. XMLHttpRequest می‌تواند پاسخ سرور وب را به صورت همزمان یا غیرهمزمان بازگرداند و می‌تواند محتوای خود را به صورت متن یا یک مستند DOM بازگرداند.

با اینکه نام XMLHttpRequest دارد، اما محدود به استفاده با مستندات XML نیست: می‌تواند هر نوع مستند متنی را دریافت کند.

شیء XMLHttpRequest نام دارد AJAX یک ویژگی کلیدی از معماری برنامه‌های وب است.

پشتیبانی مرورگر

XMLHttpRequest یافته است که از همه مرورگرهای مدرن به خوبی پشتیبانی می‌شود. تنها وابستگی مرورگر به ایجاد شیء XMLHttpRequest است. در IE 5 و IE 6، باید از فرمول‌ساز ActiveXObject() خاص IE استفاده شود. همچنان که در اشیاء XMLHttpRequest این بخش معرفی شده است.

استاندارد W3C

شیء XMLHttpRequest هنوز استاندارد نشده است، اما W3C شروع به کار استانداردسازی کرده است، محتوای این راهنما بر اساس پیش‌نویس‌های استاندارد است.

تحقق فعلی XMLHttpRequest به طور قابل توجهی مشابه است. اما با استاندارد کمی متفاوت است. به عنوان مثال، یک تحقق ممکن است null را برمی‌گرداند، در حالی که استاندارد خواستار یک رشته خالی است، یا ممکن است readyState را به 3 تنظیم کند بدون این که اطمینان دهد که تمام سرتیترهای پاسخ در دسترس هستند.

ویژگی

readyState

وضعیت درخواست HTTP. وقتی XMLHttpRequest به طور اولیه ایجاد می‌شود، مقدار این ویژگی از 0 شروع می‌شود و تا دریافت کامل پاسخ HTTP کامل می‌شود، به 4 افزایش می‌یابد.

هر یک از 5 وضعیت دارای یک نام غیر رسمی مرتبطی دارند، جدول زیر وضعیت، نام و معنای آن‌ها را نشان می‌دهد:

وضعیت نام توضیح
0 Uninitialized وضعیت اولیه. شیء XMLHttpRequest ایجاد شده یا توسط روش abort() بازنشانی شده است.
1 Open روش open() فراخوانی شده است، اما روش send() فراخوانی نشده است. درخواست هنوز ارسال نشده است.
2 Sent روش Send() فراخوانی شده است، درخواست HTTP به سرور وب ارسال شده است. پاسخی دریافت نشده است.
3 Receiving تمام سرتیترهای پاسخ دریافت شده‌اند. بدنه پاسخ در حال دریافت است اما هنوز کامل نشده است.
4 Loaded پاسخ HTTP به طور کامل دریافت شده است.

مقدار readyState کاهش نمی‌یابد، مگر اینکه در حالی که درخواست در حال پردازش است، روش abort() یا open() فراخوانی شود. هر بار که مقدار این ویژگی افزایش می‌یابد، رویداد onreadystatechange فراخوانی می‌شود.

responseText

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

اگر readyState کمتر از 3 باشد، این ویژگی یک رشته خالی است. وقتی readyState برابر با 3 باشد، این ویژگی بخشی از پاسخ دریافت شده تا آن لحظه را برمی‌گرداند. اگر readyState برابر با 4 باشد، این ویژگی بدنه کامل پاسخ را ذخیره می‌کند.

اگر پاسخ شامل سرتیترهایی است که کد نگارش بدنه پاسخ را مشخص می‌کند، از آن کد استفاده می‌شود. در غیر این صورت، فرض بر این است که از Unicode UTF-8 استفاده می‌شود.

responseXML

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

status

که توسط سرور بازمی‌گردانده می‌شود کد وضعیت HTTP، مانند 200 که نشان‌دهنده موفقیت است و 404 که نشان‌دهنده خطای "Not Found" است. خواندن این ویژگی وقتی که readyState کمتر از 3 باشد، منجر به یک استثنا می‌شود.

statusText

این ویژگی با استفاده از نام به جای عدد سربرگ HTTP درخواست را مشخص می‌کند. به عنوان مثال، وقتی که وضعیت 200 است، "OK" است و وقتی که وضعیت 404 است، "Not Found" است. مانند ویژگی status، خواندن این ویژگی وقتی که readyState کمتر از 3 باشد، منجر به یک استثنا می‌شود.

وظیفه‌ی رویداد

onreadystatechange

وظیفه‌ای که هر بار که ویژگی readyState تغییر می‌کند، فراخوانی می‌شود. زمانی که readyState 3 باشد، ممکن است چندین بار فراخوانی شود.

روش

abort()

پاسخ فعلی را لغو کنید، ارتباط را ببندید و تمام فعالیت‌های شبکه‌ای در حال انجام را پایان دهید.

این روش XMLHttpRequest را به حالت readyState 0 بازمی‌گرداند و تمام فعالیت‌های شبکه‌ای در حال انجام را لغو می‌کند. به عنوان مثال، اگر درخواست مدت زیادی طول کشیده باشد و پاسخ دیگر ضروری نباشد، می‌توان این روش را فراخوانی کرد.

getAllResponseHeaders()

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

اگر readyState کمتر از 3 باشد، این روش null بازمی‌گرداند. در غیر این صورت، آن بازمی‌گرداند تمام سربرگ‌های HTTP پاسخ‌دهنده‌ای که توسط سرور ارسال شده‌اند. سربرگ‌ها به عنوان یک رشته واحد بازمی‌گردانند، یک سربرگ در هر سطر. هر سطر با استفاده از نشانه‌گذار ترمینال سطر "\r\n" جدا می‌شود.

getResponseHeader()

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

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

open()

پارامترهای درخواست HTTP را به عنوان مثال URL و روش HTTP، ابتداالیه‌سازی کنید، اما درخواست را ارسال نکنید.

send()

درخواست HTTP را ارسال کنید، از پارامترهایی که به روش open() ارسال شده‌اند، و بدنه درخواست اختیاری که به این روش ارسال شده است استفاده کنید.

setRequestHeader()

یک درخواست HTTP باز و ارسال نشده را تنظیم یا اضافه کنید.

XMLHttpRequest.open()

پارامترهای درخواست HTTP را به صورت اولیه تنظیم می‌کند

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

open(method, url, async, username, password)

پارامتر method روشی است که برای درخواست استفاده می‌شود. مقادیر شامل GET، POST و HEAD هستند.

پارامتر url محتوای درخواست است. بیشتر مرورگرها یک سیاست امنیتی همسان‌سری دارند و می‌خواهند که این URL با متنی که اسکریپت در آن قرار دارد دارای نام دامنه و پورت مشابهی باشد.

پارامتر async نشان‌دهنده این است که درخواست باید به صورت غیرمستقیم اجرا شود. اگر این پارامتر false باشد، درخواست مستقیم است و فراخوانی‌های بعدی به روش send() تا دریافت کامل پاسخ مسدود می‌شوند. اگر این پارامتر true باشد یا مشخص نشده باشد، درخواست غیرمستقیم است و معمولاً نیاز به یک دستگیره رویداد onreadystatechange دارد.

پارامترهای username و password انتخابی هستند و برای ارائه اعتبار برای اعطای دسترسی به url مورد نیاز هستند. اگر مشخص شدند، آن‌ها هرگونه اعطای دسترسی که url خود مشخص کرده است را برمی‌گردانند.

توضیح

این روش پارامترهای درخواست را برای استفاده در روش send() به صورت بعدی تنظیم می‌کند. آن را به حالت readyState 1 تنظیم می‌کند، تمامی سرخط‌های درخواست قبلی و سرخط‌های پاسخ قبلی را حذف می‌کند و پارامترهای responseText، responseXML، status و statusText را به مقادیر پیش‌فرض خود تنظیم می‌کند. این روش زمانی که readyState 0 باشد (وقتی XMLHttpRequest به تازگی ایجاد شده یا روش abort() فراخوانی شده است) و زمانی که readyState 4 باشد (وقتی پاسخ دریافت شده است)، امن است. هنگامی که برای هر حالت دیگری فراخوانی می‌شود، رفتار روش open() به صورت مشخص است.

علاوه بر ذخیره کردن پارامترهای درخواست برای استفاده در روش send() و بازپس‌گیری XMLHttpRequest برای استفاده مجدد، روش open() هیچ عمل دیگری ندارد. توجه داشته باشید که معمولاً هنگام فراخوانی این روش، اجرا معمولاً یک اتصال شبکه به سرور وب باز نمی‌کند.

XMLHttpRequest.send()

یک درخواست HTTP ارسال می‌کند

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

send(body)

اگر روشی که با فراخوانی open() تعیین شده است POST یا PUT باشد، بدنه پارامتر به عنوان یک رشته یا مستنداگر درخواست بدنه لازم نیست، این پارامتر null است. برای هر روش دیگری، این پارامتر غیرقابل استفاده است و باید null باشد (برخی از اجراها اجازه نمی‌دهند که این پارامتر حذف شود).

توضیح

این روش باعث ارسال یک درخواست HTTP می‌شود. اگر روش open() قبلاً فراخوانی نشده باشد، یا به عبارت دیگر، اگر حالت readyState برابر با 1 نباشد، روش send() یک استثنا پرتاب می‌کند. در غیر این صورت، آن یک درخواست HTTP ارسال می‌کند که از چندین بخش تشکیل شده است:

  • روش HTTP، URL و اعتبارنامه‌ای که در فراخوانی قبلی open() تعیین شده است (اگر وجود دارد).
  • سرصفحه درخواست که در فراخوانی قبلی setRequestHeader() تعیین شده است (اگر وجود دارد).
  • که به این روش ارسال می‌شود بدنه پارامترها.

بعد از اینکه درخواست منتشر شد، روش send() حالت readyState را به 2 تنظیم کرده و رویداد onreadystatechange را فعال می‌کند.

اگر پارامتر async فراخوانی قبلی open() برابر با false باشد، این روش مسدود شده و تا زمانی که حالت readyState برابر با 4 و پاسخ سرور به طور کامل دریافت شده باشد، برمی‌گردد. در غیر این صورت، اگر پارامتر async برابر با true باشد یا این پارامتر را فراموش کرده باشید، روش send() بلافاصله برمی‌گردد و، همانطور که در ادامه توضیح داده خواهد شد، پاسخ سرور در یک رشته پس‌زمینه پردازش خواهد شد.

اگر پاسخ سرور دارای یک ریدایرکت HTTP باشد، روش send() یا رشته پس‌زمینه به طور خودکار از ریدایرکت پیروی می‌کند. هنگامی که تمام سرصفحه‌های پاسخ HTTP دریافت شده‌اند، روش send() یا رشته پس‌زمینه حالت readyState را به 3 تنظیم کرده و رویداد onreadystatechange را فعال می‌کند. اگر پاسخ طولانی باشد، روش send() یا رشته پس‌زمینه ممکن است در حالت 3 رویداد onreadystatechange را فعال کند: این می‌تواند به عنوان یک نشانگر پیشرفت بارگیری استفاده شود. در نهایت، هنگامی که پاسخ کامل شد، روش send() یا رشته پس‌زمینه حالت readyState را به 4 تنظیم کرده و رویداد آخرین بار فعال می‌کند.

XMLHttpRequest.setRequestHeader()

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

setRequestHeader(name, value)

پارامتر name نام سرصفحه‌ای است که قرار است تنظیم شود. این پارامتر نباید شامل فاصله، دوام و خطوط خالی باشد.

پارامتر value مقدار سرصفحه است. این پارامتر نباید شامل خطوط خالی باشد.

توضیح

روش setRequestHeader() سرصفحه یک درخواست HTTP را تعیین می‌کند که باید در درخواست‌هایی که از طریق فراخوانی‌های بعدی send() منتشر می‌شوند، شامل شود. این روش فقط زمانی قابل فراخوانی است که حالت readyState برابر با 1 باشد، به عنوان مثال، پس از فراخوانی open()، اما قبل از فراخوانی send().

اگر سرصفحه‌ای با نام مشخص شده قبلاً تعیین شده باشد، مقدار جدید سرصفحه این است: مقدار قبلی، به اضافه کاما، فاصله و مقدار تعیین شده توسط این فراخوانی.

اگر فراخوانی open() گواهی اعتبارسنجی را مشخص کرده باشد، XMLHttpRequest یک سرخط درخواست Authorization مناسب را به صورت خودکار ارسال می‌کند. اما شما می‌توانید از setRequestHeader() برای اضافه کردن این سرخط استفاده کنید. به طور مشابه، اگر سرور وب‌سایت کوکی‌هایی را که با URL ارسالی به open() مرتبط هستند ذخیره کرده باشد، سرخط‌های Cookie یا Cookie2 مناسب نیز به صورت خودکار به درخواست اضافه می‌شوند. این کوکی‌ها می‌توانند از طریق فراخوانی setRequestHeader() به سرخط‌ها اضافه شوند. XMLHttpRequest همچنین می‌تواند یک ارزش پیش‌فرض برای سرخط User-Agent ارائه دهد. اگر این کار را انجام دهد، هر ارزشی که شما برای این سرخط مشخص می‌کنید به این ارزش پیش‌فرض اضافه می‌شود.}

برخی از سرخط‌های درخواستی توسط XMLHttpRequest به صورت خودکار تنظیم می‌شوند و نه توسط این روش، تا با پروتکل HTTP مطابقت داشته باشند. این شامل سرخط‌های مرتبط با نماینده نیز می‌شود:

  • Host
  • Connection
  • Keep-Alive
  • Accept-charset
  • Accept-Encoding
  • If-Modified-Since
  • If-None-Match
  • If-Range
  • Range