字体模块 3个月前

本 API 参考文档将帮助你了解如何使用 next/font/google 和 next/font/local。有关功能和使用方法，请参阅 优化字体 页面。

字体函数参数

要了解使用方法，请查看 Google Fonts 和 本地字体。

标记为 0 表示false, 未标记即为 true

src

字体文件的路径，可以是字符串或对象数组（类型为 Array<{path: string, weight?: string, style?: string}>），相对于调用字体加载函数的目录。

用于 next/font/local

• 必填项

示例：

• src:'./fonts/my-font.woff2'，其中 my-font.woff2 放置在 app 目录中的 fonts 文件夹内
• src:[{path: './inter/Inter-Thin.ttf', weight: '100',},{path: './inter/Inter-Regular.ttf',weight: '400',},{path: './inter/Inter-Bold-Italic.ttf', weight: '700',style: 'italic',},]
• 如果字体加载函数在 app/page.tsx 中调用，使用 src:'../styles/fonts/my-font.ttf'，那么 my-font.ttf 放置在项目根目录的 styles/fonts 中

weight

字体的 weight 可能有以下几种情况：

• 一个字符串，可能的值为特定字体可用的权重或范围值，如果是 variable 字体
• 如果字体不是 variable google font，则为权重值的数组。仅适用于 next/font/google。

用于 next/font/google 和 next/font/local

• 如果使用的字体不是variable，则为必填项

示例：

• weight: '400'：一个表示单一权重值的字符串 - 对于 Inter 字体，可能的值为 '100'、'200'、'300'、'400'、'500'、'600'、'700'、'800'、'900' 或 'variable'，其中 'variable' 为默认值
• weight: '100 900'：表示从 100 到 900 的范围字符串，适用于可变字体
• weight: ['100','400','900']：对非可变字体而言的 3 个可能值的数组

style

字体的 style 可能有以下几种情况：

• 一个字符串 value，默认值为 'normal'
• 如果字体不是 variable google font，则为样式值的数组。仅适用于 next/font/google。

用于 next/font/google 和 next/font/local

• 选填

示例：

• style: 'italic'：一个字符串 - 对于 next/font/google 可以是 normal 或 italic
• style: 'oblique'：一个字符串 - 对于 next/font/local 可以取任何值，但通常来自 standard font styles
• style: ['italic','normal']：对 next/font/google 的 2 个值的数组 - 取值为 normal 和 italic

subsets

字体的 subsets 由一个字符串值数组定义，该数组包含你希望 预加载 的每个子集的名称。通过 subsets 指定的字体将在 preload 选项为 true 时注入到头部的预加载链接标签中，默认值为 true。

用于 next/font/google

• 选填

示例：

• subsets: ['latin']：一个包含 latin 子集的数组

你可以在 Google Fonts 页面上找到所有子集的列表。

axes

一些可变字体有额外的 axes 可以包括在内。默认情况下，仅包含字体权重，以保持文件大小较小。axes 的可能值取决于特定字体。

用于 next/font/google

• 选填

示例：

• axes: ['slnt']：一个包含 slnt 值的数组，适用于 Inter 可变字体，该字体具有 slnt 作为额外的 axes，如 此处 所示。你可以通过使用 Google 可变字体页面 上的过滤器查找你的字体可能的 axes 值，并查找除 wght 以外的 axes。

display

字体的 display 可能的字符串 值 为 'auto'、'block'、'swap'、'fallback' 或 'optional'，默认值为 'swap'。

用于 next/font/google 和 next/font/local

• 选填

示例：

• display: 'optional'：字符串值设置为 optional

preload

一个布尔值，指定是否应 预加载 字体。默认值为 true。

用于 next/font/google 和 next/font/local

• 选填

示例：

• preload: false

fallback

在无法加载字体时使用的后备字体。一个包含后备字体的字符串数组，没有默认值。

• 选填

用于 next/font/google 和 next/font/local

示例：

• fallback: ['system-ui', 'arial']：一个数组，将回退字体设置为 system-ui 或 arial。

adjustFontFallback

• 对于 next/font/google：一个布尔值，设置是否使用自动回退字体以减少 累计布局偏移。默认值为 true。
• 对于 next/font/local：一个字符串或布尔值 false，设置是否使用自动回退字体以减少 累计布局偏移。可能的值有 'Arial'、'Times New Roman' 或 false。默认值为 'Arial'。

