الفرق بين المراجعتين ل"jQuery/css"

من موسوعة حسوب
اذهب إلى التنقل اذهب إلى البحث
سطر 1: سطر 1:
 
<noinclude>{{DISPLAYTITLE:التابع <code>‎.css()‎</code>‎ في jQuery}}</noinclude>
 
<noinclude>{{DISPLAYTITLE:التابع <code>‎.css()‎</code>‎ في jQuery}}</noinclude>
يُستخدَم التابع ‎<code>.css()</code>‎ في الحصول على قيمة خاصيّة تنسيق محسوبة (computed style property) للعنصر الأول من مجموعة العناصر المُطابِقة أو تعيين واحدة أو أكثر من خاصيّات CSS لكل عنصر مُطابِق.
+
يُستخدَم التابع ‎<code>.css()</code>‎ في الحصول على [[CSS/computed value|القيمة المحسوبة]] لخاصية من خاصيات التنسيق (computed style property) للعنصر الأول من مجموعة العناصر المُطابِقة أو تعيين واحدة أو أكثر من خاصيّات [[CSS]] لكل عنصر مُطابِق.
 
==<code>‎.css( propertyName )‎</code>==
 
==<code>‎.css( propertyName )‎</code>==
 
===القيمة المعادة===
 
===القيمة المعادة===
[[JavaScript/String|سلسلة نصيّة]].
+
[[JavaScript/String|سلسلة نصيّة من الكائن String]].
 
===الوصف===
 
===الوصف===
 
الحصول على خاصيّات التنسيق المحسوبة للعنصر الأول من مجموعة العناصر المُطابِقة.
 
الحصول على خاصيّات التنسيق المحسوبة للعنصر الأول من مجموعة العناصر المُطابِقة.
سطر 9: سطر 9:
 
أضيفت في الإصدار: 1.0.
 
أضيفت في الإصدار: 1.0.
 
====<code>propertyName</code>====
 
====<code>propertyName</code>====
[[JavaScript/String|سلسلة نصيّة]]، وتُمثِّل اسم خاصيّة CSS.
+
[[JavaScript/String|سلسلة نصيّة String]]، وتُمثِّل اسم خاصيّة CSS.
 
===<code>‎.css( propertyNames )‎</code>===
 
===<code>‎.css( propertyNames )‎</code>===
 
أضيفت في الإصدار: 1.9.
 
أضيفت في الإصدار: 1.9.
 
====<code>propertyNames</code>====
 
====<code>propertyNames</code>====
[[JavaScript/Array|مصفوفة]]، وتُمثِّل مصفوفة من خاصيّات CSS.
+
[[JavaScript/Array|مصفوفة Array]]، وتُمثِّل مصفوفة من خاصيّات CSS.
  
يُعد التابع <code>‎.css()</code>‎ طريقة مثاليّة للحصول على خاصيّة تنسيق محسوبة للعنصر المُطابِق الأول، خاصّة في ضوء الطرق المختلفة التي تصل فيها المتصفحات لهذه الخاصيّات (التّابع ‎<code>getComputedStyle()‎</code> وهو التّابع المعياري الذي تعتمد عليه المتصفحات، مقابل الخاصيّات <code>currentStyle</code> و <code>runtimeStyle</code> في متصفح Internet Explorer قبل الإصدار 9) والمصطلحات المختلفة التي تستخدمها المتصفحات لبعض الخاصيّات، على سبيل المثال يُشير تنفيذ DOM في متصفّح Internet Explorer إلى الخاصيّة <code>float</code> بالاسم <code>styleFloat</code>، بينما تُشير المتصفّحات المتوافقة مع معايير W3C إليها بالاسم <code>cssFloat</code>. تستطيع للسهولة أن تستخدم ببساطة <code>float</code>، وستترجمها jQuery إلى القيمة الصحيحة بالنسبة لكل متصفّح.
+
يُعد التابع <code>‎.css()</code>‎ طريقة مثاليّة للحصول على خاصيّة تنسيق محسوبة للعنصر المُطابِق الأول، خاصّة في ضوء الطرق المختلفة التي تصل فيها المتصفحات لهذه الخاصيّات (التّابع ‎<code>getComputedStyle()‎</code> وهو التّابع المعياري الذي تعتمد عليه المتصفحات، مقابل الخاصيّات <code>currentStyle</code> و <code>runtimeStyle</code> في متصفح Internet Explorer قبل الإصدار 9) والمصطلحات المختلفة التي تستخدمها المتصفحات لبعض الخاصيّات، على سبيل المثال يُشير تنفيذ DOM في متصفّح Internet Explorer إلى الخاصيّة <code>[[CSS/float|float]]</code> بالاسم <code>styleFloat</code>، بينما تُشير المتصفّحات المتوافقة مع معايير W3C إليها بالاسم <code>cssFloat</code>. تستطيع للسهولة أن تستخدم ببساطة <code>float</code>، وستترجمها jQuery إلى القيمة الصحيحة بالنسبة لكل متصفّح.
  
