React 响应式布局 Container Queries 集成

各位同学，大家好！

欢迎来到今天的“React 响应式布局 Container Queries 集成”深度研讨会。我是你们的讲师，一个在代码世界里摸爬滚打多年的老司机。今天我们不聊虚的，也不搞那些“为了用而用”的架构设计，我们就来聊聊如何让你的组件学会“察言观色”——不是看浏览器窗口有多大，而是看它的“爸妈”（容器）到底有多大。

如果你还在用 @media (min-width: 768px) 这种老掉牙的写法，那就像是一个只会看天气预报的农民，不管地里庄稼长什么样，只要太阳出来就以为要收成。这很糟糕，真的。今天，我们要解锁的是 CSS 的新大陆——Container Queries（容器查询），以及它如何在 React 这个大熔炉里大放异彩。

第一部分：视口查询的“谎言”与容器查询的“真相”

首先，我们要承认一个残酷的现实：传统的响应式设计，本质上是一种“懒惰”的设计。

当你写 @media (min-width: 768px) 时，你的组件在问：“嘿，浏览器窗口是不是变宽了？”而不是问：“嘿，我的父容器是不是变宽了？”

这就导致了一个经典的场景：布局的断裂。

想象一下，你写了一个漂亮的 UserProfileCard 组件。在宽屏电脑上，它显示头像在左，信息在右。你把它放在一个侧边栏里，侧边栏隐藏了，卡片内容区变宽了，完美！
但是，当你把它放在手机的主内容区（侧边栏也隐藏了），卡片依然试图维持“头像左、信息右”的布局。结果就是，头像太小，文字挤成一团，或者布局崩坏。

为什么？因为组件不知道它的父容器被挤压了。它只知道“世界变宽了”，不知道“我的家变小了”。

Container Queries（容器查询） 就是来打破这个谎言的。它允许组件基于其父容器的大小来调整样式，而不是基于视口。

这就好比：

• 媒体查询：你问你的老板（浏览器窗口）：“老板，我现在能干活了吗？”老板说：“能。”然后你干活。
• 容器查询：你问你的同事（父容器）：“哥们，你这块地儿够不够我摆个办公桌？”同事说：“不够，你缩一缩。”然后你缩一缩。

第二部分：原生 CSS 的“魔法”语法

在 React 集成之前，我们得先看看 CSS 本身是怎么玩这个的。别怕，语法不难，就是有点绕。

1. 定义容器

首先，你得告诉浏览器，哪个元素是一个“容器”。这就像是你得给房子贴个标签：“此处可变宽”。

/* 假设这是一个卡片容器 */
.card-container {
  /* 关键属性：container-type */
  /* inline-size 表示基于容器内部宽度变化触发 */
  /* size 表示基于容器宽度和高度变化触发 */
  container-type: inline-size;

  /* 可选：给容器起个名字，方便针对性查询 */
  container-name: my-card;
}

/* 如果你想同时监听宽和高 */
/* container-type: size; */

2. 查询容器

接下来，当你的子组件（比如 CardHeader）想根据容器大小改变样式时，它就不再用 @media，而是用 @container。

/* 这里的 @container 相当于 @media */
/* 它的意思是：只要父容器是 my-card，且宽度大于 400px */
@container my-card (min-width: 400px) {
  .card-header {
    font-size: 1.5rem;
    color: #333;
    /* 变宽了，字体变大，布局变复杂 */
  }

  .card-body {
    /* 这里可以写更复杂的 Grid 布局 */
    display: grid;
    grid-template-columns: 1fr 1fr;
  }
}

/* 如果容器宽度小于 400px */
@container my-card (max-width: 399px) {
  .card-header {
    font-size: 1rem;
    color: #888;
    /* 变窄了，字体变小，布局简化 */
  }

  .card-body {
    display: block; /* 回到单列 */
  }
}

注意：这里的 @container 默认查询的是父级容器。如果你想查询更上层的容器，可以加个 @at- 前缀，比如 @at-viewport（虽然现在很少见）。

第三部分：React 的挑战——CSS 看不懂 React

好了，语法懂了。但是！React 是个动态的世界。CSS 是静态的，React 是动态的。这就好比你想教一个只会看书的文盲（CSS）去理解一个不停变魔术的魔术师（React）。

CSS 不知道 React 组件的 style 属性，也不知道 props 传了什么。CSS 只知道它看到的 DOM 节点。

