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

()slideToggle.

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

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

الوصف

يُظهِر هذا التابع أو يخفي جميع العناصر المطابقة مع حركة انسحابيَّة.

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

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

duration

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

complete

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

‎.slideDown( 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

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

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).

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

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

duration

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

easing

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

complete

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

يحرِّك التابع ‎.slideToggle()‎ ارتفاع العناصر المطابقة، ويؤدي ذلك إلى انسحاب الأجزاء السفلية من الصفحة للأسفل أو للأعلى كاشفًا أو مخفيًا المحتوى للمستخدم، إذ سيختفي العنصر إن كان ظاهرًا، وسيظهر إن كان مخفيًا.

ستُخزَّن قيمة الخاصِّيَّة display لاسترجاعها عن الحاجة. إن كانت قيمتها inline مثلًا في عنصرٍ ما ثمَّ أُخفي هذا العنصر وأُظهر من جديد، فستعود قيمة الخاصِّيَّة display إلى ما كانت عليه ألا وهي inline. عندما تصبح قيمة ارتفاع العنصر 0 أثناء تطبيق حركة لإخفائه، فستُضبط قيمة الخاصِّيَّة display إلى القيمة none للتأكد من أنَّه لم بعد للعنصر أي تأثير على تنسيق وتخطيط الصفحة.

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

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

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

يمكن أن نستدعي التابع slideToggle()‎. عند الضغط على أي عنصر:

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

سيؤدي الضغط على العنصر مرةً أخرى إلى إظهار العنصر مجدَّدًا.

الانتقال السلس (easing)

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

دالة رد النداء (Callback Function)

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

بدءًا من الإصدار jQuery 1.6، يمكن استخدام التابع ‎.promise()‎ بالتزامن مع التابع deferred.done()‎ لتنفيذ دالة رد نداء واحدة للحركة ككل عند اكتمال حركة جميع العناصر المطابقة (راجع أمثلة التابع ‎‎.promise()‎).

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

يمكن إيقاف تشغيل كافة تأثيرات jQuery، بما في ذلك ‎.slideToggle()‎، عمومًا باستعمال الضبط jQuery.fx.off = true، والذي يضبط فعليًا المدة إلى 0. لمزيد من المعلومات، راجع jQuery.fx.off.

إن استُعمل التابع ‎.sildeDown()‎ مع قائمة غير مرتبة <ul> وكانت قيمة الخاصِّيَّة position لعناصرها (<li>) هي relative أو absolute أو fixed، فقد لا تعمل التأثيرات الحركيَّة المطبَّقة عليها بشكل صحيح في الإصدار 6 من المتصفح IE وحتى الإصدار 9 ما لم تملك هذه القائمة الخاصِّيَّة layout. لحل هذه المشكلة، أضف قاعدتي CSS التاليتن إلى القائمة <ul> وهما: position: relative;‎ و zoom: 1;‎.

أمثلة

إظهار وإخفاء جميع الفقرات <p> عبر تحريكها وسحبهم للأسفل والأعلى خلال زمن قدره 600 ميلي ثانية:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>slideToggle مثالٌ عن استعمال التابع</title>
  <style>
  p {
    width: 400px;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<button>أظهر/أخفي الفقرة</button>
<p>
  هذه الفقرة هي نهاية جميع الفقرات.  يجب
  أن تشعر أنك <em>محظوظ</em> جدًا لرؤية مثل هذه الفقرة في حياتك كلها.
  تهانينا لك :)
</p>
 
<script>
$( "button" ).click(function() {
  $( "p" ).slideToggle( "slow" );
});
</script>
 
</body>
</html>

تحريك العناصر <div> المتوضعة بجانب بعضها بعضًا مع وجود فواصل بينها عبر إظهار وإخفاء بعضٍ منها في الوقت ذاته:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>slideToggle مثالٌ عن استعمال التابع</title>
  <style>
  div {
    background: #b977d1;
    margin: 3px;
    width: 60px;
    height: 60px;
    float: left;
  }
  div.still {
    background: #345;
    width: 5px;
  }
  div.hider {
    display: none;
  }
  span {
    color: red;
  }
  p {
    clear: left;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<div></div>
<div class="still"></div>
<div style="display:none;">
</div><div class="still"></div>
<div></div>
<div class="still"></div>
<div class="hider"></div>
<div class="still"></div>
<div class="hider"></div>
<div class="still"></div>
<div></div>
<p><button id="aa">أظهر/أخفي العناصر</button> هنالك <span>0</span> عنصر قد تبدلت حالته.</p>
 
<script>
$( "#aa" ).click(function() {
  $( "div:not(.still)" ).slideToggle( "slow", function() {
    var n = parseInt( $( "span" ).text(), 10 );
    $( "span" ).text( n + 1 );
  });
});
</script>
 
</body>
</html>

مصادر

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