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

()slideDown.

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

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

الوصف

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

‎.slideDown( [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()‎ وتُستدعَى مرةً وحدةً مع كل عنصر من العناصر المطابقة بعد اكتمال الحركة المطبقة عليه.

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

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

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

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

إن كان العنصر مخفيًّا منذ البداية، فيكن إظهاره ببطئ مثل:

$( "#clickme" ).click(function() {
  $( "#book" ).slideDown( "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، بما في ذلك ‎.slideDown()‎، بشكل عام باستعمال الضبط 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;‎.

أمثلة

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

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>slideDown مثالٌ عن استعمال التابع</title>
  <style>
  div {
    background: #de9a44;
    margin: 3px;
    width: 80px;
    height: 40px;
    display: none;
    float: left;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
اضغط عليّ!
<div></div>
<div></div>
<div></div>
 
<script>
$( document.body ).click(function () {
  if ( $( "div:first" ).is( ":hidden" ) ) {
    $( "div" ).slideDown( "slow" );
  } else {
    $( "div" ).hide();
  }
});
</script>
 
</body>
</html>

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

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>slideDown مثالٌ عن استعمال التابع</title>
  <style>
  div {
    background: #cfd;
    margin: 3px;
    width: 50px;
    text-align: center;
    float: left;
    cursor: pointer;
    border: 2px outset black;
    font-weight: bolder;
  }
  input {
    display: none;
    width: 120px;
    float: left;
    margin: 10px;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<div>Push!</div>
<input type="text">
<input type="text" class="middle">
<input type="text">
 
<script>
$( "div" ).click(function() {
  $( this ).css({
    borderStyle: "inset",
    cursor: "wait"
  });
  $( "input" ).slideDown( 1000, function() {
    $( this )
      .css( "border", "2px red inset" )
      .filter( ".middle" )
        .css( "background", "yellow" )
        .focus();
    $( "div" ).css( "visibility", "hidden" );
  });
});
 
</script>
 
</body>
</html>

مصادر

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