تستطيع jQuery أيضًا تفسير تنسيق DOM و CSS للخاصيّات مُتعدّدة الكلمات بشكلٍ متساوٍ، فعلى سبيل المثال تفهم وتُعيد jQuery القيمة الصحيحة لـ <code>‎.css( "background-color" )</code>‎ و ‎<code>.css( "backgroundColor" )</code>‎، ويعني هذا أنّ دمج حالة الأحرف يمتلك معنى مختلف لكل حالة، فلن يكون لـ ‎<code>.css( "WiDtH" )</code>‎ نفس فعل استخدام <code>‎.css( "width" )</code>‎ مثلًا.
+
تستطيع jQuery أيضًا تفسير تنسيق DOM و CSS للخاصيّات مُتعدّدة الكلمات بشكلٍ متساوٍ، فعلى سبيل المثال تفهم وتُعيد jQuery القيمة الصحيحة لـ <code>‎.css( "background-color" )</code>‎ و ‎<code>.css( "backgroundColor" )</code>‎، ويعني هذا أنّ دمج حالة الأحرف يمتلك معنى مختلف لكل حالة، فلن يكون للتعبير ‎<code>.css( "WiDtH" )</code>‎ نفس فعل استخدام <code>‎.css( "width" )</code>‎ مثلًا.
  
لاحظ أنّ التنسيق المحسوب للعنصر قد لا يكون مماثلًا للقيمة المُحدَّدة لهذا العنصر في ملف التنسيقات، فمثلًا تكون التنسيقات المحسوبة للأبعاد دومًا بالبكسل ولكن يُمكِن تحديدها في ملف التنسيقات بواحدات أخرى مثل <code>em</code>، و <code>ex</code>، و <code>px</code>، و <code>%</code>. قد تُعيد المتصفّحات المختلفة قيم ألوان CSS متساوية منطقيًّا ولكن غير متساوية نصيًّا، مثل ‎<code>#FFF</code>، و ‎<code>#ffffff</code>‎، و ‎<code>rgb(255,255,255)</code>‎.
+
لاحظ أنّ [[CSS/computed value|القيمة المحسوبة]] للخاصية قد لا تكون مماثلةً [[CSS/specified value|للقيمة المحددة]] لهذا العنصر في ملف التنسيقات، فمثلًا تكون التنسيقات المحسوبة للأبعاد دومًا بالبكسل ولكن يُمكِن تحديدها في ملف التنسيقات بواحدات أخرى مثل <code>em</code>، و <code>ex</code>، و <code>px</code>، و <code>%</code>. قد تُعيد المتصفّحات المختلفة قيم ألوان CSS متساوية منطقيًّا ولكن غير متساوية نصيًّا، مثل ‎<code>#FFF</code>، و ‎<code>#ffffff</code>‎، و ‎<code>rgb(255,255,255)</code>‎.
  
يكون استرجاع خاصيّات CSS المختصرة (مثل <code>margin</code>، و <code>background</code>، و <code>border</code>) غير مضمونًا مع أنّه فعّال في بعض المتصفّحات، فمثلًا إن أردنا استرجاع الخاصيّة <code>border-width</code> نستخدم ‎<code>$( elem ).css( "borderTopWidth" )‎</code>، و ‎<code>$( elem ).css( "borderBottomWidth" )‎</code>، وهكذا.
+
يكون استرجاع خاصيّات CSS المختصرة (مثل <code>[[CSS/margin|margin]]</code>، و <code>[[CSS/background|background]]</code>، و <code>[[CSS/border|border]]</code>) غير مضمونًا مع أنّه فعّال في بعض المتصفّحات، فمثلًا إن أردنا استرجاع الخاصيّة <code>[[CSS/border-width|border-width]]</code> نستخدم ‎<code>$( elem ).css( "borderTopWidth" )‎</code>، و ‎<code>$( elem ).css( "borderBottomWidth" )‎</code>، وهكذا.
  
يجب أن يكون العنصر مُتصلًا بـ DOM عند استدعاء التّابع <code>‎.css()‎</code> عليه، وإن لم يكن كذلك فقد ترمي jQuery خطأً.
+
يجب أن يكون العنصر مُتصلًا بشجرة DOM عند استدعاء التّابع <code>‎.css()‎</code> عليه، وإن لم يكن كذلك فقد ترمي jQuery خطأً.
  
بدءًا من إصدار jQuery 1.9 أصبح تمرير مصفوفة من خاصيّات التنسيق إلى التّابع <code>‎.css()‎</code> ينتج عنه كائن من أزواج قيمة-خاصيّة، فمثلًا للحصول على قيم الحدود الأربعة للخاصيّة <code>border-width</code> بإمكاننا استخدام: <code>‎$( elem ).css([ "borderTopWidth", "borderRightWidth", "borderBottomWidth", "borderLeftWidth" ])</code>‎
+
بدءًا من إصدار jQuery 1.9 أصبح تمرير مصفوفة من خاصيّات التنسيق إلى التّابع <code>‎.css()‎</code> ينتج عنه كائن من أزواج قيمة-خاصيّة، فمثلًا للحصول على قيم الحدود الأربعة للخاصيّة <code>[[CSS/border-width|border-width]]</code> بإمكاننا استخدام: <code>‎$( elem ).css([ "borderTopWidth", "borderRightWidth", "borderBottomWidth", "borderLeftWidth" ])</code>‎
 
===أمثلة===
 
===أمثلة===
الحصول على لون الخلفيّة لعنصر ‎<code>[[HTML/div|<nowiki><div></nowiki>]]</code>‎ عند النقر عليه:<syntaxhighlight lang="html">
+
الحصول على لون الخلفيّة <code>[[CSS/background-color|background-color]]</code> لعنصر ‎<code>[[HTML/div|<nowiki><div></nowiki>]]</code>‎ عند النقر عليه:<syntaxhighlight lang="html">
 
<!doctype html>
 
<!doctype html>
 
<html lang="en">
 
<html lang="en">
سطر 61: سطر 61:
 
</body>
 
</body>
 
</html>
 
