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

يُستخدَم التابع ‎.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>

مصادر

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

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

محتويات

`‎.css( propertyName )‎`

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

الوصف

`‎.css( propertyName )‎`

`propertyName`

`‎.css( propertyNames )‎`

`propertyNames`

أمثلة

`‎.css( propertyName, value )‎`

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

الوصف

`‎.css( propertyName, value )‎`

`propertyName`

`value`

`‎.css( propertyName, function )‎`

`propertyName`

`function`

`‎.css( properties )‎`

`properties`

أمثلة

مصادر

قائمة التصفح

بحث

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

‎.css( propertyName )‎

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

الوصف

‎.css( propertyName )‎

propertyName

‎.css( propertyNames )‎

propertyNames

أمثلة

‎.css( propertyName, value )‎

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

الوصف

‎.css( propertyName, value )‎

propertyName

value

‎.css( propertyName, function )‎

propertyName

function

‎.css( properties )‎

properties

أمثلة

مصادر

قائمة التصفح

بحث

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

`‎.css( propertyName )‎`

`‎.css( propertyName )‎`

`propertyName`

`‎.css( propertyNames )‎`

`propertyNames`

`‎.css( propertyName, value )‎`

`‎.css( propertyName, value )‎`

`propertyName`

`value`

`‎.css( propertyName, function )‎`

`propertyName`

`function`

`‎.css( properties )‎`

`properties`