用于 next/font/google 和 next/font/local

• 可选

示例：

• adjustFontFallback: false：用于 next/font/google
• adjustFontFallback: 'Times New Roman'：用于 next/font/local

variable

一个字符串值，用于定义 CSS 变量名称，该变量在使用 CSS 变量方法 应用样式时使用。

用于 next/font/google 和 next/font/local

• 可选

示例：

• variable: '--my-font'：声明了 CSS 变量 --my-font

declarations

一个描述符数组，包含键值对，用于进一步定义生成的 @font-face。

用于 next/font/local

• 可选

示例：

• declarations: [{ prop: 'ascent-override', value: '90%' }]

应用样式

你可以通过以下三种方式应用字体样式：

• className
• style
• CSS 变量

className

返回一个只读的 CSS className，用于传递给 HTML 元素。

copy
<p className={inter.className}>Hello, Next.js!</p>

style

返回一个只读的 CSS style 对象，用于传递给 HTML 元素，包括 style.fontFamily 用于访问字体系列名称和回退字体。

copy
<p style={inter.style}>Hello World</p>

CSS 变量

如果你希望在外部样式表中设置样式并在其中指定附加选项，请使用 CSS 变量方法。

除了导入字体，还需要导入定义 CSS 变量的 CSS 文件，并将字体加载器对象的 variable 选项设置如下：

copy
// app/page.tsx

import { Inter } from 'next/font/google';
import styles from '../styles/component.module.css';

const inter = Inter({
  variable: '--font-inter',
});

要使用该字体，将文本的父容器的 className 设置为字体加载器的 variable 值，将文本的 className 设置为外部 CSS 文件中的 styles 属性。

copy
// app/page.tsx

<main className={inter.variable}>
  <p className={styles.text}>Hello World</p>
</main>

在 component.module.css CSS 文件中定义 text 选择器类如下：

copy
/* styles/component.module.css */

.text {
  font-family: var(--font-inter);
  font-weight: 200;
  font-style: italic;
}

在上面的示例中，文本 Hello World 使用了 Inter 字体和生成的字体回退，并设置了 font-weight: 200 和 font-style: italic。

使用字体定义文件

每次调用 localFont 或 Google 字体函数时，该字体将在应用中作为一个实例进行托管。因此，如果你需要在多个地方使用相同的字体，应该在一个地方加载它，并在需要的地方导入相关的字体对象。这可以通过使用字体定义文件来完成。

例如，在应用目录的 styles 文件夹中创建一个 fonts.ts 文件。

然后，按如下方式指定你的字体定义：

copy
// styles/fonts.ts

import { Inter, Lora, Source_Sans_3 } from 'next/font/google';
import localFont from 'next/font/local';

// 定义变量字体
const inter = Inter();
const lora = Lora();

// 定义两种权重的非变量字体
const sourceCodePro400 = Source_Sans_3({ weight: '400' });
const sourceCodePro700 = Source_Sans_3({ weight: '700' });

// 定义一个本地自定义字体，其中 GreatVibes-Regular.ttf 存储在 styles 文件夹中
const greatVibes = localFont({ src: './GreatVibes-Regular.ttf' });

export { inter, lora, sourceCodePro400, sourceCodePro700, greatVibes };

现在你可以按如下方式在代码中使用这些定义：

copy
// app/page.tsx

import { inter, lora, sourceCodePro700, greatVibes } from '../styles/fonts';

export default function Page() {
  return (
    <div>
      <p className={inter.className}>Hello world using Inter font</p>
      <p style={lora.style}>Hello world using Lora font</p>
      <p className={sourceCodePro700.className}>
        Hello world using Source_Sans_3 font with weight 700
      </p>
      <p className={greatVibes.className}>My title in Great Vibes font</p>
    </div>
  );
}

为了更方便地访问字体定义，你可以在 tsconfig.json 或 jsconfig.json 文件中定义路径别名，如下所示：

copy
// tsconfig.json

{
  "compilerOptions": {
    "paths": {
      "@/fonts": ["./styles/fonts"]
    }
  }
}

现在你可以按如下方式导入任何字体定义：

copy
// app/about/page.tsx

import { greatVibes, sourceCodePro400 } from '@/fonts';

版本更改