跳到内容

字体模块

此 API 参考将帮助你了解如何使用 next/font/googlenext/font/local。有关功能和用法,请参阅优化字体页面。

字体函数参数

有关用法,请查看 Google 字体本地字体

font/googlefont/local类型必需
src字符串或对象数组
weight字符串或数组必需/可选
style字符串或数组-
subsets字符串数组-
axes字符串数组-
display字符串-
preload布尔值-
fallback字符串数组-
adjustFontFallback布尔值或字符串-
variable字符串-
declarations对象数组-

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,具有以下可能性

  • 一个字符串,包含特定字体可用的粗细值或范围值(如果是可变字体)
  • 如果字体不是可变 Google 字体,则为粗细值数组。仅适用于 next/font/google

next/font/googlenext/font/local 中使用

示例

  • weight: '400':一个字符串,表示单个粗细值 - 对于字体 Inter,可能的值为 '100''200''300''400''500''600''700''800''900''variable',其中 'variable' 是默认值)
  • weight: '100 900':一个字符串,表示可变字体的 100900 之间的范围
  • weight: ['100','400','900']:一个包含 3 个可能值的数组,用于非可变字体

style

字体style,具有以下可能性

  • 一个字符串,默认值为 'normal'
  • 如果字体不是可变 Google 字体,则为样式值数组。仅适用于 next/font/google

next/font/googlenext/font/local 中使用

  • 可选

示例

  • style: 'italic':一个字符串 - 对于 next/font/google,可以是 normalitalic
  • style: 'oblique':一个字符串 - 对于 next/font/local,可以接受任何值,但应来自 标准字体样式
  • style: ['italic','normal']:一个包含 2 个值的数组,用于 next/font/google - 值来自 normalitalic

subsets

字体subsets,由字符串值数组定义,其中包含要预加载的每个子集的名称。通过 subsets 指定的字体将在 preload 选项为 true 时(默认情况)将链接预加载标签注入到 head 中。

next/font/google 中使用

  • 可选

示例

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

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

axes

一些可变字体具有可以包含的额外 axes。默认情况下,仅包含字体粗细以减小文件大小。axes 的可能值取决于特定字体。

next/font/google 中使用

  • 可选

示例

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

display

字体display,可能的字符串'auto''block''swap''fallback''optional',默认值为 'swap'

next/font/googlenext/font/local 中使用

  • 可选

示例

  • display: 'optional':分配给 optional 值的字符串

preload

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

next/font/googlenext/font/local 中使用

  • 可选

示例

  • preload: false

fallback

如果字体无法加载,则使用的后备字体。一个不包含默认值的后备字体字符串数组。

  • 可选

next/font/googlenext/font/local 中使用

示例

  • fallback: ['system-ui', 'arial']:一个将后备字体设置为 system-uiarial 的数组

adjustFontFallback

  • 对于 next/font/google:一个布尔值,用于设置是否应使用自动后备字体以减少累积布局偏移。默认值为 true
  • 对于 next/font/local:一个字符串或布尔值 false,用于设置是否应使用自动后备字体以减少累积布局偏移。可能的值为 'Arial''Times New Roman'false。默认值为 'Arial'

next/font/googlenext/font/local 中使用

  • 可选

示例

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

variable

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

next/font/googlenext/font/local 中使用

  • 可选

示例

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

declarations

字体面描述符键值对数组,用于进一步定义生成的 @font-face

next/font/local 中使用

  • 可选

示例

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

应用样式

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

className

返回已加载字体的只读 CSS className,以便传递给 HTML 元素。

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

style

返回已加载字体的只读 CSS style 对象,以便传递给 HTML 元素,包括 style.fontFamily 以访问字体族名称和后备字体。

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

CSS 变量

如果你想在外部样式表中设置样式并在其中指定其他选项,请使用 CSS 变量方法。

除了导入字体外,还要导入定义了 CSS 变量的 CSS 文件,并将字体加载器对象的 variable 选项设置为如下所示

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 属性。

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

component.module.css CSS 文件中定义 text 选择器类,如下所示

styles/component.module.css
.text {
  font-family: var(--font-inter);
  font-weight: 200;
  font-style: italic;
}

在上面的示例中,文本 Hello World 使用 Inter 字体和生成的字体后备样式,font-weight: 200font-style: italic

使用字体定义文件

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

例如,在你的 app 目录根目录的 styles 文件夹中创建一个 fonts.ts 文件。

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

styles/fonts.ts
import { Inter, Lora, Source_Sans_3 } from 'next/font/google'
import localFont from 'next/font/local'
 
// define your variable fonts
const inter = Inter()
const lora = Lora()
// define 2 weights of a non-variable font
const sourceCodePro400 = Source_Sans_3({ weight: '400' })
const sourceCodePro700 = Source_Sans_3({ weight: '700' })
// define a custom local font where GreatVibes-Regular.ttf is stored in the styles folder
const greatVibes = localFont({ src: './GreatVibes-Regular.ttf' })
 
export { inter, lora, sourceCodePro400, sourceCodePro700, greatVibes }

你现在可以在你的代码中使用这些定义,如下所示

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.jsonjsconfig.json 文件中定义路径别名,如下所示

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

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

app/about/page.tsx
import { greatVibes, sourceCodePro400 } from '@/fonts'

版本变更

版本变更
v13.2.0@next/font 重命名为 next/font。不再需要安装。
v13.0.0添加了 @next/font