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

‎.animate( properties [, duration ] [, easing ] [, complete ] )‎

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

كائن jQuery.

الوصف

يُستخدَم التّابع ‎.animate()‎ في تنفيذ تحريك (animation) مُخصَّص لمجموعة من خاصيّات CSS.

‎.animate( properties [, duration ] [, easing ] [, complete ] )‎

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

properties

كائن مُجرَّد (PlainObject)، ويُمثِّل خاصيّات CSS والقيم التي سيتجه التحريك باتجاهها.

duration

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

easing

سلسلة نصيّة، وتُمثِّل دالة الحركة السّلسة (easing function) المُستخدَمة لأجل الانتقال. القيمة الافتراضيّة: swing.

complete

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

‎.animate( properties, options )‎

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

properties

كائن مُجرَّد (PlainObject)، ويُمثِّل خاصيّات CSS والقيم التي سيتجه التحريك باتجاهها.

options

كائن مُجرَّد (PlainObject)، ويُمثِّل مجموعة خيارات إضافيّة لتمريرها إلى التّابع.

duration

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

easing

سلسلة نصيّة، وتُمثِّل دالة الحركة السّلسة (easing function) المُستخدَمة لأجل الانتقال. القيمة الافتراضيّة: swing.

queue

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

specialEasing

كائن مُجرَّد (PlainObject)، ويُمثِّل كائنًا يحتوي على واحدة أو أكثر من خاصيّات CSS المُعرَّفة عن طريق الوسيط properties ودوال الحركة السّلسة (easing function) المُوافقة لها. أضيف في الإصدار: 1.4.

step

دالة على الشكل ‎Function( Number now, Tween tween )‎، وتُمثِّل الدالة المُستدعاة لكل خاصيّة كائن (property) مُحرَّكة لكل عنصر مُحرَّك. تُزوِّدنا هذه الدالة بفرصة لتعديل الكائن 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.

يسمح لنا التّابع ‎.animate()‎ بإنشاء تأثيرات تحريك لأي خاصيّة CSS عدديّة، والمُعامِل الوحيد المطلوب هو كائن مُجرَّد مُؤلَّف من خاصيّات CSS، يُشبِه هذا الكائن ذلك الكائن المُمكِن إرساله إلى التّابع ‎.css()‎ عدا أنّ مجال الخاصيّات هنا يكون محصورًا أكثر.

قيم وخاصيّات التحريك

ينبغي تحريك جميع الخاصيّات المُحرَّكة إلى قيمة عدديّة واحدة، لا يُمكِن تحريك معظم الخاصيّات غير العدديّة باستخدام وظائف jQuery الأساسيّة (على سبيل المثال يُمكِن تحريك الخاصيّات width، و height، و left، ولكن لا يُمكِن تحريك الخاصيّة background-color ما لم نستخدم الإضافة jQuery Color). تُعامَل قيم الخاصيّات كعدد من البكسلات (Pixels) ما لم يُذكَر خلاف ذلك، ويُمكِن تحديد الواحدات em و % بحسب ما هو مُناسِب.

بالإضافة إلى خاصيّات التنسيق يُمكننا تحريك بعض الخاصيّات غير المستخدمة للتنسيق مثل scrollTop، و scrollLeft، والخاصيّات المُخصَّصة أيضًا.

إنّ خاصيّات CSS المختصرة (مثل font، و background، و border) غير مدعومة بشكل كامل، فإذا أردنا على سبيل المثال تحريك عرض الإطار (border width) فيجب على الأقل مُسبقًا تعيين نمط الإطار (border-style) وعرض الإطار (border-width) إلى قيمة أخرى غير "auto"، أو إن أردنا تحريك حجم الخط (font-size) فيجب استخدام خاصيّة الكائن fontSize أو ما يُكافئها في CSS وهي 'font-size' وذلك بدلًا من كتابة 'font' ببساطة.

