وثائق CSS قابلة للتشغيل: متغيرات CSS

Q: كيف أعرّف متغيرًا في CSS؟

اكتب خاصية يبدأ اسمها بشرطتين داخل قاعدة، عادةً :root للقيمة العامة: :root { --brand: #2563eb; }. اقرأها في أي مكان عبر var(--brand)، مثلًا color: var(--brand);.

Q: ما هو :root في CSS؟

:root فئة زائفة تطابق العنصر الجذر للمستند، وهو في صفحة HTML. المتغيرات المعرّفة هناك يرثها كل عنصر. خصوصيتها بمستوى الفئة، فتتغلب على المحدد html العادي.

Q: كيف أضع قيمة افتراضية لمتغير CSS؟

مرّر وسيطًا ثانيًا إلى var(): color: var(--accent, #2563eb);. تُستخدم القيمة الاحتياطية حين لا يكون --accent معرّفًا على العنصر أو أسلافه. ولا تُستخدم حين يكون المتغير معرّفًا بقيمة غير صالحة للخاصية.

Q: كيف أغيّر متغير CSS بـ JavaScript؟

استدعِ setProperty على نمط العنصر: document.documentElement.style.setProperty('--brand', '#16a34a'). كل قاعدة تستخدم var(--brand) تتحدث فورًا. اقرأ القيمة الحالية عبر getComputedStyle(el).getPropertyValue('--brand').

Q: هل أسماء متغيرات CSS حساسة لحالة الأحرف؟

نعم. --Brand و--brand متغيران مختلفان، على عكس أسماء الخصائص العادية مثل color التي لا تتأثر بحالة الأحرف.

تعريف متغير CSS واستخدامه

متغير CSS، واسمه الرسمي الخاصية المخصصة (custom property)، خاصية يبدأ اسمها بـ --. عرّفه مرة واحدة، عادةً على :root كي ترثه الصفحة كلها، واقرأه في أي مكان عبر var().

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>CSS variables</title>
  <style>
    :root {
      --brand: #2563eb;
      --radius: 8px;
      --space: 12px;
    }

    .btn {
      background: var(--brand);
      color: white;
      border: 0;
      border-radius: var(--radius);
      padding: var(--space) calc(var(--space) * 2);
    }

    .card {
      border: 2px solid var(--brand);
      border-radius: var(--radius);
      padding: var(--space);
      margin-bottom: var(--space);
    }
  </style>
</head>
<body>
  <div class="card">Change --brand in :root and both change.</div>
  <button class="btn">Button</button>
</body>
</html>

غيّر --brand إلى #16a34a وسيتغير حد البطاقة والزر معًا. هذه هي الفكرة كلها: قيمة واحدة، ومكان واحد لتغييرها. وتعمل المتغيرات أيضًا مع calc()، كما يظهر في الحشو الجانبي للزر.

الصيغة

:root {
  --name: value;         /* declare */
}

.element {
  color: var(--name);                 /* use */
  color: var(--name, #111827);        /* use, with a fallback */
  padding: calc(var(--space) * 2);    /* compute with it */
}

القاعدة	التفاصيل
الاسم	يبدأ بـ `--` ثم حروف أو أرقام أو `-` أو `_`. حساس لحالة الأحرف: `--Brand` ليس `--brand`.
القيمة	أي شيء تقريبًا: لون، طول، قائمة، سلسلة نصية. لا تُفحص إلا عند استخدامها.
مكان التعريف	أي قاعدة. `:root` للقيم العامة، ومحدد المكوّن للقيم المحلية.
الوراثة	الخصائص المخصصة تُورَّث، فيرى الابن قيم أسلافه.
أين تعمل `var()`	في قيم الخصائص فقط، لا في المحددات ولا أسماء الخصائص ولا شروط `@media`.

يطابق :root العنصر <html>. يُستخدم بدل html لأن خصوصيته بمستوى الفئة، ولأنه يدل عرفًا على «الإعدادات العامة».

النطاق: تجاوز المتغير لكل مكوّن

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

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Scope</title>
  <style>
    :root { --accent: #2563eb; }

    .alert {
      border-inline-start: 6px solid var(--accent);
      background: #e5e7eb;
      color: #111827;
      padding: 10px 14px;
      margin-bottom: 8px;
    }

    .alert.success { --accent: #16a34a; }
    .alert.warning { --accent: #f59e0b; }
  </style>
</head>
<body>
  <div class="alert">Info uses the global blue.</div>
  <div class="alert success">Success overrides --accent.</div>
  <div class="alert warning">Warning overrides it too.</div>
</body>
</html>

الأشكال المختلفة تضبط المتغير فقط، ولا تضبط الحد نفسه أبدًا. إضافة شكل رابع تتطلب سطرًا واحدًا.

القيم الاحتياطية

تستخدم var(--name, fallback) القيمة الاحتياطية حين لا يكون المتغير معرّفًا على العنصر أو أي من أسلافه. كل ما بعد الفاصلة الأولى هو القيمة الاحتياطية، لذلك يمكن أن تحتوي هي نفسها على فواصل (var(--font, Georgia, serif))، ويمكن أن تكون var() أخرى.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Fallback</title>
  <style>
    p { padding: 8px; color: white; }
    .a { background: var(--missing, #16a34a); }
    .b { --defined: #2563eb; background: var(--defined, #16a34a); }
    .c { background: var(--missing, var(--also-missing, #f59e0b)); }
  </style>
</head>
<body>
  <p class="a">Green: --missing is not defined, fallback used.</p>
  <p class="b">Blue: --defined exists, fallback ignored.</p>
  <p class="c">Amber: nested fallback.</p>
</body>
</html>

تغيير المتغيرات بـ JavaScript: مبدّل السمات

يستطيع JavaScript ضبط متغير على أي عنصر عبر style.setProperty(). اضبطه على document.documentElement (العنصر <html>) وستتبعه الصفحة كلها. النمط الأكثر شيوعًا هو تبديل فئة تعيد تعريف المتغيرات:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Theme</title>
  <style>
    :root {
      --bg: #ffffff;
      --text: #111827;
      --muted: #e5e7eb;
    }
    .dark {
      --bg: #111827;
      --text: #f9fafb;
      --muted: #374151;
    }
    body { background: var(--bg); color: var(--text); padding: 12px; }
    .panel { background: var(--muted); padding: 12px; border-radius: 8px; }
  </style>
</head>
<body>
  <div class="panel">
    <p>Theme colors come from three variables.</p>
    <button id="toggle">Toggle dark mode</button>
    <button id="brand">Random text color</button>
  </div>
  <script>
    const root = document.documentElement;
    document.getElementById('toggle').onclick = () => root.classList.toggle('dark');
    document.getElementById('brand').onclick = () => {
      const hue = Math.floor(Math.random() * 360);
      root.style.setProperty('--text', `hsl(${hue} 70% 40%)`);
      console.log(getComputedStyle(root).getPropertyValue('--text'));
    };
  </script>
</body>
</html>

اقرأ قيمة المتغير عبر getComputedStyle(element).getPropertyValue('--text'). لاحظ أن setProperty تكتب نمطًا مضمّنًا على <html>، وهو يتغلب على الفئة .dark، لذلك بعد الضغط على الزر الثاني يبقى لون النص ثابتًا في السمتين إلى أن تُزال القيمة المضمّنة عبر root.style.removeProperty('--text').

تمرير القيم من HTML

المتغير في السمة style هو أنظف طريقة لتسليم بيانات خاصة بكل عنصر إلى ملف الأنماط. يبقى التصميم في CSS، وHTML يوفر رقمًا فقط.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Bars</title>
  <style>
    .bar {
      width: calc(var(--value) * 1%);
      box-sizing: border-box;
      background: #2563eb;
      color: white;
      padding: 4px 8px;
      margin-bottom: 6px;
      border-radius: 4px;
    }
  </style>
</head>
<body>
  <div class="bar" style="--value: 30">30</div>
  <div class="bar" style="--value: 65">65</div>
  <div class="bar" style="--value: 90">90</div>
</body>
</html>

تحوّل calc(var(--value) * 1%) الرقم المجرد إلى نسبة مئوية. ويمكن للمتغيرات أيضًا أن تتغير داخل استعلام وسائط: @media (min-width: 900px) { :root { --space: 20px; } } تجعل كل مسافة تقرأ --space تكبر على الشاشات العريضة.

فخ القيمة غير الصالحة

لا يستطيع المتصفح أن يعرف مسبقًا إن كان المتغير يحمل قيمة صالحة للخاصية التي تستخدمه. وحين لا تكون صالحة، لا تعود الخاصية إلى التصريح السابق في القاعدة، بل تصبح غير صالحة وقت حساب القيمة (invalid at computed-value time) وتتصرف كأنها مضبوطة على unset: الخصائص الموروثة تأخذ قيمة الأب، والباقي يأخذ قيمته الابتدائية.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Invalid value</title>
  <style>
    :root { --size: red; } /* not a length */
    .box {
      background: #e5e7eb;
      padding: 12px;
      font-size: 24px;
      font-size: var(--size); /* invalid: 24px is NOT kept */
      border: 4px solid #f59e0b;
      border-width: var(--missing); /* undefined, no fallback */
    }
  </style>
</head>
<body>
  <div class="box">16px text and a 3px border, not 24px and 4px.</div>
</body>
</html>

يرث النص 16px من <body>، وتعود border-width إلى قيمتها الابتدائية medium، التي ترسمها المتصفحات بعرض 3px. من دون متغيرات يُسقط التصريح غير الصالح ويبقى التصريح الذي قبله؛ أما مع المتغيرات فقد فات الأوان لذلك. القيمة الاحتياطية لا تساعد حين يكون المتغير معرّفًا لكن خاطئًا: فهي مخصصة للمتغير غير المعرّف فقط.

الفرق بين متغيرات CSS ومتغيرات Sass

	متغيرات CSS	متغيرات Sass
الصيغة	`--brand: #2563eb;` و`var(--brand)`	`$brand: #2563eb;`
متى تُحسب	في المتصفح، مباشرة	وقت البناء، وتختفي من الناتج
تغييرها لكل عنصر	نعم، بالوراثة	لا
تغييرها بفئة أو استعلام وسائط	نعم	لا
تغييرها من JavaScript	نعم	لا
استخدامها في المحددات أو شروط الوسائط	لا	نعم

يعمل الاثنان معًا: كثير من المشاريع تستخدم Sass لمنطق وقت البناء وتُخرج متغيرات CSS لكل ما يمكن تغيير سمته.

أخطاء شائعة

نسيان الشرطتين. لا يعمل var(brand)، ولا --brand المعرّف بالشكل -brand.
استخدام متغير في استعلام وسائط. @media (min-width: var(--bp)) غير صالح. شروط الوسائط تحتاج إلى قيم حرفية.
توقع بقاء التصريح السابق مع متغير غير صالح. لا يبقى؛ راجع الفخ أعلاه.
خلط الوحدات بطريقة خاطئة. --gap: 10; ثم margin: var(--gap)px لا تنتج 10px. استخدم calc(var(--gap) * 1px) أو خزّن 10px.
التعريف على العنصر الخطأ. المتغير المعرّف على .card غير مرئي لإخوته أو لأبيه؛ عرّف القيم المشتركة على :root.

الأسئلة الشائعة

كيف أعرّف متغيرًا في CSS؟

اكتب خاصية يبدأ اسمها بشرطتين داخل قاعدة، عادةً :root للقيمة العامة: :root { --brand: #2563eb; }. اقرأها في أي مكان عبر var(--brand)، مثلًا color: var(--brand);.

ما هو :root في CSS؟

:root فئة زائفة تطابق العنصر الجذر للمستند، وهو <html> في صفحة HTML. المتغيرات المعرّفة هناك يرثها كل عنصر. خصوصيتها بمستوى الفئة، فتتغلب على المحدد html العادي.

كيف أضع قيمة افتراضية لمتغير CSS؟

مرّر وسيطًا ثانيًا إلى var(): color: var(--accent, #2563eb);. تُستخدم القيمة الاحتياطية حين لا يكون --accent معرّفًا على العنصر أو أسلافه. ولا تُستخدم حين يكون المتغير معرّفًا بقيمة غير صالحة للخاصية.

كيف أغيّر متغير CSS بـ JavaScript؟

استدعِ setProperty على نمط العنصر: document.documentElement.style.setProperty('--brand', '#16a34a'). كل قاعدة تستخدم var(--brand) تتحدث فورًا. اقرأ القيمة الحالية عبر getComputedStyle(el).getPropertyValue('--brand').

ما الفرق بين متغيرات CSS ومتغيرات Sass؟

متغيرات Sass تُستبدل بقيمها عند ترجمة ملف الأنماط، فلا يمكن أن تتغير في المتصفح. أما متغيرات CSS فتعيش في المتصفح: تُورَّث، ويمكن أن تختلف من عنصر لآخر، وتستجيب لاستعلامات الوسائط والفئات، ويمكن تغييرها من JavaScript.

هل أسماء متغيرات CSS حساسة لحالة الأحرف؟

نعم. --Brand و--brand متغيران مختلفان، على عكس أسماء الخصائص العادية مثل color التي لا تتأثر بحالة الأحرف.

مفاهيم ذات صلة