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

()show.

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

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

الوصف

يُظهِر هذا التابع جميع العناصر المطابقة.

‎.show()‎

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

‎.show( [duration ] [, complete ] )‎

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

duration

عدد أو سلسلة نصية تمثل كمية الوقت الذي ستستغرقه عملية إظهار العنصر، وقيمته الافتراضية هي 400.

complete

دالةٌ من الشكل Function()‎ وتُستدعَى مرةً وحدةً مع كل عنصر من العناصر المطابقة بعد اكتمال الحركة المطبقة عليه.

‎.show( options )‎

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

Options

كائن من النوع Object، وهو مجموعة من الخيارات الإضافية التي يمكن تمريرها للتابع وهي:

duration

عدد أو سلسلة نصية، ويحدِّد الوقت الذي ستستغرقه الحركة. قيمته الافتراضيَّة هي 400.

easing

سلسلة نصية، ويحدِّد دالة الانقال السلس ستُسخدَم خلال الحركة. القيمة الافتراضيَّة هي swing.

queue

قيمة منطقية تحدِّد إذا ما كانت الحركة ستضاف إلى طابور التأثيرات الحركية. إذا كانت قيمتها false، فستبدأ الحركة مباشرةً دون انتظار. بدءًا من الإصدار jQuery 1.7، أصبح هذا الخيار يقبل سلسلة نصية أيضًا، وتضاف الحركة في هذه الحالة إلى الطابور الممثل بتلك السلسلة النصية. عند استعمال اسم طابور خاص، فلن تبدأ الحركة تلقائيًا وإنما يجب عليك استدعاء dequeue("queuename")‎. لبدء الحركة. القيمة الافتراضيَّة هي true.

specialEasing

كائن من النوع Object يحتوي على خاصِّيَّة واحدة أو أكثر من خاصِّيَّات CSS المُعرَّفة بوسيط الخاصِّيَّات (properties argument) ودوال الانتقال السلس المقابلة لها. (أضيف مع الإصدار 1.4).

step

دالة من الشكل Function( Number now, Tween tween )‎، وتمثل الدالة التي ستُستدعى لكل خاصِّيَّة تم تحريكها من كل عنصر تم تحريكه. تتيح لنا هذه الدالة الفرصة لتعديل الكائن tween من أجل تغيير قيمة الخاصِّيَّة قبل أن تُضبط.

progress

دالة من الشكل Function( Promise animation, Number progress, Number remainingMs )‎، وتمثل الدالة التي ستُستدعى مرة واحدة فقط لكل عنصر بعد كل خطوة من الحركة بغض النظر عن عدد الخاصِّيَّات التي تم تحريكها. (أضيف مع الإصدار 1.8).

complete

دالة تُستدعى عندما تنتهي الحركة المطبَّقة على العنصر.

start

دالة من الشكل Function( Promise animation )‎ وتمثِّل الدالة التي ستُستدعى عند بدء الحركة المطبقة على العنصر. (أضيف مع الإصدار 1.8).

done

دالة من الشكل Function( Promise animation, Boolean jumpedToEnd )‎، وتمثِّل الدالة التي ستُستدعى عند انتهاء الحركة المطبقة على العنصر (قُبِل الكائن Promise). (أضيف مع الإصدار 1.8).

fail

دالة من الشكل Function( Promise animation, Boolean jumpedToEnd )‎، وتمثِّل الدالة التي ستُستدعى عند فشل إكمال حركة العنصر (رُفِض الكائن Promise). (أضيف مع الإصدار 1.8).

always

دالة من الشكل Function( Promise animation, Boolean jumpedToEnd )‎، وتمثِّل الدالة التي ستُستدعى عندما تكتمل الحركة المطبقة على العنصر أو تتوقف دون اكتمال (قُبِل الكائن Promise أو رُفِض). (أضيف مع الإصدار 1.8).

‎.show( duration [, easing ] [, complete ])‎

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

duration

عدد أو سلسلة نصية، ويحدِّد كمية الوقت الذي ستستغرقه الحركة. القيمة الافتراضيَّة هي 400.

easing

سلسلة نصية تحدِّد أي دالة تسارع ستُسخدم خلال الحركة. القيمة الافتراضيَّة هي swing.

complete

دالةٌ من الشكل Function()‎ وتُستدعَى مرةً وحدةً مع كل عنصر من العناصر المطابقة بعد اكتمال الحركة المطبقة عليه.

استعمال التابع ‎.show()‎ دون معاملات هو أبسط طريقة لإظهار عنصر معيَّن مثل:

$( ".target" ).show();

ستظهر العناصر المطابقة مباشرة بلا حركة. هذا مكافئ لاستدعاء ‎.css( "display", "none" )‎، باستثناء أن قيمة الخاصِّيَّة display تُخزَّن في ذاكرة البيانات المؤقَّتة في jQuery وبهذا يمكن استعادة قيمتها الأولية. إن كانت قيمة الخاصية display هي القيمة inline لعنصر ما وأُخفي ثمَّ أُظهر مرة أخرى، فسيُظهر آنذاك بنفس قيمة خاصية display الأولية والتي هي inline.

ملاحظة: إن استُعملت ‎!important في التنسيقات مثل display: none !important، فلن يلغيها التابع ‎.show()‎. يفضَّل استعمال أصناف مختلفة عبر ‎.addClass()‎، أو ‎.removeClass()‎، أو ‎.togglleClass()‎. يمكن اتباع أسلوب آخر وهو استعمال ‎.attr( "style", "display: block !important;" )‎ ولكن كن حذرًا، إذ تُستبدَل حينئذٍ الخاصية style للعنصر.