</html>
</syntaxhighlight>الحصول على العرض، والارتفاع، ولون النص، ولون الخلفيّة لعنصر ‎<code>[[HTML/div|<nowiki><div></nowiki>]]</code>‎ عند النقر عليه:<syntaxhighlight lang="html">
+
</syntaxhighlight>الحصول على العرض <code>[[CSS/width|width]]</code>، والارتفاع <code>[[CSS/height|height]]</code>، ولون النص <code>[[CSS/color|color]]</code>، ولون الخلفيّة <code>[[CSS/background-color|background-color]]</code> لعنصر ‎<code>[[HTML/div|<nowiki><div></nowiki>]]</code>‎ عند النقر عليه:<syntaxhighlight lang="html">
 
<!doctype html>
 
<!doctype html>
 
<html lang="en">
 
<html lang="en">
سطر 130: سطر 130:
 
أضيفت في الإصدار: 1.0.
 
أضيفت في الإصدار: 1.0.
 
====<code>propertyName</code>====
 
====<code>propertyName</code>====
[[JavaScript/String|سلسلة نصيّة]]، وتُمثِّل اسم خاصيّة CSS.
+
[[JavaScript/String|سلسلة نصيّة String]]، وتُمثِّل اسم خاصيّة CSS.
 
====<code>value</code>====
 
====<code>value</code>====
[[JavaScript/String|سلسلة نصيّة]] أو [[JavaScript/Number|عدد]]، وتُمثِّل القيمة المطلوب تعيينها لخاصيّة CSS.
+
[[JavaScript/String|سلسلة نصيّة String]] أو [[JavaScript/Number|عدد Number]]، وتُمثِّل القيمة المطلوب تعيينها لخاصيّة CSS.
 
===<code>‎.css( propertyName, function )‎</code>===
 
===<code>‎.css( propertyName, function )‎</code>===
 
أضيفت في الإصدار: 1.4.
 
أضيفت في الإصدار: 1.4.
 
====<code>propertyName</code>====
 
====<code>propertyName</code>====
[[JavaScript/String|سلسلة نصيّة]]، وتُمثِّل اسم خاصيّة CSS.
+
[[JavaScript/String|سلسلة نصيّة String]]، وتُمثِّل اسم خاصيّة CSS.
 
====<code>function</code>====
 
====<code>function</code>====
دالة على الشكل ‎[[JavaScript/Function|Function]]( [[JavaScript/Integer|Integer]] index, [[JavaScript/String|String]] value )‎، تُعيد [[JavaScript/String|سلسلة نصيّة]] أو [[JavaScript/Number|عدد]]، وتُمثِّل دالة تُعيد القيمة المطلوب تعيينها، يُشير <code>this</code> إلى العنصر الحالي. تستقبل هذه الدالة موقع فهرس العنصر في المجموعة والقيمة السّابقة كوسائط لها.
+
دالة على الشكل ‎[[JavaScript/Function|Function]]( [[JavaScript/Integer|Integer]] index, [[JavaScript/String|String]] value )‎، تُعيد [[JavaScript/String|سلسلة نصيّة]] أو [[JavaScript/Number|عدد]]، وتُمثِّل دالة تُعيد القيمة المطلوب تعيينها، يُشير <code>[[JavaScript/this|this]]</code> إلى العنصر الحالي. تستقبل هذه الدالة موقع فهرس العنصر في المجموعة والقيمة السّابقة كوسائط لها.
 
===<code>‎.css( properties )‎</code>===
 
===<code>‎.css( properties )‎</code>===
 
أضيفت في الإصدار: 1.0.
 
أضيفت في الإصدار: 1.0.
سطر 146: سطر 146:
 
يُسرِّع ويُسهِّل التّابع ‎<code>.css()‎</code> من تعيين خاصيّات العناصر، كما هو الحال مع التّابع ‎<code>[[JQuery/prop|.prop()]]</code>‎. يُمكِن للتّابع ‎<code>.css()‎</code> أن يأخذ إمّا اسم الخاصيّة وقيمتها كمُعامِلات منفصلة، أو كائن مُفرد من أزواج خاصيّة-قيمة.
 
يُسرِّع ويُسهِّل التّابع ‎<code>.css()‎</code> من تعيين خاصيّات العناصر، كما هو الحال مع التّابع ‎<code>[[JQuery/prop|.prop()]]</code>‎. يُمكِن للتّابع ‎<code>.css()‎</code> أن يأخذ إمّا اسم الخاصيّة وقيمتها كمُعامِلات منفصلة، أو كائن مُفرد من أزواج خاصيّة-قيمة.
  
تستطيع jQuery أيضًا تفسير تنسيق DOM و CSS للخاصيّات التي يتألف اسمها من كلمات متعدّدة، فعلى سبيل المثال تفهم jQuery وتُعيد القيمة الصحيحة لـ ‎<code>.css({ "background-color": "#ffe", "border-left": "5px solid #ccc" })</code> و <code>‎.css({backgroundColor: "#ffe", borderLeft: "5px solid #ccc" })‎</code>. لاحظ أنّه في DOM تكون علامات الاقتباس حول اسم الخاصيّة اختياريّة، أما في CSS فهي إجباريّة نظرًا لوجود الشَّرْطَة (hyphen) في اسم الخاصيّة.
+
تستطيع jQuery أيضًا تفسير تنسيق DOM و CSS للخاصيّات التي يتألف اسمها من كلمات متعدّدة، فعلى سبيل المثال تفهم jQuery وتُعيد القيمة الصحيحة للتعبير ‎<code>.css({ "background-color": "#ffe", "border-left": "5px solid #ccc" })</code> و <code>‎.css({backgroundColor: "#ffe", borderLeft: "5px solid #ccc" })‎</code>. لاحظ أنّه في DOM تكون علامات الاقتباس حول اسم الخاصيّة اختياريّة، أما في CSS فهي إجباريّة نظرًا لوجود الشَّرْطَة (hyphen) في اسم الخاصيّة.
  
 
عند تمرير عدد كقيمة، ستُحوِّله jQuery إلى سلسلة نصيّة وتُضيف <code>px</code> إلى نهاية هذه السّلسلة. وإن كانت الخاصيّة تحتاج إلى واحدات أخرى مختلفة عن <code>px</code>، فستُحوِّل القيمة إلى سلسلة نصيّة وتُضيف الواحدة المناسبة قبل استدعاء التّابع.
 
