Material UI Typography 组件深度指南：从 Roboto 字体配置到 variantMapping 语义元素映射

2026-09-04 11:57:18作者：余洋婵Anita

本文基于 Material UI 官方 Typography 文档页（typography.md）并结合 Typography 组件源码与 createTypography 主题函数展开。读完你将掌握：Typography 组件全部 13 个 variant 的用法与默认渲染元素、Roboto 字体的两种加载方式（Fontsource 与 Google CDN）、通过 component / variantMapping 解耦「样式」与「语义元素」的完整方案、借助主题 typography 键直接复用文字样式，以及无障碍排版的关键约束与源码级原理。

1. 为什么需要 Typography：Material Design 的字号体系

Typography 组件用于以最清晰、高效的方式呈现设计稿与内容，它实现了 Material Design 的 typographic scale（字号比例体系）——一组经过验证、彼此协调的有限字号集合，用于保证整体布局的一致性。

从源码结构看，这套字号体系由 createTypography 生成默认主题。其核心参数与默认值如下（均可在 createTheme({ typography }) 中覆盖）：

参数	默认值	说明
`fontFamily`	`'"Roboto", "Helvetica", "Arial", sans-serif'`	默认字体栈，正是文档要求引入 Roboto 的原因
`fontSize`	`14`（px）	Material 规范定义的基准字号，所有 variant 按比例缩放
`fontWeightLight / Regular / Medium / Bold`	`300 / 400 / 500 / 700`	四个字重常量，被各 variant 引用
`htmlFontSize`	`16`	`<html>` 元素的字号（浏览器默认 16px），用于 px 转 rem
`pxToRem`	`(size) => (size / htmlFontSize) * (fontSize / 14) rem`	px 到 rem 的换算函数，保证随 `fontSize` 基准联动
`allVariants`	无	附加到所有 variant 上的公共 CSS 属性

各 variant 的默认字号、字重、行高与字距（letter spacing）在源码中被硬编码为一份完整的映射（createTypography.js 第 61–83 行）：

const variants = {
  h1: buildVariant(fontWeightLight, 96, 1.167, -1.5),
  h2: buildVariant(fontWeightLight, 60, 1.2, -0.5),
  h3: buildVariant(fontWeightRegular, 48, 1.167, 0),
  h4: buildVariant(fontWeightRegular, 34, 1.235, 0.25),
  h5: buildVariant(fontWeightRegular, 24, 1.334, 0),
  h6: buildVariant(fontWeightMedium, 20, 1.6, 0.15),
  subtitle1: buildVariant(fontWeightRegular, 16, 1.75, 0.15),
  subtitle2: buildVariant(fontWeightMedium, 14, 1.57, 0.1),
  body1: buildVariant(fontWeightRegular, 16, 1.5, 0.15),
  body2: buildVariant(fontWeightRegular, 14, 1.43, 0.15),
  button: buildVariant(fontWeightMedium, 14, 1.75, 0.4, caseAllCaps),
  caption: buildVariant(fontWeightRegular, 12, 1.66, 0.4),
  overline: buildVariant(fontWeightRegular, 12, 2.66, 1, caseAllCaps),
  // ...
};

两个值得注意的实现细节：

字距只在默认字体栈下生效。源码中明确注释：letter spacing 是为 Roboto 字体调校的，跨字体族复用会造成字距（kerning）问题。因此当你更换 fontFamily 后，letterSpacing 会被自动剔除（createTypography.js 第 52–56 行）。
行高采用无单位数字（如 1.167），遵循相对单位最佳实践，使行高随字号缩放。

2. Roboto 字体配置

Material UI 默认使用 Roboto 字体。官方文档提供两种加载方式：

2.1 通过 Fontsource 安装

npm install @fontsource/roboto

然后在入口文件（entry point）中按需导入字重：

import '@fontsource/roboto/300.css';
import '@fontsource/roboto/400.css';
import '@fontsource/roboto/500.css';
import '@fontsource/roboto/700.css';

Fontsource 支持按需加载特定字符子集、字重与字形样式。Material UI 默认 typography 配置只依赖 300、400、500、700 四个字重——这正好对应源码中的 fontWeightLight/Regular/Medium/Bold 常量，因此默认场景下导入这四个文件即可，无需引入其他字重。

2.2 通过 Google Web Fonts CDN

在项目的 <head /> 标签内添加：

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap"
/>

CDN 方式无需安装依赖、适合快速接入；Fontsource 方式将字体文件打包进项目、离线可用且更利于性能控制，两种方式选其一即可。

3. 组件用法：全部 variant 一览

Typography 提供 13 个内置 variant，覆盖 Material Design 字号比例体系的每个层级。官方文档示例 Types.tsx 展示了完整用法，每个 variant 均配合 gutterBottom（底部留白 0.35em，见 Typography.js 第 94–99 行）：