عندما تُمرَّر قيمة المعامل duration أو كائن من نوع object أو الدالة complete إلى التابع ‎.show()‎، فيصبح هذا التابع تابعًا حركيًا. يحرِّك التابع ‎.show()‎ طول وعرض وشفافيَّة العناصر المطابقة في الوقت ذاته.

تعطى قيمة الوسيط duration بالميلي ثانية، وكلما كانت قيمة هذا المعامل أكبر، استغرقت الحركات وقتًا أطول. يمكن أن يكون هذا الوسيط سلسلة نصية أيضًا مثل 'fast' التي تكافئ 200 ميلي ثانية و 'slow' التي تكافئ 600 ميلي ثانية.

بدءًا من الإصدار jQuery 1.4.3، يمكن استخدام سلسلة نصية اختيارية لتسمية دالة الحركة السلسة. تُستعمَل دوال الحركة السلسة لتغيير السرعة في نقاط مختلفة داخل الحركة أثناء تقدم عملية التحريك. دوال الانتقال السلس الوحيدة المبنية في jQuery هي الدالة الافتراضية swing وأخرى تتحرك بسرعة ثابت تدعى linear. هناك دوال انتقال سلس أخرى يمكننا الحصول عليها باستعمال الإضافات، ومن أهمها الإضافة jQuery UI suite.

إن مُرِّر تابع رد نداء callback، فسيُستدعى هذا التابع مباشرة بعد انتهاء الحركة، وهذا قد يكون مفيدًا لجمع حركات مختلفة معًا في سلسلة نصية وفقًا لتعاقب محدَّد. لايقبل التابع callback أية وسائط، ولكن يمكن استعمال this داخله الذي يشير إلى عنصر DOM الذي يجري تحريكه. إن شملت الحركة مجموعة من العناصر، فمن المهم أن نشير إلى أن دالة callback تُنفَّذ مرةً لكل عنصر مطابق، وليس مرةً واحدةً للحركة ككل.

ملاحظة: يمكن أن يسبب هذا التابع مشاكل في الأداء خصوصًا عندما يُستعمل مع مجموعة من العناصر. إن واجهت مشاكل من هذا القبيل، فاستعمل أدوات قياس الأداء كي تعرف هل المسبب لتلك المشاكل هو التابع ‎.show()‎ فعلًا. أضف إلى ذلك أنَّه يمكن أن يُسبب هذا التابع مشاكل مع التصميم المتجاوب إذا كانت قيمة الخاصية display تتغير بتغير قياس الشاشة.

يمكن تحريك أي عنصر مثل صورة بسيطة:

<div id="clickme">
  اضغط هنا
</div>
<img id="book" src="book.png" alt="" width="100" height="123">

إن كان العنصر مخفي من البداية، فيمكن إظهاره ببطء:

$( "#clickme" ).click(function() {
  $( "#book" ).show( "slow", function() {
    // إكتمال الحركة
  });
});

ملاحظات إضافية

يمكن إيقاف كل تأثيرات jQuery، من ضمنها ‎.show()‎، باستعمال الضبط jQuery.fx.off = true، والذي يغير بفاعلية الوسيط duration إلى 0. لمعلومات أكثر، اطلع على  jQuery.fx.off.

أمثلة

إظهار كل الفقرات <p> المخفية ببطء، إذ ستكتمل الحركة في غضون 600 ميلي ثانية:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>show مثالٌ عن استعمال التابع</title>
  <style>
  p {
    background: yellow;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<button>أظهر كل ما هو مخفي </button>
<p style="display: none">مرحبًا</p>
 
<script>
$( "button" ).click(function() {
  $( "p" ).show( "slow" );
});
</script>
 
</body>
</html>

إظهار العنصر <div> الأول وما يتبعه من عناصر أخوة متجاورة من النوع <div> أيضًا بالترتيب، إذ تستغرق كل حركة 200 ميلي ثانية. تبدأ كل حركة عندما تنتهي حركة العنصر الأخ السابق:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>show مثالٌ عن استعمال التابع</title>
  <style>
  div {
    background: #def3ca;
    margin: 3px;
    width: 80px;
    display: none;
    float: left;
    text-align: center;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<button id="showr">أظهر</button>
<button id="hidr">أخفِ</button>
<div>السلام عليكم,</div>
<div>مرحبًا</div>
<div>كيف</div>
<div>الحال؟</div>
 
<script>
$( "#showr" ).click(function() {
  $( "div" ).first().show( "fast", function showNext() {
    $( this ).next( "div" ).show( "fast", showNext );
  });
});
 
$( "#hidr" ).click(function() {
  $( "div" ).hide( 1000 );
});
</script>
 
</body>
</html>

إظهار جميع العناصر <span> وعناصر الإدخال <input> باستعمال حركات. سيتغير النص بعد انتهاء كل حركة:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>show مثالٌ عن استعمال التابع</title>
  <style>
  span {
    display: none;
  }
  div {
    display: none;
  }
  p {
    font-weight: bold;
    background-color: #fcd;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<button>ابدأ الآن</button>
<span>هل أنت متأكد؟ اكتب “نعم” إن كنت كذلك. </span>
<div>
  <form>
    <input type="text"  value="اكتب هنا">
  </form>
</div>
<p style="display:none;">أنا فقرة مخفية :)</p>
 
<script>
function doIt() {
  $( "span,div" ).show( "slow" );
}
// يمكن التمرير باسم الدالة
$( "button" ).click( doIt );
 
$( "form" ).submit(function( event ) {
  if ( $( "input" ).val() === "yes" ) {
    $( "p" ).show( 4000, function() {
      $( this ).text( "حسنًا، لقد انتهينا );
    });
  }
  $( "span,div" ).hide( "fast" );
 
  // منع إرسال النموذج
  event.preventDefault();
});
</script>
 
</body>
</html>

مصادر

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