عند تمرير عدد كقيمة، ستُحوِّله jQuery إلى سلسلة نصيّة وتُضيف <code>px</code> إلى نهاية هذه السّلسلة. وإن كانت الخاصيّة تحتاج إلى واحدات أخرى مختلفة عن <code>px</code>، فستُحوِّل القيمة إلى سلسلة نصيّة وتُضيف الواحدة المناسبة قبل استدعاء التّابع.
  
عند استخدام التّابع ‎<code>.css()‎</code> للتعيين، تُعدِّل jQuery خاصيّة تنسيق العنصر <code>style</code>، فمثلًا تكون ‎<code>$( "#mydiv" ).css( "color", "green" )</code>‎ مُكافِئة لـِ ‎<code>document.getElementById( "mydiv" ).style.color = "green"</code>‎. يُؤدّي تعيين قيمة خاصيّة التنسيق إلى سلسلة نصيّة فارغة (مثل <code>‎$( "#mydiv" ).css( "color", "" )</code>‎) إلى إزالة تلك الخاصيّة من العنصر إن كانت مُطبّقة عليه مُسبقًا، سواءً كانت مُطبّقة عن طريق خاصيّة تنسيق HTML، أو عبر التّابع ‎<code>.css()‎</code> في jQuery، أو عبر التعديل المباشر في DOM للخاصيّة <code>style</code>. وكنتيجة لذلك سيُسترجَع تنسيق العنصر بالنسبة لتلك الخاصيّة إلى القيمة التي كانت مُطبّقة، لذلك يُمكِن استخدام هذا التّابع لإلغاء أي تعديلات على التنسيق قُمنا بها مُسبقًا، وعلى الرغم من ذلك لا يُزيل التنسيق المُطبَّق بواسطة قواعد CSS الموجودة في ملفّات تنسيق CSS أو عبر العنصر <code>[[HTML/style|<style‎>]]</code>.
+
عند استخدام التّابع ‎<code>.css()‎</code> للتعيين، تُعدِّل jQuery خاصيّة تنسيق العنصر <code>style</code>، فمثلًا يكون التعبير ‎<code>$( "#mydiv" ).css( "color", "green" )</code>‎ مكافئًا للتعبير ‎<code>document.getElementById( "mydiv" ).style.color = "green"</code>‎. يُؤدّي تعيين قيمة خاصيّة التنسيق إلى سلسلة نصيّة فارغة (مثل <code>‎$( "#mydiv" ).css( "color", "" )</code>‎) إلى إزالة تلك الخاصيّة من العنصر إن كانت مُطبّقة عليه مُسبقًا، سواءً كانت مُطبّقة عن طريق خاصيّة تنسيق HTML، أو عبر التّابع ‎<code>.css()‎</code> في jQuery، أو عبر التعديل المباشر في DOM للخاصيّة <code>style</code>. وكنتيجة لذلك سيُسترجَع تنسيق العنصر بالنسبة لتلك الخاصيّة إلى القيمة التي كانت مُطبّقة، لذلك يُمكِن استخدام هذا التّابع لإلغاء أي تعديلات على التنسيق قُمنا بها مُسبقًا، وعلى الرغم من ذلك لا يُزيل التنسيق المُطبَّق بواسطة قواعد CSS الموجودة في ملفّات تنسيق CSS أو عبر العنصر <code>[[HTML/style|<style‎>]]</code>.
  
'''تحذير:''' من الاستثناءات الملاحظة أنّه في متصفّح Internet Explorer الإصدار 8 فما دون، تُؤدّي إزالة الخاصيّات المكتوبة بالشكل المُختصَر مثل <code>border</code> أو <code>background</code> إلى إزالة تنسيق تلك الخاصيّة تمامًا من العنصر بغض النظر عمّا هو مُحدَّد في ملف تنسيقات CSS أو في العنصر <code>[[HTML/style|<style‎>]].</code>
+
'''تحذير:''' من الاستثناءات الملاحظة أنّه في متصفّح Internet Explorer الإصدار 8 فما دون، تُؤدّي إزالة الخاصيّات المكتوبة بالشكل المُختصَر مثل <code>[[CSS/border|border]]</code> أو <code>[[CSS/background|background]]</code> إلى إزالة تنسيق تلك الخاصيّة تمامًا من العنصر بغض النظر عمّا هو مُحدَّد في ملف تنسيقات CSS أو في العنصر <code>[[HTML/style|<style‎>]].</code>
  
 
'''ملاحظة:''' يتجاهل التّابع ‎<code>.css()‎</code> التصريح <code>‎!important</code>، لذا لا تقلب الشيفرة <code>‎$( "p" ).css( "color", "red !important" )‎</code> لون جميع الفقرات في الصفحة إلى الأحمر. يُنصَح باستخدام الأصناف بدلًا من ذلك، أو استخدام إضافة jQuery.
 