import Box from '@mui/material/Box';
import Typography from '@mui/material/Typography';

export default function Types() {
  return (
    <Box sx={{ width: '100%', maxWidth: 500 }}>
      <Typography variant="h1" gutterBottom>h1. Heading</Typography>
      <Typography variant="h2" gutterBottom>h2. Heading</Typography>
      <Typography variant="h3" gutterBottom>h3. Heading</Typography>
      <Typography variant="h4" gutterBottom>h4. Heading</Typography>
      <Typography variant="h5" gutterBottom>h5. Heading</Typography>
      <Typography variant="h6" gutterBottom>h6. Heading</Typography>
      <Typography variant="subtitle1" gutterBottom>subtitle1. ...</Typography>
      <Typography variant="subtitle2" gutterBottom>subtitle2. ...</Typography>
      <Typography variant="body1" gutterBottom>body1. ...</Typography>
      <Typography variant="body2" gutterBottom>body2. ...</Typography>
      <Typography variant="button" gutterBottom sx={{ display: 'block' }}>button text</Typography>
      <Typography variant="caption" gutterBottom sx={{ display: 'block' }}>caption text</Typography>
      <Typography variant="overline" gutterBottom sx={{ display: 'block' }}>overline text</Typography>
    </Box>
  );
}

从源码看，variant 的默认值是 body1（Typography.js 第 121–131 行），且 variant 的样式完全来自 theme.typography 中对应键值：组件用 Object.entries(theme.typography) 动态生成样式变体，因此凡是在主题里能定义的对象型 variant，都能被 variant prop 直接消费——这也是「添加自定义 variant」能够工作的底层机制。

其他常用 prop（均带默认值，来自 Typography.js 的 PropTypes 定义）：

Prop	默认值	说明
`variant`	`'body1'`	应用主题 typography 样式，取值含 13 个内置 variant，也接受自定义字符串
`component`	无（回退到映射）	根节点使用的 HTML 元素或组件
`variantMapping`	`defaultVariantMapping`	variant 到语义元素的映射表，可局部覆盖
`align`	`'inherit'`	文本对齐：`center / inherit / justify / left / right`，通过 CSS 变量 `--Typography-textAlign` 生效
`color`	无	支持 `primary / secondary / success / error / info / warning` 及 `textPrimary / textSecondary / textDisabled` 等调色板色
`gutterBottom`	`false`	`true` 时添加 0.35em 底部外边距
`noWrap`	`false`	`true` 时文本不换行、以省略号截断（要求元素为块级或 inline-block 且有确定宽度）
`sx`	无	支持 MUI System 全部样式函数与主题感知属性的样式对象

color prop 同样由源码动态生成：Typography.js 第 64–79 行遍历 theme.palette 与 theme.palette.text 自动生成对应的颜色变体样式，所以自定义调色板色加入主题后无需改组件即可使用。

4. Theme keys：不用组件时复用文字样式

在某些场景（例如普通 div、自定义元素）你可能无法直接使用 Typography 组件。此时可以直接消费主题的 typography 键。官方示例 TypographyTheme.tsx 演示了将 theme.typography.button 展开到 styled 的 div 上：

import { styled } from '@mui/material/styles';

const Div = styled('div')(({ theme }) => ({
  ...theme.typography.button,
  backgroundColor: (theme.vars || theme).palette.background.paper,
  padding: theme.spacing(1),
}));

export default function TypographyTheme() {
  return <Div>This div's text looks like that of a button.</Div>;
}

由于 theme.typography.button 就是一个纯 CSS 属性对象（fontFamily、fontWeight、fontSize、lineHeight、letterSpacing、textTransform 等），它可以被直接展开到任何样式系统（styled-components、sx、CSS-in-JS）中。这也解释了为什么 Typography 组件的 variant 样式「独立于语义元素」——二者共享同一份主题数据，只是作用载体不同。

5. 自定义

5.1 添加与禁用 variant

除了 13 个默认 variant，你可以在主题的 typography 键中新增自定义 variant 或删除不需要的 variant。更完整的参数说明可参考定制文档页 customization/typography。

从源码结构看，这套机制能成立的根本原因是：TypographyRoot 的样式变体列表是运行时从 theme.typography 派生的（Typography.js 第 58–63 行）：

...Object.entries(theme.typography)
  .filter(([variant, value]) => variant !== 'inherit' && value && typeof value === 'object')
  .map(([variant, value]) => ({
    props: { variant },
    style: value,
  })),

因此在主题中定义 dot: { fontSize: '2rem', ... } 后，<Typography variant="dot" /> 会自动生效；测试用例中 testVariantProps: { variant: 'dot' }（Typography.test.js 第 15 行）验证了自定义 variant 的通用性。反过来，删除某个键即禁用该 variant。

