優(yōu)維低代碼：Theme -u0026 Mode 頁面主題和模式（優(yōu)維 cmdb）
優(yōu)維低代碼技術專欄，是一個全新的、技術為主的專欄，由優(yōu)維技術委員會成員執(zhí)筆，基于優(yōu)維7年低代碼技術研發(fā)及運維成果，主要介紹低代碼相關的技術原理及架構邏輯，目的是給廣大運維人提供一個技術交流與學習的平臺。
連載第三十一期
《高級指引：Theme & Mode 頁面主題和模式》
▽
⊙ NOTE
Brick Next 從 2.7.1 開始支持頁面主題和模式。
Brick Next 支持兩種主題：light 和 dark（默認為 light），以及兩種模式：default 和 dashboard（默認為 default）。
在 dark 深色主題下，頁面框架及構件將以深色背景樣式顯示。而在 dashboard 大屏模式下，系統(tǒng)的頁面頂欄及側(cè)欄將消失，同時配合 basic-bricks.micro-view 開啟 dashboardMode: true 可以實現(xiàn)大屏效果。
目前主要在“大屏”場景下使用，注意該場景需要同時啟用深色主題和大屏模式。
# 微應用編排：切換主題和模式
例如在 Storyboard 編排中，希望某個按鈕點擊后切換到“深色 大屏”場景，可以如下配置：
brick: "your-button"events: click: - action: "theme.setDarkTheme" - action: "mode.setDashboardMode"
每當頁面初始進入、或發(fā)生跳轉(zhuǎn)并重新渲染前，系統(tǒng)將自動切回淺色主題和默認模式，但系統(tǒng)開放了一個窗口期 onBeforePageLoad，以支持頁面可以設置初始化為深色主題及大屏模式。
例如假設我們希望 URL 中攜帶參數(shù) mode=dashboard 時自動使用深色主題和大屏模式，可以如下配置：
brick: "basic-bricks.micro-view"lifeCycle: onBeforePageLoad: - if: "<% QUERY.mode === 'dashboard' %>" action: "theme.setDarkTheme" - if: "<% QUERY.mode === 'dashboard' %>" action: "mode.setDashboardMode"properties: dashboardMode: "<% QUERY.mode === 'dashboard' %>"
注意 basic-bricks.micro-view 構件在大屏模式下會多一個退出按鈕，點擊后將發(fā)出 mode.dashboard.exit 事件，需要用戶自行配置退出大屏需要執(zhí)行的動作。例如通常應添加如下事件配置：
brick: "basic-bricks.micro-view"events: mode.dashboard.exit: - target: "_self" properties: dashboardMode: false - action: "theme.setLightTheme" - action: "mode.setDefaultMode"
不內(nèi)置退出動作的原因是，用戶可以通過其他方式退出大屏，例如通過 history.pushQuery 跳轉(zhuǎn)重置 mode=dashboard 參數(shù)來實現(xiàn)退出大屏模式：
brick: "basic-bricks.micro-view"events: mode.dashboard.exit: - action: "history.pushQuery" args: - mode: null
⊙ IMPORTANT
不要在編排中為構件配置固定的顏色值，而應使用系統(tǒng)預定義的 css custom properties，具體可以參考本文下一節(jié)內(nèi)容。
# 構件開發(fā)：適配深色主題和大屏模式
系統(tǒng)通過定義一系列 CSS custom properties（又稱 CSS variables）來實現(xiàn)主題樣式的實時無縫切換，無論在編排或構件開發(fā)時應首先嘗試使用這些屬性。具體屬性列表可以參考這里的源碼。
系統(tǒng)當前的主題和模式反饋在<html>元素的 data-theme 及 data-mode 屬性上，因此僅使用 css 即可完成大部分深色主題和大屏模式的適配。例如：
.your-class { color: black;}html[data-theme="dark"] .your-class { color: white;}
當使用系統(tǒng)預定義的 CSS custom properties 時，則無需額外配置 html[data-theme="dark"] 樣式：
.your-class { color: var(--text-color-default);}
有時候構件需要在 JavaScript 中判斷當前主題或模式，例如圖表類構件需要根據(jù)當前主題來生成不同的顏色列表，對此系統(tǒng)提供了 React Hooks useCurrentTheme 和 useCurrentMode 來獲取當前的主題和模式，例如：
import { useCurrentTheme } from "@next-core/brick-kit";function YourComponent() { const theme = useCurrentTheme(); const colors = theme === "dark" ? ["red", "green"] : ["blue", "orange"]; return <YourChart colors={colors} />;}
# 適配公共 UI 規(guī)范樣式
使用 Less
Brick Next 的 UI 底層基于 Ant Design，在適配我們自己的 UI 規(guī)范相關的樣式時，應結合 Ant Design 的底層技術 Less 的能力，盡量通過使用或覆蓋已有的 Less 預定義變量值來實現(xiàn)樣式更新，而不是使用固定的顏色值。例如：
// ? Good:// In `packages/custom-antd-styles/src/var.less`:@link-hover-color: #0071eb;// ? Bad:// In `packages/custom-antd-styles/src/link.less`a:hover { color: #0071eb;}
// ? Good:// In `bricks/your-brick/src/style.less`:.your-class { color: @link-hover-color;}// ? Bad:// In `bricks/your-brick/src/style.less`.your-class { color: #0071eb;}
Brick Next 的 Antd Less 變量統(tǒng)一管理在 next-core 倉庫的 packages/custom-antd-styles/src/var.less 中。
# 使用 CSS Variables
由于 Less 的處理發(fā)生在編譯階段，無法在運行時提供切換變量的能力，因此為了實現(xiàn)運行時深色主題的自由切換，我們還需要結合使用 CSS custom properties（又稱 CSS variables）。
對于色值一類的樣式（例如 color: #fff）通常需要為默認主題和深色主題配置不同的色值，此時，我們可以將 Antd 中對應的 Less 變量設置為 CSS variables，并針對不同主題分別設置不同的色值。例如：
// In `packages/custom-antd-styles/src/var.less`:@text-color: var(--antd-text-color);
/* In `packages/brick-container/src/styles/variables.css`: */:root { --antd-text-color: rgba(0, 0, 0, 0.85);}html[data-theme="dark"] { --antd-text-color: #c6cfd9;}
⊙ NOTE
注意我們統(tǒng)一使用 –antd- 作為前綴加上對應的 Antd Less 變量名作為 Antd 相關的 CSS variable name。
Brick Next 的 CSS variables 統(tǒng)一管理在 next-core 倉庫的 packages/brick-container/src/styles/variables.css 中。
# 處理 Less 編譯報錯
由于 Antd 大量使用了色值計算（例如 darken(…) lighten(…) 等），這些計算無法兼容 CSS variable，因此有時當我們使用 CSS variable 作為 Less 的變量值時，構建 Less 可能會報錯，對此的解決方案是使用我們自定義的 LessReplacer 插件，將這些報錯的色值計算代碼進行替換。
例如：
// In `packages/less-plugin-css-variables/src/LessReplacer.js`:const rawStringMap = { "darken(@item-active-bg, 2%)": "var(--antd-item-active-bg-darken-2)",};
以上配置將把 Antd Less 文件中所有的 darken(@item-active-bg, 2%) 替換為 var(–antd-item-active-bg-darken-2)，注意變量命名方法為「–antd- 前綴 Antd Less 變量名 方法名 參數(shù)值」。
又例如：
// In `packages/less-plugin-css-variables/src/LessReplacer.js`:const variableMap = { "table-header-sort-active-bg": true,};
以上配置將把 Antd Less 文件中所有的 @table-header-sort-active-bg: **;（假設 ** 為包含色值計算等導致 Less 編譯報錯的代碼）的定義替換為 @table-header-sort-active-bg: var(–antd-table-header-sort-active-bg)。
注意這些新增的 –antd-* 需要在 packages/brick-container/src/styles/variables.css 中寫好定義。