'''ملاحظة:''' يتجاهل التّابع ‎<code>.css()‎</code> التصريح <code>‎!important</code>، لذا لا تقلب الشيفرة <code>‎$( "p" ).css( "color", "red !important" )‎</code> لون جميع الفقرات في الصفحة إلى الأحمر. يُنصَح باستخدام الأصناف بدلًا من ذلك، أو استخدام إضافة jQuery.
سطر 158: سطر 158:
 
بدءًا من إصدار jQuery 1.8، يهتم التّابع ‎<code>.css()‎</code> المُستخدَم للتعيين تلقائيًّا بوضع البادئة لأسماء الخاصيّات. فمثلًا عند كتابة ‎<code>.css( "user-select", "none" )</code>‎ في متصفّحات Chrome و Safari، سيُعيّنها التّابع إلى ‎<code>-webkit-user-select</code>، وفي Firefox سيستخدم ‎<code>-moz-user-select</code>، وفي Internet Explorer 10 سيستخدم <code>‎-ms-user-select</code>.
 
بدءًا من إصدار jQuery 1.8، يهتم التّابع ‎<code>.css()‎</code> المُستخدَم للتعيين تلقائيًّا بوضع البادئة لأسماء الخاصيّات. فمثلًا عند كتابة ‎<code>.css( "user-select", "none" )</code>‎ في متصفّحات Chrome و Safari، سيُعيّنها التّابع إلى ‎<code>-webkit-user-select</code>، وفي Firefox سيستخدم ‎<code>-moz-user-select</code>، وفي Internet Explorer 10 سيستخدم <code>‎-ms-user-select</code>.
  
أصبح التّابع ‎<code>.css()‎</code> بدءًا من إصدار jQuery 1.6 يقبل القيم النسبيّة مثل التّابع <code>[[jQuery/animate|‎.animate()‎]]</code>. والقيم النسبيّة هي عبارة عن سلسلة نصيّة تبدأ بـ ‎‎<code>+=</code>‎ أو <code>‎-=</code>‎ لزيادة أو إنقاص القيمة الحاليّة. فمثلًا إن كانت قيمة الخاصيّة <code>padding-left</code> للعنصر هي <code>10px</code>، فسينتج عن <code>‎.css( "padding-left", "+=15" )‎</code> قيمة إجماليّة لهذه الخاصيّة وهي <code>25px</code>.
+
أصبح التّابع ‎<code>.css()‎</code> بدءًا من إصدار jQuery 1.6 يقبل القيم النسبيّة مثل التّابع <code>[[jQuery/animate|‎.animate()‎]]</code>. والقيم النسبيّة هي عبارة عن سلسلة نصيّة تبدأ بالمعاملات ‎‎<code>+=</code>‎ أو <code>‎-=</code>‎ لزيادة أو إنقاص القيمة الحاليّة. فمثلًا إن كانت قيمة الخاصيّة <code>[[CSS/padding-left|padding-left]]</code> للعنصر هي <code>10px</code>، فسينتج عن <code>‎.css( "padding-left", "+=15" )‎</code> قيمة إجماليّة لهذه الخاصيّة وهي <code>25px</code>.
  
 
يسمح لنا التّابع ‎<code>.css()‎</code> بدءًا من إصدار jQuery 1.4 تمرير دالة كقيمة للخاصيّة:<syntaxhighlight lang="javascript">
 
يسمح لنا التّابع ‎<code>.css()‎</code> بدءًا من إصدار jQuery 1.4 تمرير دالة كقيمة للخاصيّة:<syntaxhighlight lang="javascript">
سطر 166: سطر 166:
 
</syntaxhighlight>يُعيِّن هذا المثال العرض للعناصر المُطابِقة إلى قيم أكبر تدريجيًّا.
 
</syntaxhighlight>يُعيِّن هذا المثال العرض للعناصر المُطابِقة إلى قيم أكبر تدريجيًّا.
  
'''ملاحظة:''' إن لم ترجع أي قيمة من دالة التعيين (أي ‎<code>function( index, style ){} )</code>‎) أو عادت القيمة <code>undefined</code>، فلن تتغيّر القيمة الحاليّة للخاصيّة. يُفيد هذا في تعيين القيم انتقائيًّا عند تحقيق معايير مُحدَّدة فقط.
+
'''ملاحظة:''' إن لم ترجع أي قيمة من دالة التعيين (أي ‎<code>function( index, style ){} )</code>‎) أو عادت القيمة <code>[[JavaScript/undefined|undefined]]</code>، فلن تتغيّر القيمة الحاليّة للخاصيّة. يُفيد هذا في تعيين القيم انتقائيًّا عند تحقيق معايير مُحدَّدة فقط.
  
 
=== أمثلة ===
 
=== أمثلة ===
تغيير لون أي فقرة إلى الأحمر عند وضع الفأرة فوقها (أي إطلاق الحدث <code>mouseover</code>):<syntaxhighlight lang="html">
+
تغيير لون <code>[[CSS/color|color]]</code> أي فقرة إلى الأحمر عند وضع الفأرة فوقها (أي إطلاق الحدث <code>mouseover</code>):<syntaxhighlight lang="html">
 
<!doctype html>
 
<!doctype html>
 
<html lang="en">
 
<html lang="en">
سطر 258: سطر 258:
 
</body>
 
</body>
 
</html>
 