وبالإضافة للقيم العدديّة، يُمكِن للخاصيّة أن تأخذ قيم على شكل سلسلة نصيّة وهي 'show'، و 'hide'، و 'toggle'. تسمح هذه الاختصارات بإجراء تحريك مُخصَّص للإخفاء أو الإظهار والتي تأخذ بالحسبان نوع العرض للعنصر. من أجل التبديل بين وضعيتين (toggle)، يجب إعطاء الكلمة المفتاحيّة 'toggle' كقيمة للخاصيّة المطلوب تحريكها.

يُمكِن للخاصيّات المُحرَّكة أن تكون نسبيّة، فإن أضفنا ‎+=‎ أو ‎-=‎ إلى بداية القيمة فستُحسَب القيمة عن طريق جمع أو طرح العدد المُعطَى مع القيمة الحاليّة للخاصيّة.

ملاحظة: على عكس توابع التحريك الأخرى مثل ‎.slideDown()‎ و ‎.fadeIn()‎، لا يُظهِر التّابع ‎.animate()‎ العناصر المخفيّة كجزء من التأثير، على سبيل المثال عند إعطاء الشيفرة ‎$( "someElement" ).hide().animate({height: "20px"}, 500)‎ سيُنفَّذ التحريك ولكن سيبقى العنصر مخفيًّا.

المدة

تُقدَّر المدّة بالميلي ثانية، تُشير القيم الأعلى إلى تحريك أبطأ وليس أسرع. المدّة الافتراضيّة هي 400 ميلي ثانية، يُمكننا إعطاء السلاسل النصيّة 'slow' و 'fast' للإشارة إلى المدّة 600 و 200 على التوالي وبالترتيب.

دوال الاستدعاء

عند إضافة مُعامِلات دوال الاستدعاء وهي start، و step، و progress، و complete، و done، و fail، و always فستُستدعى الدوال على أساس كل عنصر، تُشير this إلى العنصر المُحرَّك، وإن لم يكن هناك عناصر فلن تُستدعى الدوال، وإن كان هناك عناصر مُتعدّدة فسيُنفَّذ الاستدعاء مرّة لكل عنصر مُطابِق وليس مرّة لكامل التحريك. استخدم التابع ‎.promise()‎ للحصول على promise والذي يُمكننا إرفاق الاستدعاءات إليه التي تُطلَق مرّة للمجموعة المُحرَّكة من أي حجم، بما في ذلك المجموعة التي لا تملك أيّة عناصر.

الاستخدام الأساسي

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

<div id="clickme">
 اضغط هنا
</div>
<img id="book" src="book.png" alt="" width="100" height="123"  style="position: relative; left: 10px;">

لتحريك الشفافية (opacity)، والإزاحة اليسرى (left)، وارتفاع الصورة (height) معًا:

$( "#clickme" ).click(function() {
 $( "#book" ).animate({
   opacity: 0.25,
   left: "+=50",
   height: "toggle"
 }, 5000, function() {
   // اكتمل التحريك
 });
});

لاحظ أنّ قيمة خاصيّة الارتفاع height هي 'toggle'، ولمّا كانت الصورة مرئيّةً فسيُقلِّص التحريك الارتفاع إلى الصفر لإخفائه، وعند الضغط مرّة أخرى سينعكس هذا الانتقال.

بعد النقرة الأولى تكون شفافيّة الصورة opacity بقيمتها المطلوبة، لذا لن تُحرَّك هذه الخاصيّة بعد النقرة الثانية. ولمّا كانت القيمة المطلوبة للخاصيّة left هي قيمة نسبيّة فستتحرّك الصورة إلى اليمين مرّة أخرى خلال التحريك الثاني.

لا تملك خاصيّات الاتجاهات (top، و right، و bottom، و left) تأثيرًا واضحًا على العناصر إن كانت قيمة خاصيّة الموقع position هي static، وهي القيمة الافتراضيّة.

ملاحظة: يُوسِّع مشروع jQuery UI التّابع ‎.animate()‎ عن طريق السّماح بتحريك بعض الخاصيّات غير العدديّة مثل الألوان. يتضمّن المشروع أيضًا آليات لتخصيص التحريك عبر أصناف CSS بدلًا من خاصيّات HTML المفردة.

