字體模組

本 API 參考將幫助您理解如何使用 next/font/google 和 next/font/local。關於功能和用法，請參閱 優化字體 頁面。

字體函數參數

關於用法，請查看 Google 字體 和 本地字體。

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/google 和 next/font/local

• 如果使用的字體 不是 可變字體 則為必填

範例：

• weight: '400': 單一權重值的字串 - 對於 Inter 字體，可能的值為 '100'、'200'、'300'、'400'、'500'、'600'、'700'、'800'、'900' 或 'variable'（其中 'variable' 是預設值）
• weight: '100 900': 可變字體的範圍值，介於 100 和 900 之間的字串
• weight: ['100','400','900']: 非可變字體的三個可能值的陣列

style

字體的 style 有以下可能值：

• 字串 值，預設值為 'normal'
• 如果字體不是 可變 Google 字體，則為樣式值的陣列。僅適用於 next/font/google

用於 next/font/google 和 next/font/local

• 選填

範例：

• style: 'italic': 字串 - 對於 next/font/google 可以是 normal 或 italic
• style: 'oblique': 字串 - 對於 next/font/local 可以接受任何值，但預期來自 標準字體樣式
• style: ['italic','normal']: next/font/google 的兩個值的陣列 - 值來自 normal 和 italic

subsets

字體的 subsets，由字串值的陣列定義，每個子集的名稱表示您希望 預載入 的子集。當 preload 選項為 true（預設值）時，透過 subsets 指定的字體會在 head 中注入一個 link preload 標籤。

用於 next/font/google

• 選填

範例：

• subsets: ['latin']: 包含子集 latin 的陣列

您可以在 Google Fonts 頁面上找到您字體的所有子集列表。

axes

某些可變字體具有可以包含的額外 axes。預設情況下，僅包含字體權重以保持檔案大小較小。axes 的可能值取決於特定字體。

用於 next/font/google

• 選填

範例：

• axes: ['slnt']: 包含值 slnt 的陣列，適用於 Inter 可變字體，該字體具有 slnt 作為額外的 axes，如 此處 所示。您可以在 Google 可變字體頁面 上使用篩選器並尋找除 wght 之外的 axes 來找到您字體的可能 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: 布林值，設定是否應使用自動後備字體來減少 累積版面偏移 (CLS)。預設為 true。
• 對於 next/font/local: 字串或布林值 false，設定是否應使用自動後備字體來減少 累積版面偏移 (CLS)。可能的值為 '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 元素。

<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 文件，並如下設定字體載入器物件的變數選項：

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

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

要使用字體，請將要設定樣式的文字的父容器的 className 設定為字體載入器的 variable 值，並將文字的 className 設定為外部 CSS 文件中的 styles 屬性。

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

在 component.module.css CSS 文件中定義 text 選擇器類別如下：

.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 文件。

然後，如下指定您的字體定義：

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 }

現在您可以在程式碼中使用這些定義如下：

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

export default function Page() {
  return (
    <div>
      <p className={inter.className}>使用 Inter 字體的 Hello world</p>
      <p style={lora.style}>使用 Lora 字體的 Hello world</p>
      <p className={sourceCodePro700.className}>
        使用權重 700 的 Source_Sans_3 字體的 Hello world
      </p>
      <p className={greatVibes.className}>使用 Great Vibes 字體的標題</p>
    </div>
  )
}

為了更輕鬆地在程式碼中存取字體定義，您可以在 tsconfig.json 或 jsconfig.json 文件中定義路徑別名如下：

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

現在您可以如下匯入任何字體定義：

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

版本變更