</html>
</syntaxhighlight>تغيير الخاصيّة <code>font-weight</code> و <code>background-color</code> عند إطلاق الحدثين <code>mouseenter</code> و <code>mouseleave</code>:<syntaxhighlight lang="html">
+
</syntaxhighlight>تغيير الخاصيّة <code>[[CSS/font-weight|font-weight]]</code> و <code>[[CSS/background-color|background-color]]</code> عند إطلاق الحدثين <code>mouseenter</code> و <code>mouseleave</code>:<syntaxhighlight lang="html">
 
<!doctype html>
 
<!doctype html>
 
<html lang="en">
 
<html lang="en">
سطر 335: سطر 335:
 
*<span>[http://api.jquery.com/css/ صفحة التابع ‎‎‎.css()‎‎ في توثيق jQuery الرسمي].</span>
 
*<span>[http://api.jquery.com/css/ صفحة التابع ‎‎‎.css()‎‎ في توثيق jQuery الرسمي].</span>
 
[[تصنيف:jQuery]]
 
[[تصنيف:jQuery]]
[[تصنيف:CSS]]
 
 
[[تصنيف:jQuery Manipulation]]
 
[[تصنيف:jQuery Manipulation]]

مراجعة 11:07، 3 يونيو 2018

يُستخدَم التابع ‎.css()‎ في الحصول على القيمة المحسوبة لخاصية من خاصيات التنسيق (computed style property) للعنصر الأول من مجموعة العناصر المُطابِقة أو تعيين واحدة أو أكثر من خاصيّات CSS لكل عنصر مُطابِق.

‎.css( propertyName )‎

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

سلسلة نصيّة من الكائن String.

الوصف

الحصول على خاصيّات التنسيق المحسوبة للعنصر الأول من مجموعة العناصر المُطابِقة.

‎.css( propertyName )‎

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

propertyName

سلسلة نصيّة String، وتُمثِّل اسم خاصيّة CSS.

‎.css( propertyNames )‎

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

propertyNames

مصفوفة Array، وتُمثِّل مصفوفة من خاصيّات CSS.

يُعد التابع ‎.css()‎ طريقة مثاليّة للحصول على خاصيّة تنسيق محسوبة للعنصر المُطابِق الأول، خاصّة في ضوء الطرق المختلفة التي تصل فيها المتصفحات لهذه الخاصيّات (التّابع ‎getComputedStyle()‎ وهو التّابع المعياري الذي تعتمد عليه المتصفحات، مقابل الخاصيّات currentStyle و runtimeStyle في متصفح Internet Explorer قبل الإصدار 9) والمصطلحات المختلفة التي تستخدمها المتصفحات لبعض الخاصيّات، على سبيل المثال يُشير تنفيذ DOM في متصفّح Internet Explorer إلى الخاصيّة float بالاسم styleFloat، بينما تُشير المتصفّحات المتوافقة مع معايير W3C إليها بالاسم cssFloat. تستطيع للسهولة أن تستخدم ببساطة float، وستترجمها jQuery إلى القيمة الصحيحة بالنسبة لكل متصفّح.

تستطيع jQuery أيضًا تفسير تنسيق DOM و CSS للخاصيّات مُتعدّدة الكلمات بشكلٍ متساوٍ، فعلى سبيل المثال تفهم وتُعيد jQuery القيمة الصحيحة لـ ‎.css( "background-color" )‎ و ‎.css( "backgroundColor" )‎، ويعني هذا أنّ دمج حالة الأحرف يمتلك معنى مختلف لكل حالة، فلن يكون للتعبير ‎.css( "WiDtH" )‎ نفس فعل استخدام ‎.css( "width" )‎ مثلًا.

لاحظ أنّ القيمة المحسوبة للخاصية قد لا تكون مماثلةً للقيمة المحددة لهذا العنصر في ملف التنسيقات، فمثلًا تكون التنسيقات المحسوبة للأبعاد دومًا بالبكسل ولكن يُمكِن تحديدها في ملف التنسيقات بواحدات أخرى مثل em، و ex، و px، و %. قد تُعيد المتصفّحات المختلفة قيم ألوان CSS متساوية منطقيًّا ولكن غير متساوية نصيًّا، مثل ‎#FFF، و ‎#ffffff‎، و ‎rgb(255,255,255)‎.

يكون استرجاع خاصيّات CSS المختصرة (مثل margin، و background، و border) غير مضمونًا مع أنّه فعّال في بعض المتصفّحات، فمثلًا إن أردنا استرجاع الخاصيّة border-width نستخدم ‎$( elem ).css( "borderTopWidth" )‎، و ‎$( elem ).css( "borderBottomWidth" )‎، وهكذا.

يجب أن يكون العنصر مُتصلًا بشجرة DOM عند استدعاء التّابع ‎.css()‎ عليه، وإن لم يكن كذلك فقد ترمي jQuery خطأً.

بدءًا من إصدار jQuery 1.9 أصبح تمرير مصفوفة من خاصيّات التنسيق إلى التّابع ‎.css()‎ ينتج عنه كائن من أزواج قيمة-خاصيّة، فمثلًا للحصول على قيم الحدود الأربعة للخاصيّة border-width بإمكاننا استخدام: ‎$( elem ).css([ "borderTopWidth", "borderRightWidth", "borderBottomWidth", "borderLeftWidth" ])

أمثلة

الحصول على لون الخلفيّة background-color لعنصر ‎<div>‎ عند النقر عليه:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>css مثال عن التابع</title>
  <style>
  div {
    width: 60px;
    height: 60px;
    margin: 5px;
    float: left;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<span id="result">&nbsp;</span>
<div style="background-color:blue;"></div>
<div style="background-color:rgb(15,99,30);"></div>
<div style="background-color:#123456;"></div>
<div style="background-color:#f11;"></div>
 
<script>
$( "div" ).click(function() {
  var color = $( this ).css( "background-color" );
  $( "#result" ).html( "لون عنصر div <span style='color:" +
    color + ";'>" + color + "</span>." );
});
</script>
 
</body>
</html>

الحصول على العرض width، والارتفاع height، ولون النص color، ولون الخلفيّة background-color لعنصر ‎<div>‎ عند النقر عليه:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>css مثال عن التابع</title>
  <style>
  div {
    height: 50px;
    margin: 5px;
    padding: 5px;
    float: left;
  }
  #box1 {
    width: 50px;
    color: yellow;
    background-color: blue;
  }
  #box2 {
    width: 80px;
    color: rgb(255, 255, 255);
    background-color: rgb(15, 99, 30);
  }
  #box3 {
    width: 40px;
    color: #fcc;
    background-color: #123456;
  }
  #box4 {
    width: 70px;
    background-color: #f11;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p id="result">&nbsp;</p>
