CSS @container style 查询怎样按主题变量切换样式

我第一次把主题切换从一组全局选择器里拆出来时，最容易混淆的是“按容器尺寸查询”和“按容器样式查询”。如果目标只是让后代组件根据父级的主题变量换一套颜色，真正需要的是 @container style()，而不是尺寸容器查询。

官方资料：https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Containment/Container_size_and_style_queries

这篇只解决一个问题：父容器声明 --theme: dark 或 --theme: light 后，后代组件怎样按这个自定义属性切换样式。当前实用范围应优先放在 CSS 自定义属性上；普通 CSS 声明的 style 查询仍要以目标浏览器兼容表为准。

先给组件一套不依赖查询的默认变量

回退样式要先成立。这样即使浏览器没有应用 style 查询，卡片仍然有背景色、文字色和边框，而不是把主题切换变成组件可用性的前置条件。

.theme-card {
  /* 默认主题保证未命中查询时仍然可读 */
  --theme: light;
  --surface: #ffffff;
  --text: #1f2937;
  --border: #d1d5db;

  color: var(--text);
  background: var(--surface);
  border: 1px solid var(--border);
}

.theme-card[data-theme="dark"] {
  /* 主题标记只负责改变容器上的自定义属性 */
  --theme: dark;
}

这里没有把所有颜色直接写进 data-theme 选择器。容器只提供语义标记，具体组件可以在自己的 style 查询里决定如何解释这个标记。

用 @container style(--theme: dark) 让后代组件换色

style 查询读取的是容器的计算样式。自定义属性会沿着树继承，所以 .theme-card 上的 --theme 可以作为后代规则的条件；被条件规则直接设置的对象应当是后代元素，而不是查询容器本身。

@container style(--theme: dark) {
  .theme-card__body {
    /* 深色主题只覆盖变量，组件结构保持不变 */
    --surface: #111827;
    --text: #f9fafb;
    --border: #374151;
  }

  .theme-card__meta {
    /* 次要文字也从同一组变量取值 */
    color: #cbd5e1;
  }
}

@container style(--theme: light) {
  .theme-card__body {
    /* 明确写出 light 便于和未来的其它主题值区分 */
    --surface: #ffffff;
    --text: #1f2937;
    --border: #d1d5db;
  }
}

查询中的 style(--theme: dark) 是“自定义属性的值等于 dark”的纯文本匹配。它不需要给元素额外设置尺寸容器类型；style 查询关注的是样式特征，而不是容器宽度。

主题关键词用冒号，数值条件才用范围语法

dark、light、compact 这类词是主题标签，使用冒号形式最直观：

@container style(--theme: dark) {
  /* 关键词比较：dark 是一个主题值，不是数值 */
  .theme-card__title {
    color: var(--text);
  }
}

如果自定义属性保存的是数量，例如列数或间距，才使用 =、>= 这类范围语法：

@container style(--density = 2) {
  .theme-card__body {
    /* 数值条件用于紧凑程度，不要拿它替代 dark/light 关键词 */
    padding: 0.75rem;
  }
}

因此不要把主题条件写成 style(--theme = dark)。范围比较需要可解析的数值类型，关键词主题应保留冒号。另一个常见误区是写成 style(var(--theme): dark)：查询左侧应是自定义属性名，不能用 var() 代替。

多个标记可以组合，但变量回退仍要放在查询外

一个组件可能同时有主题和密度两个维度。可以用 and 或 or 组合 style 条件，基础变量则留在普通规则中：

.theme-card__body {
  /* 查询未命中时的稳定回退 */
  padding: 1rem;
  background: var(--surface);
  color: var(--text);
}

@container style(--theme: dark) and style(--density: compact) {
  .theme-card__body {
    /* 两个自定义属性同时满足时才采用紧凑深色变体 */
    padding: 0.75rem;
    border-radius: 0.5rem;
  }
}

@container style(--theme: dark), style(--theme: dim) {
  .theme-card__body {
    /* or 适合把多个主题值映射到同一组视觉变量 */
    --surface: #111827;
    --text: #f9fafb;
  }
}

这种写法的取舍很明确：普通规则负责“没有查询也能用”，style 查询负责“命中主题后替换变量或局部细节”。不要把唯一的文字颜色只放进查询块，否则降级环境可能出现对比度问题。

把它整理成可复用的最小完整片段

下面这段把父容器、默认变量、主题值和后代匹配放在一起。实际项目里可以把 data-theme 换成组件状态、页面主题上下文或服务端输出的属性。

.theme-card {
  /* 父容器提供主题语义，默认值也在这里 */
  --theme: light;
  --surface: #ffffff;
  --text: #1f2937;
  --border: #d1d5db;
  color: var(--text);
  background: var(--surface);
  border: 1px solid var(--border);
}

.theme-card[data-theme="dark"] {
  /* 只改主题标记，颜色交给 style 查询统一处理 */
  --theme: dark;
}

.theme-card__body {
  /* 后代默认读取继承来的变量 */
  padding: 1rem;
  color: var(--text);
  background: var(--surface);
}

@container style(--theme: dark) {
  .theme-card__body {
    /* 命中深色主题后覆盖同名变量 */
    --surface: #111827;
    --text: #f9fafb;
    --border: #374151;
  }
}

兼容和排查时先看这几个点

• 先确认主题值写在被查询的祖先容器上，并且拼写完全一致；Dark 和 dark 不应当当作同一个标记。
• 关键词比较使用冒号，不要用数值范围运算符替换它；数值条件和主题字符串是两种不同的意图。
• 把默认颜色、间距和边框放在查询外，查询块只做增强或覆盖，降级就能保留基本可用性。
• 如果需要查询普通 CSS 属性而不是自定义属性，先查目标浏览器的兼容说明；本文的稳妥方案只依赖 --theme 这类自定义属性。
• 不要让查询规则反过来修改正在作为查询条件的同一个容器样式，避免形成难以推断的样式依赖。

最后的判断

按主题变量切换样式的最小思路是：父容器声明语义化的 --theme，普通规则提供默认变量，@container style(--theme: dark) 只为后代覆盖需要改变的变量。这样主题条件与组件结构解耦，关键词匹配也不会和尺寸查询混在一起。

相关问题

• style 查询必须设置 container-type 吗？ 只做自定义属性 style 查询时，不必为了尺寸查询额外设置 container-type。
• 为什么 style(--theme = dark) 不适合主题？ 范围形式面向可解析的数值类型，主题关键词应使用冒号匹配。
• 不支持 style 查询时怎么办？ 把默认变量和基础可读样式放在普通选择器中，把查询块当作增强层。