HTML没有变量机制，主题切换实际依赖CSS自定义属性（如--color-bg），由JS通过style.setProperty()动态更新，HTML仅通过class或data-theme提供触发标识。

HTML 本身没有变量机制，所谓“HTML 变量”其实是误称；真正支撑主题切换的是 CSS 自定义属性（CSS Custom Properties），它们运行在 CSS 层，由 JavaScript 驱动读写，HTML 只负责承载 class 或 data-theme 这类触发标识。

为什么不能用 HTML 属性当“变量”存主题色？

HTML 的 data- 属性（比如 data-primary-color="#3b82f6"）看起来像变量，但浏览器不会自动把它映射到样式上。它只是静态字符串，不参与 CSS 计算，也不响应变化——你改了 dataset.primaryColor，页面颜色纹丝不动。

常见错误现象：

• 在 JS 中修改 document.documentElement.dataset.theme = "dark"，但没同步更新任何 CSS 规则 → 主题无反应
• 把颜色值硬编码在 style 属性里（如
  ），导致无法批量切换、难以维护

  CSS 自定义属性才是主题切换的实际载体

  --color-bg、--color-text 这类以 -- 开头的属性，是真正的运行时变量：可继承、可被 var(--color-bg) 引用、可通过 JS 动态修改 style.setProperty() 更新，且所有依赖它的样式会立即重绘。

  典型用法：

  

  DeepBI DHTML 页面生成器

  生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur

  下载

  :root {
    --color-bg: #ffffff;
    --color-text: #1e293b;
  }
  
  @media (prefers-color-scheme: dark) {
    :root {
      --color-bg: #0f172a;
      --color-text: #f1f5f9;
    }
  }
  
  body {
    background-color: var(--color-bg);
    color: var(--color-text);
  }

  关键点：

  • 必须定义在 :root 或带主题 class 的选择器下（如 .theme-dark :root）
  • JS 切换时操作的是 document.documentElement.style，不是 HTML 属性
  • 不要在 @media 外覆盖暗色值，否则系统偏好失效

  HTML class 和 data-theme 是开关，不是变量容器

  class="theme-dark" 或 data-theme="dark" 的作用只有一个：作为 CSS 选择器的锚点或 JS 查询条件。它们本身不存储颜色、不计算值，只是信号。

  推荐做法：

  • 用 class 控制主题（语义清晰、支持层叠、便于调试）
  • 用 data-theme 仅作状态标记（例如供 analytics 或 SSR 读取）
  • 避免混合使用：class="theme-dark" 和 data-theme="light" 同时存在会导致逻辑混乱
  • 初始化时 JS 应优先读取 localStorage，再 fallback 到 matchMedia，最后写入 document.documentElement.className

  最容易被忽略的是 CSS 自定义属性的作用域链和继承时机——它们不是全局常量，而是随元素继承动态求值的；如果某个子元素被显式设置了 all: unset 或 inherit: false，主题变量就会中断。调试时别只看 JS 是否执行，更要检查 computed styles 里 var(--xxx) 是否已解析为实际值。

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！