متد document.addEventListener

مثال (متد document.addEventListener)

اضافه کردن یک رویداد کلیک به document. هنگامی که کاربر در جایی از صفحه کلیک می کند، "Hello World" در یک عنصر <p> با id="demo" نمایش داده می شود:

document.addEventListener("click", function(){
document.getElementById("demo").innerHTML = "Hello World";
});

خودتان امتحان کنید »

در انتهای این صفحه، مثال های بیشتری آورده شده است.

تعریف و کاربرد

متد document.addEventListener()، یک شنونده ی رویداد را به document(صفحه) اضافه می کند.

نکته: می توانید از متد document.removeEventListener() برای حذف کردن یک شنونده ی رویداد که به وسیله ی متد addEventListener() ایجاد شده است، استفاده کنید.

نکته: می توانید از متد element.addEventListener() برای اضافه کردن یک شنونده ی رویداد به یک عنصر خاص استفاده کنید.

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

اعداد داخل جدول زیر نشان دهنده ی اولین ورژن مرورگری است که به طور کامل از این رویداد پشتیبانی می کند.

متد
addEventListener()	1.0	9.0	1.0	1.0	7.0

نکته: متد addEventListener() در Internet Explorer 8 و ورژن های قبلی آن پشتیبانی نمی شود، و همچنین در opera 7 و ورژن های قبلی آن پشتیبانی نمی شود. اما برای این ورژن های مرورگرها، می توانید از متد attachEvent() برای اضافه کردن شنونده های رویداد استفاده کنید.

نحوه استفاده

document.addEventListener(event, function, useCapture)

مقادیر پارامترها

پارامتر	توضیحات
event	ضروری. یک رشته که مشخص کننده ی نام رویداد است. نکته: از پیشوند on استفاده نکنید. بعنوان مثال، از click به جای onclick استفاده کنید. برای دیدن یک لیست از تمام رویداد های HTML DOM مرجع کلیه رویدادهای JavaScript Reference را مشاهده کنید.
function	ضروری. تابعی که به هنگام روی دادن رویداد اجرا می شود را مشخص می کند. هنگامی که رویداد روی می دهد، یک شیء رویداد بعنوان اولین پارامتر به تابع ارسال می شود. نوع این شیء رویداد بستگی به رویداد دارد. بعنوان مثال رویداد click به شیء MouseEvent تعلق دارد.
useCapture	اختیاری. یک مقدار بولی که مشخص می کند آیا رویداد در فاز capturing اجرا شود یا فاز bubbling. مقادیر امکان پذیر: true: مشخص می کند که شنونده ی رویداد در فاز capturing اجرا شود. false: مشخص می کند که شنونده ی رویداد در فاز bubbling اجرا شود.

پارامتر

توضیحات

event

ضروری. یک رشته که مشخص کننده ی نام رویداد است.

نکته: از پیشوند on استفاده نکنید. بعنوان مثال، از click به جای onclick استفاده کنید.
برای دیدن یک لیست از تمام رویداد های HTML DOM مرجع کلیه رویدادهای JavaScript Reference را مشاهده کنید.

function

ضروری. تابعی که به هنگام روی دادن رویداد اجرا می شود را مشخص می کند.

هنگامی که رویداد روی می دهد، یک شیء رویداد بعنوان اولین پارامتر به تابع ارسال می شود. نوع این شیء رویداد بستگی به رویداد دارد. بعنوان مثال رویداد click به شیء MouseEvent تعلق دارد.

useCapture

اختیاری. یک مقدار بولی که مشخص می کند آیا رویداد در فاز capturing اجرا شود یا فاز bubbling.

مقادیر امکان پذیر:

true: مشخص می کند که شنونده ی رویداد در فاز capturing اجرا شود.
false: مشخص می کند که شنونده ی رویداد در فاز bubbling اجرا شود.

جزئیات تکنیکی

DOM Version:	DOM Level 2 Events
مقدار برگشتی	مقدار برگشتی ندارد
Changelog:	پارامتر useCapture در فایرفاکس 6 و اپرا 11.60 اختیاری است.(این پارامتر همواره در مرورگرهای chrome و IE و safari اختیاری بوده است).

مثال - خودتان امتحان کنید

مثال (متد document.addEventListener)

شما همچنین می توانید به یک تابع نام گذاری شده ی خارجی ارجاع دهید:

document.addEventListener("click", myFunction);

function myFunction() {
document.getElementById("demo").innerHTML = "Hello World";
}

خودتان امتحان کنید »

مثال (متد document.addEventListener)

شما می توانید رویدادهای زیادی را به document اضافه کنید.

این مثال نشان می دهد که چطور دو رویداد click را به صفحه اضافه کنید:

document.addEventListener("click", myFunction);
document.addEventListener("click", someOtherFunction);

خودتان امتحان کنید »

مثال (متد document.addEventListener)

شما می توانید رویداد های مختلفی را به document اضافه کنید.

این مثال نشان می دهد که چطور، رویداد ها مختلف را به صفحه اضافه کنید:

document.addEventListener("mouseover", myFunction);
document.addEventListener("click", someOtherFunction);
document.addEventListener("mouseout", someOtherFunction);

خودتان امتحان کنید »

مثال (متد document.addEventListener)

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

document.addEventListener("click", function() {
myFunction(p1, p2);
});

خودتان امتحان کنید »

مثال (متد document.addEventListener)

تغییر دادن رنگ پس زمینه ی عنصر <body> در صفحه:

document.addEventListener("click", function(){
document.body.style.backgroundColor = "red";
});

خودتان امتحان کنید »

مثال (متد document.addEventListener)

استفاده از متد removeEventListener() برای حذف کردن یک شنونده ی رویداد که به وسیله ی متد addEventListener() اضافه شده است:

// Attach an event handler to the document
document.addEventListener("mousemove", myFunction);

// Remove the event handler from the document
document.removeEventListener("mousemove", myFunction);

خودتان امتحان کنید »

مثال (متد document.addEventListener)

برای مرورگرهایی که از متد addEventListener() پشتیبانی نمی کنند می توانید از متد attachEvent() استفاده کنید.

این مثال یک راه حل برای اجرا در تمام مرورگرها را نشان می دهد:

if (document.addEventListener) {                // For all major browsers, except IE 8 and earlier
    document.addEventListener("click", myFunction);
} else if (document.attachEvent) {             // For IE 8 and earlier versions
    document.attachEvent("onclick", myFunction);
}

خودتان امتحان کنید »