<div id="box1">1</div>
<div id="box2">2</div>
<div id="box3">3</div>
<div id="box4">4</div>
 
<script>
$( "div" ).click(function() {
  var html = [ "يمتلك عنصر div الذي ضغطت عليه التنسيقات التالية:" ];
 
  var styleProps = $( this ).css([
    "width", "height", "color", "background-color"
  ]);
  $.each( styleProps, function( prop, value ) {
    html.push( prop + ": " + value );
  });
 
  $( "#result" ).html( html.join( "<br>" ) );
});
</script>
 
</body>
</html>

‎.css( propertyName, value )‎

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

كائن jQuery.

الوصف

تعيين واحدة أو أكثر من خاصيّات CSS لمجموعة العناصر المُطابِقة.

‎.css( propertyName, value )‎

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

propertyName

سلسلة نصيّة String، وتُمثِّل اسم خاصيّة CSS.

value

سلسلة نصيّة String أو عدد Number، وتُمثِّل القيمة المطلوب تعيينها لخاصيّة CSS.

‎.css( propertyName, function )‎

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

propertyName

سلسلة نصيّة String، وتُمثِّل اسم خاصيّة CSS.

function

دالة على الشكل ‎Function( Integer index, String value )‎، تُعيد سلسلة نصيّة أو عدد، وتُمثِّل دالة تُعيد القيمة المطلوب تعيينها، يُشير this إلى العنصر الحالي. تستقبل هذه الدالة موقع فهرس العنصر في المجموعة والقيمة السّابقة كوسائط لها.

‎.css( properties )‎

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

properties

كائن مُجرَّد (Plain Object)، ويُمثِّل أزواج من خاصيّة-قيمة المطلوب تعيينها.

يُسرِّع ويُسهِّل التّابع ‎.css()‎ من تعيين خاصيّات العناصر، كما هو الحال مع التّابع ‎.prop()‎. يُمكِن للتّابع ‎.css()‎ أن يأخذ إمّا اسم الخاصيّة وقيمتها كمُعامِلات منفصلة، أو كائن مُفرد من أزواج خاصيّة-قيمة.

تستطيع jQuery أيضًا تفسير تنسيق DOM و CSS للخاصيّات التي يتألف اسمها من كلمات متعدّدة، فعلى سبيل المثال تفهم jQuery وتُعيد القيمة الصحيحة للتعبير ‎.css({ "background-color": "#ffe", "border-left": "5px solid #ccc" }) و ‎.css({backgroundColor: "#ffe", borderLeft: "5px solid #ccc" })‎. لاحظ أنّه في DOM تكون علامات الاقتباس حول اسم الخاصيّة اختياريّة، أما في CSS فهي إجباريّة نظرًا لوجود الشَّرْطَة (hyphen) في اسم الخاصيّة.

عند تمرير عدد كقيمة، ستُحوِّله jQuery إلى سلسلة نصيّة وتُضيف px إلى نهاية هذه السّلسلة. وإن كانت الخاصيّة تحتاج إلى واحدات أخرى مختلفة عن px، فستُحوِّل القيمة إلى سلسلة نصيّة وتُضيف الواحدة المناسبة قبل استدعاء التّابع.

عند استخدام التّابع ‎.css()‎ للتعيين، تُعدِّل jQuery خاصيّة تنسيق العنصر style، فمثلًا يكون التعبير ‎$( "#mydiv" ).css( "color", "green" )‎ مكافئًا للتعبير ‎document.getElementById( "mydiv" ).style.color = "green"‎. يُؤدّي تعيين قيمة خاصيّة التنسيق إلى سلسلة نصيّة فارغة (مثل ‎$( "#mydiv" ).css( "color", "" )‎) إلى إزالة تلك الخاصيّة من العنصر إن كانت مُطبّقة عليه مُسبقًا، سواءً كانت مُطبّقة عن طريق خاصيّة تنسيق HTML، أو عبر التّابع ‎.css()‎ في jQuery، أو عبر التعديل المباشر في DOM للخاصيّة style. وكنتيجة لذلك سيُسترجَع تنسيق العنصر بالنسبة لتلك الخاصيّة إلى القيمة التي كانت مُطبّقة، لذلك يُمكِن استخدام هذا التّابع لإلغاء أي تعديلات على التنسيق قُمنا بها مُسبقًا، وعلى الرغم من ذلك لا يُزيل التنسيق المُطبَّق بواسطة قواعد CSS الموجودة في ملفّات تنسيق CSS أو عبر العنصر <style‎>.

