企业官网建设流程全解析

• 前端
• UI组件
• 跨平台

导读

品牌色（Brand Colors）是决定一个网站/应用视觉识别最核心的第一步，而 Quasar 的 Theme Builder 正是为此设计的交互式工具：它内嵌在官方文档页面中，允许你点击调色板按钮实时替换九个品牌色的取值，并在模拟的 Quasar 页面布局中即时预览效果，最后通过底部的Export按钮一键导出为 Sass、SCSS、Quasar CLI 配置或 UMD 初始化代码。读完本文，你将掌握 Theme Builder 的完整操作流程、四种导出格式的区别与落盘位置，以及它在底层依赖的setCssVar、CSS 自定义属性与亮度判定机制，从而在自己的项目中熟练定制与动态切换主题。

Theme Builder 是什么：品牌色的第一步

网站或应用最需要建立的就是“品牌”。官方文档 theme-builder.md 明确点出它的定位：“选择一个品牌色方案正是 Theme Builder 帮你完成的事情”。它是打造品牌的第一步——先把品牌色定下来，之后组件、页面、插件的所有视觉细节都会以这组颜色为准则自动统一。

这个工具并不是独立页面，而是由文档页面直接挂载的交互式 Vue 组件 ThemePicker.vue 提供：文档通过<ThemePicker class="q-py-lg" />将其渲染进页面，左侧是一排品牌色按钮，右侧是一个用 Quasar 组件搭建的“模拟应用页面”，用于实时展示配色效果。

基本操作流程

官方文档给出的用法非常直接：

1. 点击彩色按钮：点击布局旁边（左侧）的彩色按钮，选择某个品牌色。
2. 在弹窗中取色：每个按钮都绑定了q-menu+q-color，点击后弹出取色器，选择新颜色即生效。
3. 实时预览：右侧模拟页面上的顶部导航栏、卡片、浮动按钮等元素会立刻应用新颜色。
4. 点击Export导出：配色满意后，点击底部的Export按钮，在弹窗中选择目标格式并复制代码。

九大品牌色与默认取值

Theme Builder 可调的品牌色共 9 个，源码 ThemePicker.vue 中colors与list两个变量给出了完整清单与默认值：

这九种颜色与 color-palette.md 中“Brand Colors”一节完全一致：Quasar 组件使用的颜色与这八个/九个颜色强绑定，修改默认值后组件会立刻跟随这些颜色变化。模拟页面中右侧卡片区域还专门展示了secondary、dark、positive、negative、info、warning六种颜色卡片（见sideColors数组），方便判断它们在真实卡片上的呈现。

此外，模拟页面顶部工具栏有一个“Dark page”开关（darkMode），打开后页面背景切换为--q-dark-page对应的深色（见样式theme-picker__bg-dark），可同时验证深色模式下品牌色的表现。

Export 导出：四种格式的完整代码

点击Export后弹出对话框，包含四个选项卡，分别对应四种使用场景。以下代码均来自 ThemePicker.vue 中sassExport、scssExport、quasarCliExport、umdExport四个计算属性，颜色值占位符即你刚才在面板中选定的颜色。

1. Sass（.sass缩进语法）

对应src/css/quasar.variables.sass文件（仅适用于 Quasar CLI 管理的项目）：

// src/css/quasar.variables.sass $primary : #1976d2 $secondary : #26A69A $accent : #9C27B0 $dark : #1d1d1d $dark-page : #121212 $positive : #21BA45 $negative : #C10015 $info : #31CCEC $warning : #F2C037

2. SCSS（.scss语法）

对应src/css/quasar.variables.scss文件，与 Sass 版本内容等价、仅多分号：

// src/css/quasar.variables.scss $primary : #1976d2; $secondary : #26A69A; $accent : #9C27B0; $dark : #1d1d1d; $dark-page : #121212; $positive : #21BA45; $negative : #C10015; $info : #31CCEC; $warning : #F2C037;

关于该文件的使用细节，sass-scss-variables.md 中有几条重要约定：

• 两个文件二选一即可（.sass与.scss任一存在），其中的变量会提供给所有项目内的.sass、.scss及.vue文件；
• 若两者同时存在，Quasar CLI 优先使用quasar.variables.scss，其次才是.sass，两者都没有则回退到预编译的 Quasar CSS；
• 新建或删除该文件后需要重启 dev server 才会生效；仅修改文件内容则无需重启；
• 当文件只包含变量声明（无 mixin、函数、@import等）时，Quasar 会只向每个样式块注入其实际用到的变量，显著加速 Sass 编译（Quasar v2.24+ / @quasar/vite-plugin v2 / @quasar/app-vite v3.4+）。

3. Quasar CLI（quasar.config 配置）

对应 Quasar CLI / Quasar Vite 插件项目中的quasar.config文件：

// quasar.config file return { framework: { config: { brand: { primary: '#1976d2', secondary: '#26A69A', accent: '#9C27B0', dark: '#1d1d1d', 'dark-page': '#121212', positive: '#21BA45', negative: '#C10015', info: '#31CCEC', warning: '#F2C037' } } } }

