在你的主题中使用 Discourse 核心变量

Discourse 的可定制性极强!

本主题旨在向您展示如何充分利用作为主题开发者可用的所有精彩选项。您知道……这样您就不必重新发明轮子了 :smile:

变量?什么变量?

变量涵盖了许多方面,从字体大小到颜色,再到 z-index 值。您可以在主题编辑器中使用和覆盖绝大部分变量。

颜色

有大量的颜色可供您在主题中使用或覆盖。您可以在管理界面的“自定义” > “颜色”下查看基本颜色集。以下是默认配色方案的截图:

这些颜色作为 CSS 自定义属性提供,您可以使用以下语法对其进行使用和覆盖:

var(--primary)
var(--secondary)
var(--tertiary)
var(--quaternary)
var(--header_background)
var(--header_primary)
var(--highlight)
var(--danger)
var(--success)
var(--love)

:warning: 使用 SCSS 颜色变量(如 $primary、$secondary 等)已被弃用。Discourse 核心自 2020 年 8 月起使用 CSS 自定义属性,我们建议所有现有主题将 SCSS 变量切换为 CSS 自定义属性。有关复杂的颜色操作,请参阅本指南。

那么,我该如何使用它们呢?

首先,创建一个新主题,或者如果您使用的是基于 Git 的主题,则创建一个新主题组件并将其添加到您的主题中。

假设我想将 <body> 的背景设置为匹配当前配色方案的 highlight 颜色。我可以这样做:

body {
  background: var(--highlight);
}

颜色将自动从当前配色方案中提取,如下所示:

(不推荐将此背景颜色用于实际用途 :sweat_smile:)

现在,假设当前主题的配色方案未设置为“浅色方案”。相反,假设它设置为默认的“深色”方案,同样的代码会产生不同的结果,因为变量值不同了。

您可以看到 <body> 的背景始终遵循当前配色方案的 highlight 变量,无论其具体值为何。

这就涵盖了基本的颜色变量。Discourse 还使用可被使用或覆盖的衍生颜色。您可以在浏览器检查器中查看当前配色方案的完整颜色列表,以下是默认主题的截图:

请注意,您可以在任何 Discourse 实例上检查这些颜色,无需身份验证。在您自己的 Discourse 实例上,您可以(且应该)使用现已包含在核心中的样式指南插件。启用它并访问 /styleguide,您将看到所有 Discourse UI 元素,包括颜色:

(上面展示的是“Grey Ember”配色方案。)

好的,接下来进入更高级的主题:


高级变量

请查看 Discourse 仓库中的此文件:

这是定义大多数变量的地方。与颜色一样,这些变量在主题样式表中神奇地为您提供使用。

我将尝试在下面分解该文件的内容:

宽度

$small-width: 800px !default;
$medium-width: 995px !default;
$large-width: 1110px !default;

如果您希望主题匹配 Discourse 原生行为,这些变量非常有用,特别是在媒体查询中。例如,请查看 .user-info 预编译 SCSS 的相关部分:

.user-info {
  &.medium {
    flex: 0 0 32%;
    margin: 0 2% 4vh 0;
    @media screen and (max-width: $small-width) {
      flex: 0 0 48%;
      margin-right: 0;
    }
  }
}

请注意,媒体查询接收一个变量来确定小屏幕的截止点并应用不同的样式。


字体

--base-font-size: 0.938em; // eq. to 15px
--base-font-size-larger: 1.063em; // eq. to 17px
--base-font-size-largest: 1.118em; // eq. to 19px

// Font-size definitions, multiplier ^ (step / interval)
--font-up-6: 2.296em;
--font-up-5: 2em;
--font-up-4: 1.7511em;
--font-up-3: 1.5157em;
--font-up-2: 1.3195em;
--font-up-1: 1.1487em; // 2^(1/5)
--font-0: 1em;
--font-down-1: 0.8706em; // 2^(-1/5)
--font-down-2: 0.7579em; // Smallest size we use based on the 1em base
--font-down-3: 0.6599em;
--font-down-4: 0.5745em;
--font-down-5: 0.5em;
--font-down-6: 0.4355em;

这也相当直观,Discourse 有一个很棒字体缩放系统,因此您应该利用它。

使用的单位是 em,因此它们是相对于用于 <html> 元素的 --base-font-size 的。

所以:

.btn {
  font-size: var(--font-up-6);
}

编译后为:

(–base-font-size _ --font-up-6) 或 (14px _ 2.296) = 32.14px

或者这个:


行高

--line-height-small: 1;
--line-height-medium: 1.2; // Headings or large text
--line-height-large: 1.4; // Normal or small text

这些变量的使用方式与前面的示例相同。请注意,它们是无单位值。这意味着什么:

Z-index 值

$z-layers: (
  "max": 9999,
  "fullscreen": 1700,
  "modal": (
    "tooltip": 1600,
    "popover": 1500,
    "dropdown": 1400,
    "content": 1300,
    "overlay": 1200,
  ),
  "mobile-composer": 1100,
  "header": 1000,
  "tooltip": 600,
  "composer": (
    "popover": 500,
    "content": 400,
  ),
  "dropdown": 300,
  "usercard": 200,
  "timeline": 100,
  "base": 1,
);

这些可以按如下方式讨论使用:

div {
  z-index: z("header");
}

“或者当嵌套时,像这样:”

div {
  z-index: z("modal", "dropdown");
}

“您也可以执行基本的数学运算,如预期:”

div {
  z-index: z("base") + 1;
}

上述代码块是引用的一部分,但我将其移出以进行格式化

现在这里有一个示例:

将盒子放在头部上方:

.zbox {
  position: fixed;
  top: 0;
  left: 0;
  height: 200px;
  width: 200px;
  background: red;
  z-index: z("header") + 1;
}

将盒子放在头部下方:

.zbox {
  position: fixed;
  top: 0;
  left: 0;
  height: 200px;
  width: 200px;
  background: red;
  z-index: z("header") - 1;
}


盒阴影

$box-shadow: (
  "modal": 0 8px 60px rgba(0, 0, 0, 0.6),
  "composer": 0 -1px 40px rgba(0, 0, 0, 0.12),
  "menu-panel": 0 6px 14px rgba(0, 0, 0, 0.15),
  "card": 0 4px 14px rgba(0, 0, 0, 0.15),
  "dropdown": 0 2px 3px 0 rgba(0, 0, 0, 0.2),
  "header": 0 2px 4px -1px rgba(0, 0, 0, 0.25),
  "kbd": (
    0 2px 0 rgba(0, 0, 0, 0.2),
    0 0 0 1px dark-light-choose(#fff, #000) inset,
  ),
  "focus": 0 0 6px 0 $tertiary,
  "focus-danger": 0 0 6px 0 $danger,
);

您可以大致看到,在变量方面,大部分工作已经为您完成了,在大多数情况下,您只需利用现有的内容。

盒阴影的用法如下:

.d-header {
  box-shadow: shadow("focus");
}

这应该使头部使用 focus 盒阴影。如果我们进行检查确认:


本帖为 Wiki,请根据需要编辑 :wink:


本文档受版本控制 - 请在 github 上建议修改。

45 个赞