那么，我们怎么在 React 里集成 Container Queries 呢？主要有三条路：原生 CSS 方案、CSS-in-JS 方案、第三方库方案。

路线一：原生 CSS + React 组件包装（最硬核）

这招就是“土法炼钢”。我们利用 React 的 style 属性来动态注入 CSS 变量，或者直接控制容器的宽度。

步骤 1：创建一个容器组件
我们需要一个组件，它负责渲染一个 div，这个 div 有 container-type，并且我们可以通过 props 传给它一个宽度限制。

// ContainerWrapper.js
import React from 'react';

const ContainerWrapper = ({ children, minWidth, maxWidth, style, className }) => {
  // 这里我们可以利用 CSS 变量或者直接内联样式来模拟容器约束
  // 在原生 CSS 中，container-type 通常直接写在类名上
  // 但为了演示 React 的控制力，我们动态设置 style
  const containerStyle = {
    ...style,
    containerType: 'inline-size', // 关键！告诉 CSS 这是一个容器
    // 注意：原生 CSS 属性通常不能直接在 style 对象里写，除非浏览器支持
    // 更好的做法是：这里只负责渲染容器，样式写在 CSS 文件里
    // 我们通过 className 来应用样式
  };

  return (
    <div 
      style={containerStyle} 
      className={`container-wrapper ${className}`}
    >
      {children}
    </div>
  );
};

export default ContainerWrapper;

步骤 2：在 CSS 文件里定义样式

/* ContainerWrapper.module.css */
.container-wrapper {
  /* 这一步最关键，必须显式声明 container-type */
  container-type: inline-size;
  container-name: my-app-container;
  width: 100%;
  border: 2px dashed #ccc;
  padding: 20px;
  box-sizing: border-box;
}

/* 当容器宽度大于 600px 时 */
@container my-app-container (min-width: 600px) {
  .react-component-a {
    background-color: lightblue;
    padding: 20px;
    /* 比如显示一个侧边栏 */
  }

  .react-component-b {
    float: right;
    width: 30%;
  }
}

/* 当容器宽度小于 600px 时 */
@container my-app-container (max-width: 599px) {
  .react-component-a {
    background-color: lightgreen;
  }

  .react-component-b {
    width: 100%;
    float: none;
  }
}

步骤 3：在 React 中使用

// App.js
import React from 'react';
import ContainerWrapper from './ContainerWrapper';
import ComponentA from './ComponentA';
import ComponentB from './ComponentB';

const App = () => {
  return (
    <div style={{ display: 'flex', gap: '20px', padding: '20px' }}>

      {/* 场景一：在宽屏下 */}
      <div style={{ width: '800px' }}>
        <h3>场景一：宽屏容器 (800px)</h3>
        <ContainerWrapper>
          <ComponentA />
          <ComponentB />
        </ContainerWrapper>
      </div>

      {/* 场景二：在窄屏下 */}
      <div style={{ width: '300px' }}>
        <h3>场景二：窄屏容器 (300px)</h3>
        <ContainerWrapper>
          <ComponentA />
          <ComponentB />
        </ContainerWrapper>
      </div>

    </div>
  );
};

export default App;

看懂了吗？ComponentA 和 ComponentB 完全不知道它们是在浏览器里，还是在 div 里。它们只关心它们的“容器”（ContainerWrapper）有多大。这就是解耦的极致！

第四部分：CSS-in-JS 的优雅——Emotion / Styled-Components

上面的原生方案虽然好，但每次都要写 .module.css 文件，还要手动管理 container-name，有点繁琐。而且，CSS-in-JS 库（如 Emotion 或 Styled-Components）通常能更好地处理作用域问题。

我们来看看怎么用 Emotion 实现容器查询。注意：Emotion 现在原生支持 @container 选择器了！

安装 Emotion：

npm install @emotion/react @emotion/styled

代码示例：

import React from 'react';
import styled from '@emotion/styled';

// 1. 定义一个容器组件
// 我们使用 'inline-size' 作为 container-type
const Container = styled.div`
  container-type: inline-size;
  container-name: grid-gallery;
  width: 100%;
  padding: 20px;
`;

// 2. 定义一个 GalleryItem 组件
// 这个组件完全不知道自己在哪里，只关心容器
const GalleryItem = styled.div`
  background: #eee;
  padding: 10px;
  border-radius: 8px;
  margin-bottom: 10px;

  /* 核心逻辑：基于容器宽度调整样式 */
  @container grid-gallery (min-width: 500px) {
    /* 容器够宽，我们变成 Grid 布局 */
    display: grid;
    grid-template-columns: repeat(2, 1fr);
    gap: 10px;

    &:last-child {
      grid-column: span 2; /* 最后一个占满两列 */
    }
  }

  @container grid-gallery (max-width: 499px) {
    /* 容器变窄，我们变回单列 */
    display: block;
    width: 100%;
  }
`;