4. Quasar Vite Plugin / UMD

对应不使用构建工具配置、直接在入口处初始化 Quasar 的场景（UMD 或手动装配 Vite 插件的项目）：

app.use(Quasar, { config: { brand: { primary: '#1976d2', secondary: '#26A69A', accent: '#9C27B0', dark: '#1d1d1d', 'dark-page': '#121212', positive: '#21BA45', negative: '#C10015', info: '#31CCEC', warning: '#F2C037' } } })

底层原理：选择颜色后发生了什么

Theme Builder 的实时预览并非“重编译”，而是依赖 Quasar 的 CSS 自定义属性（CSS Variables）机制，这也是动态主题能够零成本生效的根本原因。

setCssVar：写入--q-*变量

在 ThemePicker.vue 中，每个颜色被修改时都会触发update(color, val)：

function update(color, val) { setCssVar(color, val, document.getElementById('theme-picker')) dark[color] = luminosity(val) <= 0.4 }

setCssVar是 Quasar 导出的官方工具函数，其完整实现位于 set-css-var.js，核心只有一行：

element.style.setProperty(`--q-${propName}`, value)

即把primary写入为--q-primary，dark-page写入为--q-dark-page，依此类推。所有 Quasar 组件的样式都消费这些--q-*变量，因此改一个变量，整个组件库的配色随之联动。调用时传入的第三个参数document.getElementById('theme-picker')把变量限定在构建器自身的作用域内，避免污染整个文档页面——这也是setCssVar(colorName, colorValue[, element])第三个可选参数（默认document.body）的典型用法。

运行时动态换肤的完整说明可参考 color-palette.md 的 “Dynamic Change of Brand Colors” 一节，那里还介绍了配套的getCssVar读取工具，以及用原生 JS 的等价写法：

// 等价于 setCssVar('primary', '#0273d4') document.body.style.setProperty('--q-primary', '#0273d4')

luminosity：自动判断前景文字用黑还是白

update()中的另一行dark[color] = luminosity(val) <= 0.4用于自动决定该颜色上应该放白色文字还是黑色文字。luminosity来自 Quasar 的 colors.js 工具，它按 WCAG 标准计算颜色的相对亮度：

export function luminosity(color) { // ...将 sRGB 通道线性化后加权： return 0.2126 * R + 0.7152 * G + 0.0722 * B }

在 ThemeBuilder 的模板中，这个判断被用在按钮文字与卡片文字上，例如:text-color="dark[color] ? 'white' : 'black'"和卡片上的text-${dark[color] ? 'white' : 'black'}。也就是说，当你选了一个很亮的颜色，构建器自动切换为深色文字，保证可读性；阈值 0.4 是源码中写死的判定线。该文件还导出了lighten、brightness、blend、changeAlpha等完整的颜色工具，可用于在品牌色基础上派生更多辅助色。

应用侧：brand 配置如何落地

如果你把导出的brand配置写入quasar.config或app.use(Quasar, ...)，运行时 Quasar 会在安装阶段自动应用它。从 Body.js 的源码可以看到setColors(brand)的实现：

function setColors(brand) { for (const color in brand) { setCssVar(color, brand[color]) } }

即在插件安装时遍历config.brand的每个键，统一写入--q-*CSS 变量；同时还会把变量以行内样式形式注入根元素（源码中可见--q-${key}:${brand[key]}的拼接逻辑）。这与 Theme Builder 在编辑时使用的setCssVar是同一套机制——构建器预览的，正是你项目中实际会生效的效果。

在真实项目中使用导出的主题

综合 theme-builder.md、color-palette.md 与 sass-scss-variables.md，推荐的应用路径有三种：

• 静态定制（Quasar CLI）：把 Sass 或 SCSS 导出内容写入src/css/quasar.variables.sass/.scss。文件只需包含变量声明即可享受“按需注入变量”的编译加速。
• 初始化配置：把brand对象写入quasar.config的framework.config.brand，或 UMD 项目在app.use(Quasar, { config: { brand } })中传入，适合不希望依赖 Sass 文件的场景。
• 动态换肤：品牌色随时可通过setCssVar在运行时切换，例如在 Boot 文件中读取 API 返回的配色后再设置（color-palette.md 提供了defineBoot示例）；由于变量遵循 CSS 继承规则，你也可以只在html或body上覆盖所需颜色，删除自定义值即可还原默认主题。

小结

Theme Builder 把“选品牌色”这一设计决策变成了可视化的即改即见流程，并覆盖了从 Sass 变量、构建配置到运行时 API 的全部落地方式。其背后是 Quasar 统一的 CSS 自定义属性体系（--q-*变量 +setCssVar）和基于亮度（luminosity）的对比度自动判定。理解这层机制后，你不仅能用好这个构建器，还能在此基础上实现多主题切换、远程下发配色等更复杂的需求。相关扩展阅读：Color Palette 文档、Sass/SCSS 变量文档、构建器组件源码 ThemePicker.vue。

• 前端
• UI组件
• 跨平台