التابع jQuery.parseHTML() في jQuery
jQuery.parseHTML( data [, context ] [, keepScripts ] )
القيم المعادة
يعيد مصفوفةً (Array).
الوصف
يفسِّر هذا التابع سلسلة نصية تحتوي على شيفرة HTML ثمَّ يعيد مصفوفة من عقد DOM.
jQuery.parseHTML( data [, context ] [, keepScripts ] )
أُضيف مع الإصدار: 1.8.
data
سلسلة نصية تحوي شيفرة HTML التي يراد تفسيرها.
context
عنصرٌ يمثِّل السياق الذي سيُنشَأ فيه محتوى HTML المُفسَّر. القيمة الافتراضيَّة هي العنصر document.
keepScripts
قيمةٌ منطقيَّةٌ تحدِّد إن كان يراد إضافة السكربتات الموجودة في شيفرة HTML المعطاة.
يستعمل التابع jQuery.parseHTML() التوابع المضمنة في JavaScript لتحويل السلسلة النصية المعطاة إلى مجموعة من عقد DOM والتي يمكن إدراجها بعدئذٍ ضمن المستند. تُصيِّر (render) هذه التوابع كامل المحتوى النصي المعطى (حتى المسافات البيضاء البادئة والزائدة). ولمنع تحويل المسافات البيضاء البادئة أو الزائدة إلى عقد نصية (text nodes)، يمكنك تمرير السلسلة النصية أولًا إلى jQuery.trim.
القيمة الافتراضيَّة للوسيط context هي document إن لم يعطَ، أو أعطي وكانت قيمته null أو undefined. إن استُخدِم محتوى HTML المعطى مسبقًا في مستند آخر مثل الإطار iframe، فيمكن استخدام مستند هذا الإطار مع المستند الحالي.
تَغيَّر السلوك الافتراضي لهذا التابع بدءًا من الإصدار jQuery 3.0. فإن لم يعطَ الوسيط context أو أعطي وكانت قيمته null أو undefined، فسيستعمل كائن document جديد، إذ يساعد هذا على تعزيز الحماية لأنَّه لن تُنفَّذ الأحداث المضمنة سطريًا في عناصر HTML (inline events) في أثناء تفسير شيفرة HTML.
حالما تنتهي عمليَّة التحليل وتُدرَج شيفرة HTML إلى مستند موجود، فهذا يعطي بعض الأدوات الفرصة لتخطي DOM المُنشأَة وإزالة أي شيء يُشَك بأنَّه خطير. هذا التحسين لا يطبَّق على الاستخدام الداخلي للتابع jQuery.parsHTML() لأنَّه يُمرَّر إلى الوسيط content الكائن document الحالي دومًا؛ وبالتالي، لا تزال تخضع عبارة مثل $( "#log" ).append( $( htmlString ) ) إلى احتماليَّة إضافة شيفرة خبيثة (malicious code).
تحسبات أمنية
ستُنفَّذ أغلب واجهات jQuery البرمجيَّة (APIs) التي تقبل سلاسل HTML النصية السكربتات الموجودة والمضافة مع محتوى HTML المعطى. لا يسمح التابع jQuery.parseHTML() للسكربتات المفسَّرة من شيفرة HTML بالعمل إلا إذا ضُبطَت قيمة الوسيط keepScript إلى true. على أي حال، لا يزال بالإمكان تنفيذ السكربتات بطريقة غير مباشرة في أغلب البيئات مثل استعمال الخاصِّيَّة <img onerror>. بناءً على ذلك، يجب على من يستدعي التابع أن يكون حذرًا من هذه الناحية وأن يحذف أو يتهرَّب من أيَّة مدخلات ذات مصدر غير موثوق، مثل عناوين URL والكعكات (cookies). من أجل التوافق المستقبلي، لا يجب الاعتماد على القدرة على تشغيل أي محتوى سكربت عندما لا يعطَ المعامل keepScript أو تكون قيمته false.
أمثلة
إنشاء مصفوفة من عقد DOM باستعمال سلسلة نصيَّة تحوي شيفرة HTML ثمَّ إدراجها ضمن العنصر <div>:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>jQuery.parseHTML مثالٌ عن استعمال التابع</title>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div id="log">
<h3>Content:</h3>
</div>
<script>
var $log = $( "#log" ),
str = "hello, <b>my name is</b> jQuery.",
html = $.parseHTML( str ),
nodeNames = [];
// المحللة HTML إضافة شيفرة
$log.append( html );
// المحللة HTML تجميع أسماء العقد من شيفرة
$.each( html, function( i, el ) {
nodeNames[ i ] = "<li>" + el.nodeName + "</li>";
});
// إدراج أسماء العقد
$log.append( "<h3>Node Names:</h3>" );
$( "<ol></ol>" )
.append( nodeNames.join( "" ) )
.appendTo( $log );
</script>
</body>
</html>