التابع .toggle() في jQuery
.toggle( [duration ] [, complete ] )
القيمة المعادة
يُعيد كائنًا من النوع jQuery.
الوصف
يبدِّل هذا التابع حالة العناصر المُطابقة بين العرض و الإخفاء.
.toggle( [duration ] [, complete ] )
أُضيف مع الإصدار: 1.0.
duration (القيمة الافتراضية: 400)
مدة الحركة وهو من النوع عدد Number أو سلسلة نصية String.
complete
دالة على الشكل Function()، تُستدعى بمجرد اكتمال الحركة، وتُستدعى مرة واحدة لكل عنصر مطابق.
.toggle( options )
أُضيف مع الإصدار: 1.0.
options
كائن من النوع Object، ويقدم مجموعة من الخيارات الإضافية لتمريرها إلى التابع.
duration (القيمة الافتراضية: 400)
مدة الحركة وهو من النوع عدد Number أو سلسلة نصية String.
easing (القيمة الافتراضية: swing)
سلسلة نصية من النوع String، تُشير إلى دالة التخفيف المستخدمة في عملية التحوّل.
queue (القيمة الافتراضية: true)
قيمة منطقية Boolean تُشير إلى ما إذا كان الحركة ستندرج في قائمة انتظار التأثيرات، وهي من النوع Boolean أو String. إذا كانت قيمتها false، فستبدأ الحركة على الفور. كذلك يمكن، بدءًا من الإصدار jQuery 1.7، أن يقبل خيار queue سلسلة نصية، وفي هذه الحالة تضاف الحركة إلى طابور الانتظار الذي يمثله تلك السلسلة. عند استخدام اسم طابور انتظار مخصص لا تبدأ الحركة تلقائيًا؛ إذ يجب عليك استدعاء .dequeue("queuename") لبدء تشغيله.
specialEasing
وهو كائن من النوع Object، يحتوي على واحد أو أكثر من خصائص CSS المعرفة بواسطة وسيط الخصائص ودوال الانتقال السلس المقابلة. (أُضيف مع الإصدار: 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 ).
.toggle( duration [, easing ] [, complete ] )
أُضيف مع الإصدار: 1.4.3.
duration (القيمة الافتراضية: 400)
مدة الحركة وهو من النوع عدد Number أو سلسلة نصية String.
easing (القيمة الافتراضية: swing)
سلسلة نصية من النوع String، تُشير إلى دالة التخفيف المستخدمة في عملية التحوّل.
complete
دالة على الشكل Function()، تُستدعى بمجرد اكتمال الحركة، وتُستدعى مرة واحدة لكل عنصر مطابق.
.toggle( display )
أُضيف مع الإصدار: 1.3.
display
كائن من النوع Boolean يستخدم true لإظهار العنصر أو false لإخفائه.
ملاحظة: يحتوي طاقم معالجة الأحداث أيضًا على تابع يسمى toggle(). ويستدعى أحدهما وفقًا لمجموعة الوسائط المُمَرَرَة.
إذا لم تُمرَر وسائط، يغيّر التابع .toggle() من حالة ظهور العنصر أو إخفاءه:
$( ".target" ).toggle();
تظهر العناصر المطابقة أو تختفي على الفور، بدون أي تأثيرات حركية، عن طريق تغيير خاصية display في CSS. إذا كان العنصر ظاهرًا في البداية فسيختفي، وإذا كان مخفيًا فسيظهر. تُحفظ الخاصية display أو تُستَرجع حسب الحاجة. إذا كان العنصر يحتوي على قيمة display تساوي inline، ثم اختفى وظهر، فسيظهر مرة أخرى inline.
عند إدخال المدة، أو كائن عادي، أو دالة "كاملة" منفردة، يصبح التابع .toggle() تابع حركي. يحرك التابع .toggle() كل من العرض والارتفاع والعتامة للعناصر المطابقة في وقت واحد. عندما تصل هذه الخصائص إلى 0 بعد حركة إختفاء، ضبط الخاصية display إلى none، بحيث لا يبقى تأثير للعنصر على تخطيط الصفحة.
تُعطى المدد بالمللي ثانية، وتشير القيم الأعلى إلى حركة أبطأ، وليس أسرع. يمكن إدخال السلاسل النصية 'fast' و 'slow' للإشارة إلى الفترات 200 و 600 ميللي ثانية، على التوالي.
دوال الانتقال السلس
بدءًا من الإصدار jQuery 1.4.3، يمكن استخدام سلسلة اختيارية تسمى دالة الحركة السلسة. تحدد دوال الحركة السلسة التي يتقدم بها التحريك في نقاط مختلفة داخل الحركة. تُعد تطبيقات التخفيف الوحيدة في مكتبة jQuery هي التطبيقات الافتراضية، وتُدعى swing، والتطبيق الذي يتقدم بوتيرة ثابتة ويُدعى linear. وتتوفر المزيد من دوال الحركة السلسة مع استخدام المُلحقات، وعلى الأخص طاقم jQuery UI .
دوال رد النداء
تنطلق دوال رد النداء، إذا توفرت، بمجرد اكتمال الحركة. ويمكن أن يكون هذا مفيدًا لإدراج حركات مختلفة معا في تسلسل. لا يُرسل لدوال رد النداء أي وسائط، ولكن يُضبط المعامل this إلى عنصر DOM الذي يجري تحريكه. في حالة تحريك عناصر متعددة، من المهم ملاحظة أن دالة رد نداء تُنفذ مرة واحدة لكل عنصر مُطابق، وليس مرة واحدة للحركة ككل.
يمكننا تحريك أي عنصر، مثل صورة بسيطة:
<div id="clickme">
أنقر هنا
</div>
<img id="book" src="book.png" alt="" width="100" height="123">
استدعاء التابع .toggle() عند النقر على عنصر آخر:
$( "#clickme" ).click(function() {
$( "#book" ).toggle( "slow", function() {
// نهاية الحركة.
});
});
يقبل الإصدار الثاني من التابع معامل منطقي Boolean. إذا كان هذه المعامل true، فسيعرض العناصر المطابقة؛ وستختفي إذا كانت false. في جوهرها، تكون الشيفرة البرمجية:
$( "#foo" ).toggle( display );
مكافئة للشيفرة:
if ( display === true ) {
$( "#foo" ).show();
} else if ( display === false ) {
$( "#foo" ).hide();
}
ملاحظات إضافية
يمكن إيقاف تشغيل جميع تأثيرات jQuery، بما في ذلك .toggle() بشكل عام عن طريق ضبط jQuery.fx.off = true، والذي يضبط فعليًا المدة إلى 0. لمزيد من المعلومات، راجع jQuery.fx.off .
أمثلة
تبديل حالة جميع الفقرات <p>:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>toggle demo</title>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<button>تبديل</button>
<p>مرحبًا</p>
<p style="display: none">مع السلامة</p>
<script>
$( "button" ).click(function() {
$( "p" ).toggle();
});
</script>
</body>
</html>
تحريك جميع الفقرات لعرضها إذا كانت مخفية وإخفائها إذا كانت مرئية، واستكمال الحركة في غضون 600 ميللي ثانية:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>toggle demo</title>
<style>
p {
background: #dad;
font-weight: bold;
font-size: 16px;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<button>تبديل</button>
<p>مرحبًا</p>
<p>كيف حالك؟</p>
<script>
$( "button" ).click(function() {
$( "p" ).toggle( "slow" );
});
</script>
</body>
</html>
عرض جميع الفقرات، ثم إخفائها جميعًا، ذهابًا وإيابًا:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>toggle demo</title>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<button>تبديل</button>
<p>مرحبًا</p>
<p style="display: none">مع السلامة</p>
<script>
var flip = 0;
$( "button" ).click(function() {
$( "p" ).toggle( flip++ % 2 === 0 );
});
</script>
</body>
</html>