5.2 改变语义元素（variantMapping 与 component）

Typography 用 variantMapping prop 把 UI variant 关联到语义元素。理解这一点的关键是：排版样式与底层语义元素相互独立——variant 决定「长什么样」，component 决定「是什么标签」。

源码中的默认映射（Typography.js 第 104–116 行）：

const defaultVariantMapping = {
  h1: 'h1', h2: 'h2', h3: 'h3', h4: 'h4', h5: 'h5', h6: 'h6',
  subtitle1: 'h6', subtitle2: 'h6',
  body1: 'p', body2: 'p',
  inherit: 'p',
};

注意 subtitle1/subtitle2 默认渲染为 <h6>，body1/body2 渲染为 <p>。根元素的选择优先级为（Typography.js 第 145–146 行）：

const Component =
  component || variantMapping[variant] || defaultVariantMapping[variant] || 'span';

即：component prop > 传入的 variantMapping > 内置默认映射 > 兜底 span。

一次性修改：如避免页面出现两个 h1，用 component prop：

<Typography variant="h1" component="h2">
  h1. Heading
</Typography>

全局修改映射：通过主题的 defaultProps（Typography.js 第 119 行的 useDefaultProps 会让所有实例读取主题默认值，这也是主题覆盖能全局生效的原因）：

const theme = createTheme({
  components: {
    MuiTypography: {
      defaultProps: {
        variantMapping: {
          h1: 'h2',
          h2: 'h2',
          h3: 'h2',
          h4: 'h2',
          h5: 'h2',
          h6: 'h2',
          subtitle1: 'h2',
          subtitle2: 'h2',
          body1: 'span',
          body2: 'span',
        },
      },
    },
  },
});

测试用例印证了这一行为：variant="h6" variantMapping={{ h6: 'aside' }} 时根标签为 <aside>；即使传入空映射 variantMapping={{}}，仍会回退到内置默认映射渲染为 <H6>（Typography.test.js 第 85–105 行）。

5.3 sx prop

使用 sx prop 可以基于 MUI System 暴露的样式函数与主题感知属性，快速定制任意 Typography 实例，例如应用外边距：

<Typography sx={{ m: 2 }} />

官方测试验证了 sx 间距的系统化解析：sx={{ mt: 2, marginRight: 5, mb: 2 }} 最终计算样式为 marginTop: 16px、marginRight: 40px、marginBottom: 16px（spacing 值 × 8px 倍数，见 Typography.test.js 第 107–116 行）。

6. 无障碍（Accessibility）要点

文档给出了可访问排版的三个关键因素：

颜色（Color）：确保文本与背景之间有足够的对比度，遵循 WCAG 2.2 最低推荐对比度 4.5:1。
字号（Font size）：使用相对单位 rem 而非像素，以适配用户的浏览器字号设置。这一点由源码默认实现保证——pxToRem 将每个 variant 的 fontSize 统一转换为 rem（createTypography.js 第 44–45 行），用户调大浏览器基准字号时整站文字会等比放大。
标题层级（Heading hierarchy）：遵循 W3 指南，不要跳过标题级别；确保将语义与样式分离（即上一节的 component / variantMapping 机制）。视觉上需要 h1 样式但页面已有 h1 时，应写 variant="h1" component="h2"，而不是降级使用 variant="h2"。

7. 实用类名与类名覆盖

Typography 暴露了一组稳定的 utility classes（typographyClasses.ts），可用于 CSS 覆盖与 classes prop：

每个 variant 对应一个类：MuiTypography-root、MuiTypography-h1 … MuiTypography-body2、MuiTypography-inherit、MuiTypography-button、MuiTypography-caption、MuiTypography-overline；
对齐状态：MuiTypography-alignLeft / alignRight / alignCenter / alignJustify；
修饰状态：MuiTypography-noWrap、MuiTypography-gutterBottom。

类名按 slot 组合规则生成（Typography.js 第 13–27 行）：root 类始终存在，variant 类、align 类（align 不为 inherit 时）、noWrap 与 gutterBottom 类按条件追加。

8. 小结

Typography 组件的核心价值在于「样式与语义解耦」：variant 从主题 typography 读取一套经过 Material Design 调校的字号体系（默认 Roboto、rem 单位、相对行高），component / variantMapping 独立控制语义标签，二者互不干扰。结合本仓库源码可以确认的关键事实：

默认字号体系由 createTypography.js 定义，基准 fontSize: 14、默认字体栈以 Roboto 开头；
variant 样式运行时派生自 theme.typography，因此主题即扩展点（加 variant、删 variant、改映射）；
元素解析优先级为 component > variantMapping > defaultVariantMapping > 'span'（Typography.js）；
测试覆盖（Typography.test.js）验证了默认 body1、全部 variant 类名、元素映射与 sx 间距解析行为。