// 3. 使用
const EmotionDemo = () => {
  return (
    <div>
      {/* 父容器宽度由浏览器窗口决定，比如 1000px */}
      <Container>
        <GalleryItem>Item 1</GalleryItem>
        <GalleryItem>Item 2</GalleryItem>
        <GalleryItem>Item 3</GalleryItem>
        <GalleryItem>Item 4</GalleryItem>
      </Container>
    </div>
  );
};

这有多酷？
想象一下，你写了一个 Button 组件。在宽容器里，它是一个带图标的水平按钮；在窄容器里，它是一个全宽的垂直按钮。你只需要在 Button 组件里写 @container，完全不用管父组件是 Sidebar 还是 Modal。

第五部分：Tailwind CSS 的极速响应——Container Queries Plugin

对于 Tailwind 的信徒来说，上面的 CSS-in-JS 语法可能有点太“原生”了。Tailwind 有一个官方插件：@tailwindcss/container-queries。

配置：

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

在 tailwind.config.js 中添加插件：

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./src/**/*.{js,jsx,ts,tsx}"],
  theme: {
    extend: {},
  },
  plugins: [
    // 引入这个插件
    require('@tailwindcss/container-queries'),
  ],
}

使用方法：

import React from 'react';

const TailwindDemo = () => {
  return (
    <div className="flex gap-4 p-4">
      {/* 容器 A：宽 */}
      <div className="w-[600px]">
        <h3>容器宽度 600px</h3>
        <div className="@container w-full border border-dashed">
          <CardComponent />
        </div>
      </div>

      {/* 容器 B：窄 */}
      <div className="w-[300px]">
        <h3>容器宽度 300px</h3>
        <div className="@container w-full border border-dashed">
          <CardComponent />
        </div>
      </div>
    </div>
  );
};

// CardComponent 组件
const CardComponent = () => {
  return (
    <div className="bg-white p-4 rounded shadow @sm:p-6 @md:p-8">
      {/* 
        @container 是 Tailwind 的容器查询前缀
        @sm: 对应 min-width: 640px (Tailwind 默认断点)
        @md: 对应 min-width: 768px
      */}
      <h2 className="text-lg @container @sm:text-2xl @md:text-3xl font-bold">
        标题自适应
      </h2>
      <p className="text-gray-600 @container @sm:text-base @md:text-lg">
        这段文字的大小取决于外层容器 @container 的宽度。
      </p>
    </div>
  );
};

export default TailwindDemo;

这里的技巧：
Tailwind 的容器查询语法非常像媒体查询，只是把 @media 换成了 @container。它默认监听 inline-size。如果你想监听 size（宽和高），可以用 @size。

第六部分：实战案例——构建一个“智能”的 Profile Card

让我们来个综合案例。假设我们要做一个社交网络的头像卡片。

需求：

1. 在宽屏侧边栏里，显示头像和名字，名字在头像下方。
2. 在窄屏侧边栏里，名字在头像右侧（横向排列）。
3. 在手机主内容区（侧边栏隐藏，内容区很宽），显示大头像，名字在右侧，并附带简介。

使用原生 CSS + React 实现：

// ProfileCard.js
import React from 'react';
import styled from 'styled-components';

// 1. 定义卡片样式
const Card = styled.div`
  container-type: inline-size;
  container-name: profile-card;
  background: white;
  border-radius: 12px;
  padding: 16px;
  display: flex;
  align-items: center;
  gap: 12px;
  box-shadow: 0 4px 6px rgba(0,0,0,0.1);

  /* 默认状态：小图小名 */
  img {
    width: 50px;
    height: 50px;
    border-radius: 50%;
    object-fit: cover;
  }

  .info {
    display: flex;
    flex-direction: column;
  }

  .name {
    font-weight: bold;
    font-size: 1rem;
  }

  .role {
    font-size: 0.8rem;
    color: #666;
  }

  /* 容器查询：如果容器宽度大于 200px */
  @container profile-card (min-width: 200px) {
    .info {
      /* 名字在头像右侧 */
      align-items: flex-start; 
    }

    img {
      /* 头像稍微大一点 */
      width: 60px;
      height: 60px;
    }
  }

  /* 容器查询：如果容器宽度大于 400px */
  @container profile-card (min-width: 400px) {
    .info {
      /* 名字在头像右侧 */
      align-items: flex-start;
    }

    img {
      width: 80px;
      height: 80px;
    }

    .role {
      /* 显示职位 */
      display: block;
    }

    .bio {
      display: block;
      margin-top: 4px;
      font-size: 0.9rem;
      color: #555;
      max-height: 0;
      overflow: hidden;
      transition: max-height 0.3s ease;
    }
  }

  /* 容器查询：如果容器宽度大于 600px */
  @container profile-card (min-width: 600px) {
     .bio {
       /* 展开简介 */
       max-height: 100px;
     }
  }
`;

