字型模組

此 API 參考將幫助你了解如何使用 next/font/google 和 next/font/local。有關功能和使用方式，請參閱「優化字型」頁面。

字型函式參數

有關使用方式，請查看 Google Fonts 和 Local Fonts。

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']：非變數字型 3 個可能值的陣列

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，2 個值的陣列 - 值來自 normal 和 italic

subsets

字型subsets，由字串值陣列定義，其中包含你要預先載入的每個子集的名稱。當 preload 選項為 true 時 (預設值)，透過 subsets 指定的字型將在 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/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：布林值，設定是否應使用自動後備字型來減少累計版面配置偏移 (Cumulative Layout Shift)。預設值為 true。
• 對於 next/font/local：字串或布林值 false，設定是否應使用自動後備字型來減少累計版面配置偏移 (Cumulative Layout Shift)。可能的值為 '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

字型 face 描述符 鍵值對的陣列，進一步定義產生的 @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 檔案，並依如下方式設定字型載入器物件的 variable 選項

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 字型和產生的字型後備字型設定樣式，字型粗細為 200，字型樣式為斜體。

使用字型定義檔

每次你呼叫 localFont 或 Google font 函式時，該字型將作為你應用程式中的一個實例託管。因此，如果你需要在多個位置使用相同的字型，你應該在一個位置載入它，並在你需要它的地方匯入相關的字型物件。這是透過使用字型定義檔來完成的。

例如，在你的 app 目錄根目錄的 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 }

你現在可以在你的程式碼中使用這些定義，如下所示

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 檔案中定義路徑別名，如下所示

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

你現在可以依如下方式匯入任何字型定義

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

版本變更