التابع `‎‎.text()‎`‎ في jQuery

يجلب هذا التابع المحتوى النصي المرتبط بكل عنصر في مجموعة العناصر المطابقة بالإضافة إلى العناصر الأحفاد لهم، أو يغيِّر المحتوى النصي للعناصر المطابقة.

`‎.text()‎`

القيم المعادة

يعيد سلسلة نصية من النوع String.

الوصف

يجلب هذا التابع المحتوى النصي المرتبط بكل عنصر في مجموعة العناصر المطابقة بالإضافة إلى المحتوى النصي للعناصر الأحفاد أيضًا.

`‎‎.text()‎‎`

أُضيف مع الإصدار: 1.0. ولا يقبل هذا التابع أية وسائط.

يمكن استعمال التابع ‎.text()‎ في مستندات XML ومستندات HTML كلاهما خلافًا للتابع ‎.html()‎. يعيد التابع سلسلة نصية تحتوي على النص المرتبط بجميع العناصر المطابقة (لما كانت مفسِّرات HTML تختلف من متصفح إلى آخر، فقد يختلف محرف السطر الجديد وغيره من المسافات المستعملة في النص المعاد). بفرض لدينا شيفرة HTML التالية:

<div class="demo-container">
  <div class="demo-box">صندوق للتوضيح</div>
  <ul>
    <li>عنصر قائمة 1</li>
    <li>عنصر <strong>قائمة</strong> 2</li>
  </ul>
</div>

عند استعمال ‎$( "div.demo-container" ).text()‎، سنحصل على النتيجة التالية:

صندوق للتوضيح عنصر قائمة 1 عنصر قائمة 2

لا يمكن استعمال التابع ‎.text()‎ مع مدخلات النماذج أو السكربتات. إن أردت جلب أو تغيير القيمة النصية لعناصر الإدخال <input> أو <textarea>، فاستعمل التابع ‎.val()‎. أما إن أردت جلب المحتوى النصي للعنصر <script>، فاستعمل التابع ‎.html()‎.

بدءًا من الإصدار jQuery 1.4، أصبح التابع ‎.text()‎ يعيد قيمة النص وعُقَد CDATA بالإضافة إلى عُقَد العنصر.

أمثلة

إيجاد المحتوى النصي في الفقرة الأولى <p> ثمَّ إسناده إلى الفقرة <p> الأخيرة باستعمال التابع ‎.html()‎ لإظهاره وكأنَّه محتوى نصي مجرَّد (دون أي تنسيق):

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>text مثالٌ عن استعمال التابع</title>
  <style>
  p {
    color: blue;
    margin: 8px;
  }
  b {
    color: red;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p><b>فقرة</b> تجريبية.</p>
<p></p>
 
<script>
var str = $( "p:first" ).text();
$( "p:last" ).html( str );
</script>
 
</body>
</html>

`‎.text( text )‎`

القيم المعادة

يعيد كائنًا من النوع jQuery.

الوصف

يغيِّر هذا التابع المحتوى النصي لكل عنصر في مجموعة العناصر المطابقة إلى محتوى نصي محدَّد.

`‎‎.text()‎‎`

أُضيف مع الإصدار: 1.0.

`text`

سلسلة نصية أو عدد أو قيمة منطقية تمثِّل المحتوى النصي الجديد المراد تبديله بالمحتوى النصي القديم لكل عنصر مطابق. إن أعطي عدد أو قيمة منطقيَّة، فسيُحولان إلى سلسلة نصية (يمثلان على أنَّهما نص مجرَّد).

`‎‎.text( function )‎‎`

أُضيف مع الإصدار: 1.4.

`function`

دالة من الشكل Function( Number index, String text )‎ تعيد المحتوى النصي الجديد المراد تبديله بالمحتوى النصي القديم لكل عنصر مطابق. تقبل هذه الدالة أن يُمرَّر إليها الوسائط التالية: فهرس موقع العنصر في مجموعة العناصر المطابقة، والمحتوى النصي القديم.

يمكن استعمال التابع ‎.text()‎ في مستندات XML ومستندات HTML كلاهما خلافًا للتابع ‎.html()‎.

يجب الانتباه إلى أنَّ هذا التابع يهرِّب محارف السلسلة النصية الجديدة المعطاة عند الضرورة، لذا ستُصيَّر (render) المحارف المهرَّبة وتظهر بشكل صحيح في محتوى HTML.، إذ تفعل ذلك باستدعاء التابع ‎.createTextNode()‎ في DOM الذي لا يفسر محارف السلسلة النصية بوصفها محتوى HTML. بفرض أنَّ لدينا محتوى HTML التالي:

<div class="demo-container">
  <div class="demo-box">صندوق للتوضيح</div>
  <ul>
    <li>عنصر قائمة 1</li>
    <li>عنصر <strong>قائمة</strong> 2</li>
  </ul>
</div>

عند استعمال الشيفرة:

$( "div.demo-container" ).text( "<p>هذا نص تجريبي</p>" );

سنحصل على مخرجات DOM التالية:

<div class="demo-container">
 &lt;p&gt;هذا نص تجريبي&lt;/p&gt;
</div>

ستظهر الأوسمة في الصفحة عيانًا بعد تصيير هذه المخرجات بالشكل:

<p>هذا نص تجريبي</p>

لا يمكن استعمال التابع ‎.text()‎ مع العناصر <input>، لذا استعمل معهم آنذاك التابع ‎.val()‎. بدءًا من الإصدار jQuery 1.4، أصبح بالإمكان تمرير دالة إلى التابع ‎.text()‎ لتبديل المحتوى النصي. انظر مثلًا إلى الشيفرة التالية:

$( "ul li" ).text(function( index ) {
 return "item number " + ( index + 1 );
});

إن أعطينا التابع قائمة غير مرتبة <ul> تحتوي على ثلاثة عناصر <li>، فسيعيد هذا المثال مخرجات DOM شبيهة بالناتج التالي:

<ul>
  <li>العنصر الأول</li>
  <li>العنصر الثاني</li>
  <li>العنصر الثالث</li>
</ul>

أمثلة

إضافة نص إلى الفقرة <p> (لاحظ أنَّ الوسم <b> قد هُرِّب ولم يعد له معنًى):

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>text مثالٌ عن استعمال التابع</title>
  <style>
  p {
    color: blue;
    margin: 8px;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p>فقرة تجريبية.</p>
 
<script>
$( "p" ).text( "<b>محتوى نصي</b> جديد" );
</script>
 
</body>
</html>

مصادر

صفحة التابع ‎‎.text()‎ في توثيق jQuery الرسمي.