ملاحظة: عند محاولة تحريك عنصر ارتفاعه أو عرضه هو 0px والذي تكون محتوياته مرئيّة نتيجة الفيض (overflow)، فقد تقص jQuery هذا الفيض خلال التحريك، ومع ذلك من المُمكِن بإصلاح أبعاد العنصر الأصلي المطلوب إخفاؤه أن نضمن تنفيذ التحريك بسلاسة. يُستخدَم حذف تعويم المحتوى (clearfix) لإصلاح الأبعاد تلقائيًّا لعنصرك الأساسي بدون الحاجة لتعيينها يدويًّا.

دالة الخطوة (Step Function)

يُزوِّدنا الإصدار الآخر للتّابع ‎.animate()‎ بخيار الخطوة (step)، وهو عبارة عن دالة استدعاء تُطلَق عند كل خطوة من التحريك، تفيدنا هذه الدالة من أجل تمكين أنواع تحريك مُخصَّصة أو تبديل الحركة أثناء حدوثها، تقبل هذه الدالة وسيطين (هما now و fx)، وتُشير this إلى عنصر DOM قيد التحريك.

• now: القيمة العدديّة للخاصيّة قيد التحريك في كل خطوة.
• fx: مرجع إلى كائن prototype المشار إليه بالخاصية jQuery.fx، والذي يحتوي على عدد من الخاصيّات مثل elem لأجل العناصر المُحرَّكة، و start و end لأجل أول وآخر قيمة للخاصيّة المُحرَّكة على التوالي وبالترتيب، و prop لأجل الخاصيّة قيد التحريك.

لاحظ أنّ دالة الخطوة تُستدعى لكل خاصيّة مُحرَّكة لكل عنصر مُحرَّك. على سبيل المثال إن أخذنا عنصرين من القائمة، فستُطلَق الدالة step أربع مرات في كل خطوة من التحريك:

$( "li" ).animate({
 opacity: .5,
 height: "50%"
}, {
 step: function( now, fx ) {
   var data = fx.elem.id + " " + fx.prop + ": " + now;
   $( "body" ).append( "<div>" + data + "</div>" );
 }
});

سلاسة الحركة (easing)

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

سلاسة الحركة بحسب الخاصيّة

نستطيع بدءًا من إصدار jQuery 1.4 تعيين دوال حركة سلسة بحسب الخاصيّة خلال استدعاء وحيد للتّابع ‎.animate()‎، في الإصدار الأول للتّابع ‎.animate()‎ بإمكان كل خاصيّة أن تأخذ مصفوفة كقيمة لها، يُمثِّل العضو الأول للمصفوفة خاصيّة CSS والعضو الثاني دالة الحركة السلسة، وإن لم تُعرَّف دالة حركة سلسة بحسب الخاصيّة لخاصيّة ما، فستستخدم القيمة الموجودة في الوسيط الاختياري لسلاسة الحركة للتابع ‎.animate()‎، وإن لم يكن هذا الوسيط مُعرَّفًا ستُستخدَم القيمة الافتراضيّة swing.

لتحريك العرض والارتفاع معًا باستخدام دالة الحركة السّلسة swing وتحريك الشفافيّة (opacity) باستخدام دالة الحركة السّلسة linear:

$( "#clickme" ).click(function() {
 $( "#book" ).animate({
   width: [ "toggle", "swing" ],
   height: [ "toggle", "swing" ],
   opacity: "toggle"
 }, 5000, "linear", function() {
   $( this ).after( "<div>اكتمل التحريك.</div>" );
 });
});

في الإصدار الثاني من التّابع ‎.animate()‎، يُمكِن لكائن الاختيارات أن يتضمّن الخاصيّة specialEasing والتي هي بحد ذاتها كائن من خاصيّات CSS ودوال الحركة السّلسة المُوافقة لها. على سبيل المثال لتحريك العرض باستخدام دالة الحركة السّلسة linear وتحريك الارتفاع باستخدام دالة الحركة السّلسة easeOutBounce:

$( "#clickme" ).click(function() {
 $( "#book" ).animate({
   width: "toggle",
   height: "toggle"
 }, {
   duration: 5000,
   specialEasing: {
     width: "linear",
     height: "easeOutBounce"
   },
   complete: function() {
     $( this ).after( "<div>اكتمل التحريك.</div>" );
   }
 });
});

نحتاج كما أشرنا سابقًا إلى إضافة لاستخدام الدالة easeOutBounce.

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

يُمكِن إيقاف جميع تأثيرات jQuery عامّةً بما في ذلك التّابع ‎.animate()‎ عن طريق تعيين jQuery.fx.off = true والتي تقوم بكفاءة بتعيين المدّة إلى الصفر، للمزيد من المعلومات انظر إلى jQuery.fx.off.

أمثلة

اضغط على الزر لتحريك عنصر <div> عن طريق خاصيّات مُتعدّدة مختلفة:

<!doctype html>
<html lang="en">
<head> 
<meta charset="utf-8"> 
<title>مثال عن التحريك</title> 
<style>
 div {
   background-color: #bca;
   width: 100px;
   border: 1px solid green;
 } 
</style>
 
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>

<body>
<button id="go">&raquo; Run</button>
<div id="block">مرحبًا!</div>
<script>
// استخدام أنواع واحدات متعددة بداخل تحريك واحد

$( "#go" ).click(function() {
 $( "#block" ).animate({
   width: "70%",
   opacity: 0.4,
   marginLeft: "0.6in",
   fontSize: "3em",
   borderWidth: "10px"
 }, 1500 );
});
</script>

</body>
</html>

تحريك خاصيّة اليسار left لعنصر <div> عن طريق قيمة نسبيّة، اضغط عدّة مرات على الأزرار لمشاهدة عدّة تحريكات نسبيّة مُتتابعة خلف بعضها:

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>مثال عن التحريك</title>

<style>
 div {
   position: absolute;
   background-color: #abc;
   left: 50px;
   width: 90px;
   height: 90px;
   margin: 5px;
 } 
</style>
 
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>

<body>

<button id="left">&laquo;</button>
<button id="right">&raquo;</button>
<div class="block"></div>
<script>
$( "#right" ).click(function() {
 $( ".block" ).animate({ "left": "+=50px" }, "slow" );
});

$( "#left" ).click(function(){
 $( ".block" ).animate({ "left": "-=50px" }, "slow" );
});

</script>
</body>

</html>

في المثال التالي يُظهِر الزر الأول كيفيّة عمل التحريك غير المُتتابِع، حيث يُوسِّع عنصر <div> إلى العرض 90% في نفس الوقت الذي يزداد فيه حجم الخط font-size، وعندما يكتمل تغيير حجم الخط يبدأ تحريك الحدود. يبدأ الزر الثاني تحريك متسلسل تقليدي، حيث يبدأ كل تحريك حالما ينتهي التحريك السابق للعنصر:

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>مثال عن التحريك</title>
 
<style>
 div {
   background-color: #bca;
   width: 200px;
   height: 1.1em;
   text-align: center;
   border: 2px solid green;
   margin: 3px;
   font-size: 14px;
 }

 button {
   font-size: 14px;
 } 
</style>

<script src="https://code.jquery.com/jquery-1.10.2.js"></script>

</head>

<body>

<button id="go1">&raquo; حرّك الكتلة الأولى</button>
<button id="go2">&raquo; حرّك الكتلة الثانية</button>
<button id="go3">&raquo; حرّك الكتلتين معًا</button>
<button id="go4">&raquo; إعادة التعيين</button>
<div id="block1">الكتلة الأولى</div>
<div id="block2">الكتلة الثانية</div>
<script>

