React / 系统课时

使用 CSS Modules

使用 CSS Modules

本课将为组件编写作用域隔离的样式。通过 .module.css 文件,Next.js 会为类名生成唯一标识,使不同组件可以安全复用 title、button 等常见名称。

学习目标

  • 创建并导入 CSS Module
  • 使用样式对象绑定局部类名
  • 组合基础样式与状态样式

创建组件样式

文件名必须以 .module.css 结尾。下面为按钮定义基础规则和两个视觉变体。

css
.button {
  border: 0;
  border-radius: 0.75rem;
  padding: 0.75rem 1rem;
  font: inherit;
  font-weight: 600;
  cursor: pointer;
}

.primary {
  background: #4f46e5;
  color: #ffffff;
}

.secondary {
  background: #e8eaf3;
  color: #172033;
}

.button:focus-visible {
  outline: 3px solid #a5b4fc;
  outline-offset: 2px;
}

该文件可保存为 app/ui/Button.module.css。这些类名只在导入它的模块中通过样式对象使用,不会直接成为全局 .button 规则。

在组件中绑定类名

下面的组件根据 variant 组合基础类和变体类。示例不依赖客户端状态,因此不需要添加 'use client'。

tsx
import type { ButtonHTMLAttributes } from 'react'
import styles from './Button.module.css'

type Props = ButtonHTMLAttributes<HTMLButtonElement> & {
  variant?: 'primary' | 'secondary'
}

export function Button({
  variant = 'primary',
  className,
  ...props
}: Props) {
  const variantClass =
    variant === 'primary' ? styles.primary : styles.secondary

  const classes = [styles.button, variantClass, className]
    .filter(Boolean)
    .join(' ')

  return <button className={classes} {...props} />
}

预期结果:<Button>保存</Button> 显示紫色主按钮,<Button variant="secondary">取消</Button> 显示灰色次按钮。构建后的真实类名会被转换为局部标识,其他模块中的 .button 不会覆盖它。

管理动态样式与共享边界

正确处理动态类名

CSS Modules 的类名来自导入对象,不能把字符串直接拼成 styles['button-' + size],除非对应键确实存在。更清晰的方式是建立显式映射。

ts
const sizeClasses = {
  small: styles.small,
  medium: styles.medium,
  large: styles.large,
} as const

这是片段示例,要求样式文件中已经定义 small、medium 和 large。显式映射能让 TypeScript 检查可用值,也便于重命名。

何时继续使用全局样式

CSS Modules 适合组件内部结构、变体和交互状态。字体变量、页面背景、重置规则等跨组件约定仍应保留在全局 CSS。

如果多个组件需要共享完全相同的样式,可以抽成一个公共模块或可复用组件,而不是复制粘贴。优先复用组件通常比共享大量样式类更容易维护。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 CSS Modules

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通