الفرق بين المراجعتين لصفحة: «JavaScript/Document/getElementsByTagName»
< JavaScript | Document
إضافة الصّفحة |
لا ملخص تعديل |
||
| (3 مراجعات متوسطة بواسطة مستخدم واحد آخر غير معروضة) | |||
| سطر 1: | سطر 1: | ||
<noinclude>{{DISPLAYTITLE:<code>Document.getElementsByTagName()</code>}}</noinclude> | <noinclude>{{DISPLAYTITLE:<code>Document.getElementsByTagName()</code>}}</noinclude> | ||
يُعيد التّابع <code>Document.getElementsByTagName()</code> كائنًا من النّوع <code>[[JavaScript/HTMLCollection|HTMLCollection]]</code> يحتوي على جميع العناصر ذات | يُعيد التّابع <code>Document.getElementsByTagName()</code> كائنًا من النّوع <code>[[JavaScript/HTMLCollection|HTMLCollection]]</code> يحتوي على جميع العناصر ذات اسم الوسم (tag name) المُعطى. عند استدعائه على كائن المُستند، فسيُبحَثُ في كامل المُستند، ما يشمل العقدة الجذر. القيمة المُعادة حيّة، أي أنّها تُحدّث نفسها تلقائيّا للبقاء مُتزامنةً مع شجرة DOM دون الحاجة إلى استدعاء التّابع <code>Document.getElementsByTagName()</code> مرّة أخرى. | ||
==البنية العامة== | ==البنية العامة== | ||
| سطر 7: | سطر 7: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
===<code>elements</code>=== | |||
كائنٌ حيّ من النّوع <code>[[JavaScript/HTMLCollection|HTMLCollection]]</code> (لكن انظر الملاحظات أدناه) يُمثّل مجموعة العناصِر التي وُجدت مرتّبةً حسب طريقة عرضها في شجرة DOM. | |||
كائنٌ حيّ من النّوع <code>[[JavaScript/HTMLCollection|HTMLCollection]]</code> (لكن انظر الملاحظات أدناه) | |||
===<code>name</code>=== | |||
سلسلةٌ نصيّةٌ تُمثّل اسم العنصر. السلسلة النّصيّة الخاصّة <code>"*"</code> تُمثّل جميع العناصر. | سلسلةٌ نصيّةٌ تُمثّل اسم العنصر. السلسلة النّصيّة الخاصّة <code>"*"</code> تُمثّل جميع العناصر. | ||
مُلاحظة: تقول [https://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html آخر مواصفة من W3C] بأنّ قيمة <code>elements</code> عبارةٌ عن كائن <code>[[JavaScript/HTMLCollection|HTMLCollection]]</code>، لكنّ هذا التّابع يُعيد كائنا من النّوع <code>[[JavaScript/ | مُلاحظة: تقول [https://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html آخر مواصفة من W3C] بأنّ قيمة <code>elements</code> عبارةٌ عن كائن <code>[[JavaScript/HTMLCollection|HTMLCollection]]</code>، لكنّ هذا التّابع يُعيد كائنا من النّوع <code>[[JavaScript/NodeList|NodeList]]</code> في مُتصفّحات WebKit (مثل Chrome وSafari). انظر العلّة [https://bugzilla.mozilla.org/show_bug.cgi?id=14869 14869] للمزيد من التّفاصيل. | ||
==أمثلة== | ==أمثلة== | ||
يبدأ التّابع <code>Document.getElementsByTagName()</code> في المثال التّالي من عنصرٍ أبٍ معيّنٍ ويبحث من الأعلى إلى الأسفل تعاوديًّا (recursively) عبر DOM بدايةً من العنصر الأب، بانيًّا مجموعة عناصر أولاد يُساوي اسمها المُعامل <code>name</code>. هذا يشرح كلًّا من <code>Document.getElementsByTagName()</code> والتّابع المُشابه له <code>Element.getElementsByTagName()</code>، والذي يبدأ البحث من عنصرٍ مُعيّن داخل شجرة DOM. | يبدأ التّابع <code>Document.getElementsByTagName()</code> في المثال التّالي من عنصرٍ أبٍ معيّنٍ ويبحث من الأعلى إلى الأسفل تعاوديًّا (recursively) عبر DOM بدايةً من العنصر الأب، بانيًّا مجموعة عناصر أولاد يُساوي اسمها المُعامل <code>name</code>. هذا يشرح كلًّا من <code>Document.getElementsByTagName()</code> والتّابع المُشابه له <code>Element.getElementsByTagName()</code>، والذي يبدأ البحث من عنصرٍ مُعيّن داخل شجرة DOM. | ||
الضّغط على الأزرار يستعمل التّابع <code>getElementsByTagName()</code> لحساب عدد عناصر الفقراتِ أولادِ أبٍ مُعيّن (إمّا المُستند نفسَه أو واحدا من عنصري <nowiki><div></nowiki> مُتداخلين). | الضّغط على الأزرار يستعمل التّابع <code>getElementsByTagName()</code> لحساب عدد عناصر الفقراتِ أولادِ أبٍ مُعيّن (إمّا المُستند نفسَه أو واحدا من عنصري <code>[[HTML/div|<nowiki><div></nowiki>]]</code> مُتداخلين). | ||
<syntaxhighlight lang="html"> | |||
<syntaxhighlight lang=" | |||
| سطر 83: | سطر 81: | ||
==ملاحظات== | ==ملاحظات== | ||
عند استدعاء التّابع <code>Document.getElementsByTagName()</code> على مستند HTML، | عند استدعاء التّابع <code>Document.getElementsByTagName()</code> على مستند HTML، فستُحوَّل قيمة المعامل إلى أحرفٍ صغيرة (lower-case) قبل الاستمرار. هذا التصرّف غير مرغوب عند محاولة التّعامل مع عناصر SVG التي تكون حالة الأحرف فيها على شكل camelCase في شجرة فرعيّة داخل مستند HTML. ستجد التّابع <code>[[JavaScript/Document/getElementsByTagNameNS|Document.getElementsByTagNameNS()]]</code> مُفيدًا في هذه الحالة. | ||
التّابع <code>Document.getElementsByTagName()</code> مُشابهٌ للتّابع <code>[[JavaScript/Element/getElementsByTagName|Element.getElementsByTagName()]]</code> إلّا أنّ بحثه يشمل كامل المُستند | التّابع <code>Document.getElementsByTagName()</code> مُشابهٌ للتّابع <code>[[JavaScript/Element/getElementsByTagName|Element.getElementsByTagName()]]</code> إلّا أنّ بحثه يشمل كامل المُستند عوضًا عن أولاد عنصرٍ واحد. | ||
==مصادر ومواصفات== | ==مصادر ومواصفات== | ||
* مواصفة [http://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-A6C9094 DOM Level 2 | * مواصفة [http://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-A6C9094 DOM Level 2 Core: Document.getElementsByTagName]. | ||
* مواصفة [http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#apis-in-html-documents HTML 5: APIs in HTML documents] | * مواصفة [http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#apis-in-html-documents HTML 5: APIs in HTML documents]. | ||
[[تصنيف:JavaScript]] | [[تصنيف:JavaScript]] | ||
المراجعة الحالية بتاريخ 09:28، 31 مارس 2018
يُعيد التّابع Document.getElementsByTagName() كائنًا من النّوع HTMLCollection يحتوي على جميع العناصر ذات اسم الوسم (tag name) المُعطى. عند استدعائه على كائن المُستند، فسيُبحَثُ في كامل المُستند، ما يشمل العقدة الجذر. القيمة المُعادة حيّة، أي أنّها تُحدّث نفسها تلقائيّا للبقاء مُتزامنةً مع شجرة DOM دون الحاجة إلى استدعاء التّابع Document.getElementsByTagName() مرّة أخرى.
البنية العامة
var elements = document.getElementsByTagName(name);
elements
كائنٌ حيّ من النّوع HTMLCollection (لكن انظر الملاحظات أدناه) يُمثّل مجموعة العناصِر التي وُجدت مرتّبةً حسب طريقة عرضها في شجرة DOM.
name
سلسلةٌ نصيّةٌ تُمثّل اسم العنصر. السلسلة النّصيّة الخاصّة "*" تُمثّل جميع العناصر.
مُلاحظة: تقول آخر مواصفة من W3C بأنّ قيمة elements عبارةٌ عن كائن HTMLCollection، لكنّ هذا التّابع يُعيد كائنا من النّوع NodeList في مُتصفّحات WebKit (مثل Chrome وSafari). انظر العلّة 14869 للمزيد من التّفاصيل.
أمثلة
يبدأ التّابع Document.getElementsByTagName() في المثال التّالي من عنصرٍ أبٍ معيّنٍ ويبحث من الأعلى إلى الأسفل تعاوديًّا (recursively) عبر DOM بدايةً من العنصر الأب، بانيًّا مجموعة عناصر أولاد يُساوي اسمها المُعامل name. هذا يشرح كلًّا من Document.getElementsByTagName() والتّابع المُشابه له Element.getElementsByTagName()، والذي يبدأ البحث من عنصرٍ مُعيّن داخل شجرة DOM.
الضّغط على الأزرار يستعمل التّابع getElementsByTagName() لحساب عدد عناصر الفقراتِ أولادِ أبٍ مُعيّن (إمّا المُستند نفسَه أو واحدا من عنصري <div> مُتداخلين).
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>getElementsByTagName example</title>
<script>
function getAllParaElems() {
var allParas = document.getElementsByTagName('p');
var num = allParas.length;
alert('هناك' + num + ' فقرات في هذا المستند');
}
function div1ParaElems() {
var div1 = document.getElementById('div1');
var div1Paras = div1.getElementsByTagName('p');
var num = div1Paras.length;
alert('هناك' + num + ' فقرات في #div1');
}
function div2ParaElems() {
var div2 = document.getElementById('div2');
var div2Paras = div2.getElementsByTagName('p');
var num = div2Paras.length;
alert('هناك' + num + ' فقرات في #div2');
}
</script>
</head>
<body style="border: solid green 3px">
<p>نصّ خارجيّ</p>
<p>نصّ خارجيّ</p>
<div id="div1" style="border: solid blue 3px">
<p>نصّ div1</p>
<p>نصّ div1</p>
<p>نصّ div1</p>
<div id="div2" style="border: solid red 3px">
<p>نصّ div2</p>
<p>نصّ div2</p>
</div>
</div>
<p>نصّ خارجيّ</p>
<p>نصّ خارجيّ</p>
<button onclick="getAllParaElems();">
أظهر جميع عناصر p في المستند</button><br />
<button onclick="div1ParaElems();">
أظهر جميع عناصر p في المستند في العنصر div1</button><br />
<button onclick="div2ParaElems();">
أظهر جميع عناصر p في المستند في العنصر div2</button>
</body>
</html>
ملاحظات
عند استدعاء التّابع Document.getElementsByTagName() على مستند HTML، فستُحوَّل قيمة المعامل إلى أحرفٍ صغيرة (lower-case) قبل الاستمرار. هذا التصرّف غير مرغوب عند محاولة التّعامل مع عناصر SVG التي تكون حالة الأحرف فيها على شكل camelCase في شجرة فرعيّة داخل مستند HTML. ستجد التّابع Document.getElementsByTagNameNS() مُفيدًا في هذه الحالة.
التّابع Document.getElementsByTagName() مُشابهٌ للتّابع Element.getElementsByTagName() إلّا أنّ بحثه يشمل كامل المُستند عوضًا عن أولاد عنصرٍ واحد.