$( "#go1" ).click(function() {
 $( "#block1" )
   .animate({
     width: "90%"
   }, {
     queue: false,
     duration: 3000
   })
   .animate({ fontSize: "24px" }, 1500 )
   .animate({ borderRightWidth: "15px" }, 1500 );
});

$( "#go2" ).click(function() {
 $( "#block2" )
   .animate({ width: "90%" }, 1000 )
   .animate({ fontSize: "24px" }, 1000 )
   .animate({ borderLeftWidth: "15px" }, 1000 );
});

$( "#go3" ).click(function() {
 $( "#go1" ).add( "#go2" ).click();
});

$( "#go4" ).click(function() {
 $( "div" ).css({
   width: "",
   fontSize: "",
   borderWidth: ""
 });
});

</script>
</body>
</html>

تحريك خاصيّة اليسار left لعنصر <div> الأول ومزامنة عناصر <div> الأخرى، باستخدام دالة step لتعيين خاصيّات اليسار لها في كل مرحلة من التحريك:

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>مثال عن التحريك</title>
 
<style>
 div {
   position: relative;
   background-color: #abc;
   width: 40px;
   height: 40px;
   float: left;
   margin: 5px;
 } 

</style>
 
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>

</head>

<body>

<p><button id="go">تشغيل »</button></p>
<div class="block"></div>
<div class="block"></div>
<div class="block"></div>
<div class="block"></div>
<div class="block"></div>
<div class="block"></div>

<script>

$( "#go" ).click(function() {
 $( ".block:first" ).animate({
   left: 100
 }, {
   duration: 1000,
   step: function( now, fx ){
     $( ".block:gt(0)" ).css( "left", now );
   }
 });
});

</script>

</body>

</html>

تحريك جميع الفقرات بتعيين خاصيّة اليسار left إلى القيمة 50 والشفافية opacity إلى القيمة 1 (أي تُصبِح مرئيّة)، واستكمال الحركة خلال 500 ميلي ثانية:

$( "p" ).animate({
 left: 50,
 opacity: 1
}, 500 );

تحريك خاصيّات اليسار left والشفافيّة opacity لكل الفقرات، شغّل الحركة خارج الطابور لكي تبدأ تلقائيًّا بدون انتظار دورها:

$( "p" ).animate({
 left: "50px",
 opacity: 1
}, {
 duration: 500,
 queue: false
});

نشاهد هنا مثالًا عن استخدام دوال الحركة السّلسة لتزويدنا بتنسيقات مختلفة للتحريك، سيعمل هذا المثال فقط في حال امتلاكنا لإضافة تُزوِّدنا بدوال الحركة السّلسة. لاحظ عدم فعل هذه الشيفرة أي شيء ما لم يكن عنصر الفقرة مخفيًّا:

$( "p" ).animate({
 opacity: "show"
}, "slow", "easein" );

تحريك جميع الفقرات بالتبديل بين وضعيتين (toggle) للخاصيّتين height و opacity، واستكمال الحركة خلال 600 ميلي ثانية:

$( "p" ).animate({
 height: "toggle",
 opacity: "toggle"
}, {
 duration: "slow"
});

استخدام دالة حركة سلسة لتزويدنا بتنسيق مختلف للحركة، سيعمل هذا المثال فقط إن كنّا نمتلك إضافة تُزوِّدنا بدالة الحركة السّلسة هذه:

$( "p" ).animate({
 opacity: "show"
}, {
 duration: "slow",
 easing: "easein"
});

تحريك جميع الفقرات وتنفيذ دالة استدعاء عند انتهاء الحركة. الوسيط الأول هو كائن من خاصيّات CSS، يُحدِّد الوسيط الثاني أنّ التحريك سيستغرق 1000 ميلي ثانية لكي يكتمل، ويُحدِّد الوسيط الثالث نوع الحركة السّلسة، والوسيط الرابع هو عبارة عن دالة استدعاء مجهولة (anonymous callback function):

$( "p" ).animate({
 height: 200,
 width: 400,
 opacity: 0.5
}, 1000, "linear", function() {
 alert( "all done" );
});

مصادر

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