تحديث الثيمات والإضافات لدعم الوضع المظلم التلقائي

توثيق أدلة المطور
, ,
1

Previously, all colors in Discourse were stored as SCSS variables. To support automatic dark mode color scheme switching, we have converted these colors in core to custom CSS properties. You can easily see the full list in the inspector now:

image
image2526×1978 745 KB

Themes and plugins need to switch all the $color SCSS variables used in stylesheets to the --color CSS property equivalents. In most cases, this is a simple find and replace task:

-   background-color: $primary-very-low;
+   background-color: var(--primary-very-low);

But there are some cases where a theme or a plugin is using a more complex variation of a color, for example, when darkening or lightening using SCSS color functions. These cases require a more complex refactoring, and for this we have added the capacity to extend color definitions in themes and plugins.

In plugins

This commit in the discourse-encrypt plugin is a good and simple example of such a refactor. It moves a mix($color1, $color2) SCSS declaration into a separate file and stores it as a CSS custom property. Then the new file is registered as a :color_definitions asset which ensures that the newly declared color property is included in the color definitions stylesheet.

In themes

In themes, you can do the same thing by declaring CSS custom properties in the common/color_definitions.scss stylesheet. You can look at this commit in the graceful theme for an example.

Some additional notes

  • when using transparent colors via the rgba($color, 0.5) function, SCSS accepts HEX and RGB colors in the first parameter, whereas CSS custom properties only accept an RGB color. That is why we have introduced the hexToRGB() helper and some properties with the --rgb suffix in the color definitions. An example:
// color_definitions.scss
:root {
  --primary: #{$primary};
  --primary-rgb: #{hexToRGB($primary)};
}

// other stylesheet
.element {
  background-color: rgba(var(--primary-rgb), 0.05);
}
  • note that in the snippet above, the SCSS variable is interpolated when passed to a custom property. That is a requirement in SCSS, see Sass: Property Declarations for more details.
  • the CSS var() declaration can fallback to a second value if the first one is not available, as in, when writing var(--color1, red), CSS will fallback to the red color if the --color1 property is not found. In plugins, we use the SCSS color variables as fallbacks to ensure compatibility with previous versions of Discourse. So the earlier example, would look like this with a fallback:
-   background-color: $primary-very-low;
+   background-color: var(--primary-very-low, $primary-very-low);

This document is version controlled - suggest changes on github.

24 إعجابًا
2

I’m not very good at this stuff and it’ll take me a while to figure this out myself. . . Does this mean that all themes that referred to colors before are now going to be broken?

6 إعجابات
3

No, not at all. SCSS variables in themes will continue to work for a long time.

But any colors outputted via SCSS variables will stay static, i.e. they cannot be dynamically switched to a new color scheme when a browser goes from normal to dark mode. So those themes/plugins will continue to work, they just won’t be compatible with automatic dark mode switching.

13 إعجابًا
4

Thanks for the instructions. Is there a way to also change a background image depending on dark/light mode? (I’ve used the theme switcher component to do that.) Would a CSS class indicating the mode be possible?

إعجابَين (2)
5

Great question, I tried this and noticed that we didn’t properly support using background images or theme variables in the special color definitions stylesheet. So I made some fixes in core, and you should be able to do this now (make sure you pull the latest core).

So, if you have two images in your theme or theme component, with SCSS vars of $bg-light and $bg-dark respectively, you can add this to your color_definitions.scss stylesheet:


$bg: url(dark-light-choose($bg-light, $bg-dark));

:root {
  --custom-bg: #{$bg};
}

And then you can use var(--custom-bg) in your regular stylesheet.

8 إعجابات
6

For an image, all you need to do is the vanilla prefers-dark-theme CSS media query.

7

That won’t work well in all cases, because the media query is not aware of the user’s preferences. Users can disable auto-dark-mode switching, but the media query won’t be aware of that, and it will result in the background meant for the dark color scheme being rendered.

4 إعجابات
8

هل من الممكن لـ Discourse أيضًا إضافة فئة CSS إلى <body> لمخطط الألوان أو معرف مخطط الألوان؟ يبدو أن هذا سيكون أسهل بكثير.

أحاول حل مشكلة أثناء تحويل السمة حيث أحتاج إلى الكثير من قواعد CSS والمتغيرات المختلفة، وهي تتحول إلى فوضى معقدة في ملف color_definitions.scss.

إذا كان بإمكاني فقط القيام بشيء كهذا في ملف SCSS معزول في السمة، فسوف يستغرق الأمر 5 دقائق للقيام بشيء يستغرق وقتًا طويلاً لمعرفة كيفية التعامل معه باستخدام color_definitions.scss:

body.dark-palette .some-thing {
  // some styles
}

body.light-palette .some-thing {
  // some styles
}
9

نعم، يمكن أن ينتهي بك الأمر بالعديد من أسطر التعليمات البرمجية في ملفات تعريف الألوان، خاصةً للتدرجات.

لا يزال هذا هو المكان الأنسب في ذهني. إنه بعيد عن العنصر الذي يتم استخدامه فيه، نعم، ولكنه مكان واحد مناسب يتعامل مع الألوان/التدرجات التي تتغير بناءً على الوضع الفاتح/الداكن.

البديل هو استخدام شيء مثل هذا:

@container style(--scheme-type: light){
  body{
    background: red;
  }
}

تأتي مخططات الألوان الخاصة بنا مع خاصية --scheme-type وهي light للمخططات الفاتحة و dark للمخططات الداكنة. تدعم المتصفحات الحديثة استعلامات الحاوية، لذا يجب أن يؤدي هذا إلى تحقيق ما تحاول إنجازه هنا دون إضافة فئة إلى جسم الصفحة.

10

مهاراتي في CSS/SCSS ليست رائعة. ربما يكون هذا أسهل للأشخاص المتعمقين في هذه الأمور.

لقد كان يسبب فوضى في ملف color_definitions.scss، لذلك نقلته إلى ملف آخر في scss/ حتى أتمكن من استيراده. لست متأكدًا من كيفية تسمية كل شيء، لذا يبدو الأمر كالتالي:

تنظيم ملف SCSS
تنظيم ملف SCSS870×740 63 KB

أعتقد أنه سيكون من الأسهل القيام بذلك باستخدام فئة body (أو ربما بعض الأمثلة الأخرى)، ولكن في كل الأحوال، إنه يعمل في الوقت الحالي. لا أعرف كيف تعمل استعلامات الحاوية، لكنني سأبحث عنها لاحقًا.

11

لاحظ أن استعلامات الأنماط للخصائص المخصصة لا تعمل على فايرفوكس اعتبارًا من اليوم (2025/11/14).