تحذير: من الاستثناءات الملاحظة أنّه في متصفّح Internet Explorer الإصدار 8 فما دون، تُؤدّي إزالة الخاصيّات المكتوبة بالشكل المُختصَر مثل border أو background إلى إزالة تنسيق تلك الخاصيّة تمامًا من العنصر بغض النظر عمّا هو مُحدَّد في ملف تنسيقات CSS أو في العنصر <style‎>.

ملاحظة: يتجاهل التّابع ‎.css()‎ التصريح ‎!important، لذا لا تقلب الشيفرة ‎$( "p" ).css( "color", "red !important" )‎ لون جميع الفقرات في الصفحة إلى الأحمر. يُنصَح باستخدام الأصناف بدلًا من ذلك، أو استخدام إضافة jQuery.

بدءًا من إصدار jQuery 1.8، يهتم التّابع ‎.css()‎ المُستخدَم للتعيين تلقائيًّا بوضع البادئة لأسماء الخاصيّات. فمثلًا عند كتابة ‎.css( "user-select", "none" )‎ في متصفّحات Chrome و Safari، سيُعيّنها التّابع إلى ‎-webkit-user-select، وفي Firefox سيستخدم ‎-moz-user-select، وفي Internet Explorer 10 سيستخدم ‎-ms-user-select.

أصبح التّابع ‎.css()‎ بدءًا من إصدار jQuery 1.6 يقبل القيم النسبيّة مثل التّابع ‎.animate()‎. والقيم النسبيّة هي عبارة عن سلسلة نصيّة تبدأ بالمعاملات ‎‎+=‎ أو ‎-=‎ لزيادة أو إنقاص القيمة الحاليّة. فمثلًا إن كانت قيمة الخاصيّة padding-left للعنصر هي 10px، فسينتج عن ‎.css( "padding-left", "+=15" )‎ قيمة إجماليّة لهذه الخاصيّة وهي 25px.

يسمح لنا التّابع ‎.css()‎ بدءًا من إصدار jQuery 1.4 تمرير دالة كقيمة للخاصيّة:

$( "div.example" ).css( "width", function( index ) {
  return index * 50;
});

يُعيِّن هذا المثال العرض للعناصر المُطابِقة إلى قيم أكبر تدريجيًّا.

ملاحظة: إن لم ترجع أي قيمة من دالة التعيين (أي ‎function( index, style ){} )‎) أو عادت القيمة undefined، فلن تتغيّر القيمة الحاليّة للخاصيّة. يُفيد هذا في تعيين القيم انتقائيًّا عند تحقيق معايير مُحدَّدة فقط.

أمثلة

تغيير لون color أي فقرة إلى الأحمر عند وضع الفأرة فوقها (أي إطلاق الحدث mouseover):

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>css مثال عن التابع</title>
  <style>
  p {
    color: blue;
    width: 200px;
    font-size: 14px;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
  <p>ضع مؤشر الفأرة فوق هذه الفقرة</p>
 
  <p>أو فوق هذه الفقرة لرؤية تغيير اللون</p>
 
<script>
$( "p" ).on( "mouseover", function() {
  $( this ).css( "color", "red" );
});
</script>
 
</body>
</html>

زيادة عرض العنصر الذي يمتلك المُعرِّف ‎#box بمقدار 200px عند النقر عليه لأول مرّة:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>css مثال عن التابع</title>
  <style>
  #box {
    background: black;
    color: snow;
    width: 100px;
    padding: 10px;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<div id="box">انقر هنا ليزداد عرض العنصر</div>
 
<script>
$( "#box" ).one( "click", function() {
  $( this ).css( "width", "+=200" );
});
</script>
 
</body>
</html>

تسليط الضوء على الكلمة التي ننقر عليها في الفقرة (عن طريق تعيين لون خلفيتها إلى الأصفر):

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>css مثال عن التابع</title>
  <style>
  p {
    color: blue;
    font-weight: bold;
    cursor: pointer;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p>
  انقر فوق أي كلمة لتسليط الضوء عليها وتغيير لون خلفيتها إلى الأصفر
</p>
 
<script>
var words = $( "p" ).first().text().split( /\s+/ );
var text = words.join( "</span> <span>" );
$( "p" ).first().html( "<span>" + text + "</span>" );
$( "span" ).on( "click", function() {
  $( this ).css( "background-color", "yellow" );
});
</script>
 
</body>
</html>

تغيير الخاصيّة font-weight و background-color عند إطلاق الحدثين mouseenter و mouseleave:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>css مثال عن التابع</title>
  <style>
  p {
    color: green;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p>حرك مؤشر الفأرة فوق هذه الفقرة</p>
<p>مثل هذه الفقرة أو الفقرة السابقة</p>
 
<script>
$( "p" )
  .on( "mouseenter", function() {
    $( this ).css({
      "background-color": "yellow",
      "font-weight": "bolder"
    });
  })
  .on( "mouseleave", function() {
    var styles = {
      backgroundColor : "#ddd",
      fontWeight: ""
    };
    $( this ).css( styles );
  });
</script>
 
</body>
</html>

زيادة حجم عنصر <div‎> عند النقر عليه:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>css مثال عن التابع</title>
  <style>
  div {
    width: 20px;
    height: 15px;
    background-color: #f33;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<div>انقر هنا</div>
<div>انقر هنا</div>
 
<script>
$( "div" ).on( "click", function() {
  $( this ).css({
    width: function( index, value ) {
      return parseFloat( value ) * 1.2;
    },
    height: function( index, value ) {
      return parseFloat( value ) * 1.2;
    }
  });
});
</script>
 
</body>
</html>

مصادر