const ProfileCard = ({ name, role, bio, avatar }) => {
  return (
    <Card>
      <img src={avatar} alt={name} />
      <div className="info">
        <div className="name">{name}</div>
        <div className="role">{role}</div>
        <div className="bio">{bio}</div>
      </div>
    </Card>
  );
};

export default ProfileCard;

App.js 的布局逻辑：

import React from 'react';
import ProfileCard from './ProfileCard';

const App = () => {
  return (
    <div style={{ display: 'flex', height: '100vh' }}>

      {/* 左侧：侧边栏 */}
      <aside style={{ width: '250px', padding: '20px', background: '#f0f0f0' }}>
        <h3>侧边栏 (250px)</h3>
        {/* ProfileCard 会看到容器宽度 250px */}
        <ProfileCard 
          name="Alice"
          role="Frontend Dev"
          bio="Loves CSS and React"
          avatar="https://via.placeholder.com/150"
        />
      </aside>

      {/* 右侧：主内容区 */}
      <main style={{ flex: 1, padding: '20px' }}>
        <h3>主内容区 (自适应)</h3>
        <div style={{ display: 'flex', gap: '20px' }}>

          {/* 主内容区 1：宽 */}
          <div style={{ width: '500px', background: '#e0e0e0', padding: '20px' }}>
            <h4>容器 1 (500px)</h4>
            <ProfileCard 
              name="Bob"
              role="Backend Dev"
              bio="Loves Node.js and Coffee"
              avatar="https://via.placeholder.com/150"
            />
          </div>

          {/* 主内容区 2：超宽 */}
          <div style={{ width: '800px', background: '#d0d0d0', padding: '20px' }}>
            <h4>容器 2 (800px)</h4>
            <ProfileCard 
              name="Charlie"
              role="Fullstack Dev"
              bio="Loves everything and nothing"
              avatar="https://via.placeholder.com/150"
            />
          </div>

        </div>
      </main>

    </div>
  );
};

export default App;

观察结果：

• 在侧边栏（250px）：头像小，名字在下面。
• 在主内容区 500px：头像变大，名字在右边，显示职位。
• 在主内容区 800px：头像更大，显示职位，还显示了简介。

关键点：ProfileCard 组件本身完全没有修改，它就是纯粹的“内容”。它是如何适应不同环境的？完全归功于 @container。

第七部分：深入探讨——Context API 与容器宽度的传递

虽然上面的 CSS-in-JS 解决了大部分问题，但有时候我们需要在 React 逻辑层面知道容器宽度（比如计算布局比例）。这时候，我们就需要结合 Context API。

思路是这样的：

1. 创建一个 Context，存储当前的容器宽度。
2. 创建一个 Provider 组件，它包裹着容器。
3. 在 Provider 内部，监听容器的 ResizeObserver 或者父组件传来的宽度。
4. 子组件通过 Context 读取宽度。

代码实现：

// ContainerContext.js
import React, { createContext, useContext, useState, useEffect, useRef } from 'react';

const ContainerContext = createContext();

export const useContainerWidth = () => {
  return useContext(ContainerContext);
};

export const ContainerProvider = ({ children, width }) => {
  // 实际开发中，width 可能是从父组件传下来的，或者通过 ResizeObserver 计算出来的
  return (
    <ContainerContext.Provider value={width}>
      {children}
    </ContainerContext.Provider>
  );
};

// ContainerWrapper.js
import React, { useRef, useEffect } from 'react';
import { ContainerProvider, useContainerWidth } from './ContainerContext';

