`Document.getElementsByTagNameNS()‎`

يُعيد التّابع Document.getElementsByTagNameNS()‎ قائمةً تحتوي على جميع العناصر ذات اسم الوسم (tag name) التّابع لمجال الأسماء (namespace) المعطيين. عند استدعائه على كائن المُستند، فسيُبحَثُ في كامل المُستند، ما يشمل العقدة الجذر.

البنية العامة

elements = document.getElementsByTagNameNS(namespace, name)

القيم

`elements‎`

كائنٌ حيّ من النّوع NodeList‎ (لكن انظر الملاحظة أدناه) يُمثّل مجموعة العناصِر التي وُجدت مرتّبةً حسب طريقة عرضها في شجرة DOM.

`namespace‎`

عنوان URI مجال الأسماء المبحوث عنه (انظر ‎element.namespaceURI).

`name‎`

سلسلةٌ نصيّةٌ تُمثّل أسماء العناصِر المبحوث عنها. السلسلة النّصيّة الخاصّة "*"‎ تُمثّل جميع العناصر (انظر ‎element.localName).

مُلاحظة: تقول مواصفة W3C بأنّ قيمة elements‎ عبارةٌ عن كائن NodeList‎، لكنّ هذا التّابع يُعيد كائنا من النّوع HTMLCollection‎ في مُتصفّح Internet Explorer وFirefox. يُعيد متصفّح Opera كائن NodeList‎ ذي تابعٍ namedItem مُطبَّق، ما يجعل الكائن مُشابها للكائن HTMLCollection‎. يُعيد هذا التّابع كائنا صحيحًا من النّوع NodeList فقط في مُتصفّحات WebKit (مثل Chrome وSafari). انظر العلّة 14869 للمزيد من التّفاصيل.

أمثلة

يبدأ التّابع Document.getElementsByTagName()‎ في المثال التّالي من عنصرٍ أبٍ معيّنٍ ويبحث من الأعلى إلى الأسفل تعاوديًّا (recursively) عبر DOM بدايةً من العنصر الأب، بانيًّا مجموعة عناصر أولاد يُساوي اسمها المُعامل name‎. لاحظ أنّه عندما تكون العقدة التي يعمل عليها التّابع مُغايرةً لعقدة المُستند، فالتّابع Element.getElementsByTagNameNS()‎ يُستَخدمُ عوضًا عن هذا التّابع.

لاستخدام المثال التّالي، انسخه وألصقه في ملفٍّ جديدٍ بالامتداد ‎.xhtml‎‎.

<html xmlns="http://www.w3.org/1999/xhtml">

<head>
<title>getElementsByTagNameNS example</title>

<script type="text/javascript">

function getAllParaElems()
{
  var allParas = document.getElementsByTagNameNS("http://www.w3.org/1999/xhtml", "p");

  var num = allParas.length;

  alert('هناك' + num + ' عناصر في هذا المستند');
}


function div1ParaElems()
{
  var div1 = document.getElementById("div1")
  var div1Paras = div1.getElementsByTagNameNS("http://www.w3.org/1999/xhtml", "p");

  var num = div1Paras.length;

  alert('هناك' + num + ' عناصر في  div1');
}


function div2ParaElems()
{
  var div2 = document.getElementById("div2")
  var div2Paras = div2.getElementsByTagNameNS("http://www.w3.org/1999/xhtml", "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>

طريقة محتملة لدعم المتصفحات غير المدعومة

إن لم يكن المتصفّح يدعم ميّزة XPath، فلا بد من استعمال طريقةٍ أخرى (مثل المرور عبر DOM عبر جميع أولاده، التّعرّف على جميع نُسخ ‎@‎xmlns، أو ما شابه ذلك) للبحث عن جميع الوسوم ذات الاسم المحلي ومجال الأسماء المرغوبين، لكنّ XPath أسرع بكثير.

لدعم مُتصفّح Internet Explorer، يُمكن استدعاء XPath عبر غشاءٍ (wrapper) عوضًا عن استدعاء XPath مُباشرةً في المثال أدناه (وذلك لأنّ Internet Explorer يدعم XPath عبر واجهةٍ برمجيّة مُختلفة).

function getElementsByTagNameNSWrapper (ns, elName, doc, context) {
	if (!doc) {
		doc = document;
	}
	if (!context) {
		context = doc;
	}

	var result = doc.evaluate('//*[local-name()="'+elName+'" and namespace-uri() = "'+ns+'"]', context, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);

        var a = [];
        for(var i = 0; i < result.snapshotLength; i++) {
            a[i] = result.snapshotItem(i);
        }
        return a;
}

مصادر ومواصفات

مواصفة DOM Level 2 Core:‏ Document.getElementsByTagNameNS.