CSS 容器样式查询怎么读取自定义属性

CSS 容器样式查询读取的不是子元素自己的属性，而是最近的父级样式查询容器上的 CSS 自定义属性。最小写法是 @container style(--card-mode: compact)：当祖先容器的计算值匹配 compact 时，规则内的子元素就会切换样式。样式查询不需要像尺寸查询那样设置 container-type，但尺寸条件仍然需要尺寸容器。

先建立父容器到子组件的状态契约

把主题、密度或交互状态放在组件容器上，子组件只关心状态名。下面的例子用 --card-mode 表示卡片密度，默认值先提供紧凑布局，只有显式指定 roomy 时才放大间距。

/* 先给不支持容器样式查询的浏览器一个可用默认值 */
.card-shell {
  --card-mode: compact;
}

/* 组件本身不依赖视口宽度，状态由父容器传入 */
.card {
  padding: 12px;
  gap: 8px;
}

.card-shell[data-mode="roomy"] {
  --card-mode: roomy;
}

这里的 data-mode 只是状态输入方式，换成主题类名或内联自定义属性也可以。关键是让状态落在包含卡片的祖先元素上，避免每个卡片重复维护一套判断。

用 style() 匹配自定义属性的计算值

在支持样式查询的浏览器中，可以直接写带值的查询。下面的规则只在最近容器的 --card-mode 计算值为 roomy 时生效。

/* style() 读取父容器的自定义属性，不读取 .card 自己的属性 */
@container style(--card-mode: roomy) {
  .card {
    padding: 20px;
    gap: 14px;
    border-radius: 16px;
  }
}

/* 只关心属性是否被设置时，可以省略冒号和值 */
@container style(--has-accent) {
  .card-title {
    color: var(--accent-color, #1457d9);
  }
}

带值形式适合枚举状态；无值形式适合“是否开启”这种开关。查询条件只负责选择规则，真正的颜色、间距等表现仍然放在普通声明中，便于维护。

计算值、继承和 @property 是最容易误判的边界

自定义属性默认会继承，所以子卡片通常能沿祖先链读到 --card-mode。但查询比较的是容器的计算值，不是源码中写过的字符串。尤其是带值查询，未注册的自定义属性会按原 token 进行匹配；两个看起来等价的颜色写法不一定被当成同一个值。

/* 注册后，颜色值可以按 color 语法参与计算 */
@property --accent-color {
  syntax: "";
  inherits: true;
  initial-value: #1457d9;
}

.card-shell {
  --accent-color: rgb(20 87 217);
}

/* 这里查询注册后的颜色计算值 */
@container style(--accent-color: #1457d9) {
  .card-title {
    font-weight: 700;
  }
}

如果只是枚举 compact、roomy，不要为了查询额外注册属性；把状态值保持为稳定的短 token 更直观。需要颜色、长度等类型归一化时，再考虑 @property。

把命名、尺寸与样式条件组合起来

组件嵌套后，未命名的查询可能命中距离最近但并非目标的容器。可以给外层容器命名，再把名称和样式条件放在同一个 @container 条件中。若同时加入宽度判断，外层还要声明 container-type: inline-size。

/* 命名后，查询只在 panel 容器范围内寻找 */
.panel {
  container: panel / inline-size;
  --card-mode: roomy;
}

/* 先判断名字，再同时判断尺寸与样式状态 */
@container panel (min-width: 480px) and style(--card-mode: roomy) {
  .card-grid {
    grid-template-columns: repeat(2, minmax(0, 1fr));
  }
}

命名解决“查哪个容器”，尺寸条件解决“容器有多宽”，样式条件解决“容器处于什么状态”。三者职责不同，混写时先分别确认容器链和条件是否成立。

上线前的兼容与排查清单

最终可以在浏览器兼容性面板中确认 @container 的支持范围，并用一个固定的 --card-mode 值做最小复现。不要把样式查询误当作 JavaScript 读取器：它只能选择 CSS 规则，不能把自定义属性值返回给脚本。

常见问题

CSS 容器样式查询必须设置 container-type 吗？

只做样式查询时通常不必设置。需要查询容器尺寸、滚动状态或锚定状态时，再按对应条件声明容器类型。

为什么 @container style(--mode) 能匹配未注册变量？

未注册自定义属性只要被赋值，省略值的样式查询就能判断它不是初始状态；带值查询则需要计算值与目标值匹配。

能不能用 var(--mode) 写在 style() 里？

不能把 var() 当成容器查询参数。应直接写要匹配的自定义属性名和值，并把变化留给容器上的状态契约。