const ContainerWrapper = ({ children, minWidth, maxWidth, style }) => {
  const wrapperRef = useRef(null);
  const [width, setWidth] = useState(0);

  useEffect(() => {
    const element = wrapperRef.current;
    if (!element) return;

    // 使用 ResizeObserver 监听容器大小变化
    const resizeObserver = new ResizeObserver(entries => {
      for (let entry of entries) {
        setWidth(entry.contentRect.width);
      }
    });

    resizeObserver.observe(element);

    // 初始化宽度
    setWidth(element.getBoundingClientRect().width);

    return () => {
      resizeObserver.unobserve(element);
    };
  }, []);

  return (
    <div 
      ref={wrapperRef}
      style={{ 
        ...style, 
        containerType: 'inline-size',
        width: '100%',
        border: '1px solid red' // 调试用
      }}
    >
      <ContainerProvider width={width}>
        {children}
      </ContainerProvider>
    </div>
  );
};

// 使用示例
const MyComponent = () => {
  const width = useContainerWidth();
  const isWide = width > 600;

  return (
    <div style={{ padding: '20px', background: '#f9f9f9' }}>
      <h3>Current Container Width: {Math.round(width)}px</h3>
      <div style={{ display: isWide ? 'flex' : 'block', gap: '10px' }}>
        <div style={{ background: 'blue', color: 'white', padding: '10px' }}>
          Item 1
        </div>
        <div style={{ background: 'green', color: 'white', padding: '10px' }}>
          Item 2
        </div>
      </div>
    </div>
  );
};

这种结合了 CSS Container Queries（用于视觉样式）和 React Context（用于逻辑控制）的方式，是处理复杂布局的终极方案。

第八部分：常见的坑与注意事项

在拥抱新技术的同时，我们也要小心陷阱。Container Queries 虽然强大，但也不是万能的。

1. 默认容器宽度为零
这是最常见的问题。如果你的父元素没有设置宽度（width: auto 或者 width: fit-content），容器查询可能不会按预期工作，或者触发条件极其苛刻。
解决：确保你的容器元素明确设置了宽度。

2. 兼容性问题
虽然现代浏览器支持得很好，但在一些非常老旧的移动浏览器上可能需要 Polyfill。
解决：使用像 react-container-query 这样的库，它们内部会自动处理兼容性检测。

3. 性能
虽然容器查询比媒体查询更精细，但频繁的查询和布局重排依然需要关注。
解决：尽量减少在容器查询中使用的复杂动画，或者使用 will-change 属性进行优化。

4. 与 CSS Grid 的配合
容器查询在 Grid 布局中是神技。你可以让 Grid 的列数根据容器宽度动态变化，而不需要媒体查询。

.gallery {
  display: grid;
  /* 默认 1 列 */
  grid-template-columns: 1fr;
}

@container (min-width: 600px) {
  .gallery {
    grid-template-columns: repeat(3, 1fr);
  }
}

第九部分：总结与展望

好了，同学们，今天的讲座接近尾声。我们回顾了什么？

我们痛斥了传统媒体查询的“上帝视角”缺陷，引入了“邻居视角”的容器查询。我们学习了如何用原生 CSS 定义容器，如何用 React 的 Context API 传递容器宽度，以及如何用 Emotion 和 Tailwind 快速上手。

Container Queries 的出现，标志着 Web 开发从“响应式”向“组件级响应式”的进化。它让组件变得更独立、更灵活、更易复用。

想象一下未来的开发场景：
你不再需要写一堆 @media 来适配不同的屏幕。你只需要写一个组件，它自己就能适应任何环境。无论是放在侧边栏、模态框、还是瀑布流中，它都能找到最舒服的姿势。

这不仅仅是技术的升级，这是设计思维的解放。它让我们回归到组件设计的初衷：每一个组件都应该是一个自洽的、适应环境的独立个体。

最后，我想送给大家一句话：
“不要让你的组件去适应屏幕，要让它们去适应环境。”

祝大家在 React 的世界里，写出更加灵活、优雅的代码！下课！

---

(附录：代码库清单)

为了方便大家动手实验，这里列出几个推荐工具：

1. 原生 CSS 支持：Chrome 105+, Firefox 103+, Safari 16.4+ (基本全覆盖)。
2. Tailwind Plugin: @tailwindcss/container-queries (必装)。
3. Emotion: 原生支持 @container。
4. React 库: react-container-query (如果不自己造轮子)。
5. Polyfill: container-queries-polyfill (老旧项目救星)。

希望这篇文章能成为你从“响应式”走向“容器化”的敲门砖。动手试试吧，别光看不练！