
# テーマのタイポグラフィ

Material 3 には 15 のテキストスタイルがあります。五つのグループ (display、headline、title、body、label) と三つのサイズ (large、medium、small) です。アプリ全体のフォントを設定することも、グループ全体を一度に変えることも、一つのスタイルを変えることもできます。16 番目のスタイル `code` は等幅のテキストのためのものです。

```yaml
spring:
  flutter:
    theme:
      typography:
        font-family: Inter
        font-family-fallback: [Noto Sans JP, Noto Sans]
        defaults:
          letter-spacing: 0.1
        display:
          font-family: Playfair Display
          weight: bold
        title-large:
          size: 24
          weight: semibold
          height: 1.3
        body-medium:
          height: 1.5
        code:
          font-family: JetBrains Mono
          size: 13
```

設定しなかったものはすべて Material の値のままです。

## プロパティ

| プロパティ | 型 | 値 | デフォルト | 働き |
|---|---|---|---|---|
| `typography.font-family` | テキスト | フォントファミリーの名前 | プラットフォームのフォント | すべてのテキストのフォント |
| `typography.font-family-fallback` | テキストのリスト | ファミリーの名前。YAML のリストか、一つのカンマ区切りの値 | なし | メインのフォントにない文字 (例えば日本語) のために、順に試すフォント |
| `typography.defaults.<key>` | | 以下のスタイルのキー | なし | 15 のすべてのスタイルに適用される。最も弱い層 |
| `typography.<group>.<key>` | | `display`、`headline`、`title`、`body`、`label` | なし | そのグループの三つのサイズに適用される |
| `typography.<style>.<key>` | | 以下の 15 のスタイル | Material のもの | 一つのスタイルに適用される。最も強い層 |
| `typography.code.<key>` | | 以下のスタイルのキー | `monospace`、サイズ 14 | Material にロールのない、等幅のテキストのスタイル |

### スタイルのキー

これらのキーは、`defaults`、グループ、スタイル、`code` の下で使えます。

| キー | 型 | 値 | デフォルト | 働き |
|---|---|---|---|---|
| `font-family` | テキスト | フォントファミリーの名前 | `typography.font-family` | このスタイルのフォント |
| `size` | 数値 | 論理ピクセル、`22`、`13.5` | Material のもの | フォントのサイズ |
| `weight` | 数値または名前 | `100` から `900` まで 100 刻み、または `thin`、`extra-light`、`light`、`normal` (または `regular`)、`medium`、`semibold`、`bold`、`extra-bold`、`black` | Material のもの | フォントのウェイト。`wght` 軸にも設定されるため、可変フォントもそれに従う |
| `height` | 数値 | サイズの倍数、`1.4` | Material のもの | 行の高さ。`1.5` は行がフォントのサイズの 1.5 倍であることを意味する |
| `letter-spacing` | 数値 | 論理ピクセル。負でもよい | Material のもの | 各文字の後に加える間隔 |

ウェイトの名前は、大文字小文字、`-`、`_`、スペースを区別しません: `semibold`、`semi-bold`、`SemiBold` は同じです。100 の倍数でない数値や、`100`..`900` の範囲外の数値はエラーです。

スタイルの下のそれ以外のキー、例えば `font-family-fallback` は起動を止め、この五つを列挙します。`font-family-fallback` は `typography` の直下にだけ存在します。

### 層

一つのスタイルについて、層はこの順に組み合わされ、後のものがキーごとに優先されます。

1. `typography.defaults`
2. グループ (`typography.title`)
3. スタイル (`typography.title-large`)

```yaml
spring:
  flutter:
    theme:
      typography:
        defaults: { letter-spacing: 0.2 }   # すべてのスタイル
        title: { weight: 600 }              # title-large、title-medium、title-small
        title-small: { weight: 500 }        # これだけが細い
```

## テキストのロール

スタイルの名前はケバブケース (`display-large`) で書きます。`displayLarge` も使えます。サイズは Material 3 の基準のサイズで、`size` を設定しない場合に適用されます。

| スタイル | 基準のサイズ | 用途 |
|---|---|---|
| `display-large` | 57 | 最も大きいテキスト: 目立つ数字や歓迎の見出し |
| `display-medium` | 45 | 大きな画面での大きな見出し |
| `display-small` | 36 | 小さな画面での大きな見出し |
| `headline-large` | 32 | 画面や大きなセクションのタイトル |
| `headline-medium` | 28 | セクションのタイトル |
| `headline-small` | 24 | より小さなセクションのタイトル。ダイアログのタイトル |
| `title-large` | 22 | アプリバーのタイトル |
| `title-medium` | 16 | リストの項目やカードのタイトル。中程度のウェイト |
| `title-small` | 14 | 小さなタイトルとタブのラベル。中程度のウェイト |
| `body-large` | 16 | 長いテキストと画面の主なテキスト |
| `body-medium` | 14 | ほとんどのウィジェットのデフォルトのテキストサイズ |
| `body-small` | 12 | キャプションと補助的なテキスト |
| `label-large` | 14 | ボタンのテキスト |
| `label-medium` | 12 | ナビゲーションバーの上などの小さなラベル |
| `label-small` | 11 | 最も小さなラベルとバッジ |
| `code` | 14 | 等幅のテキスト: 識別子、ログ、ISBN。Material のロールではない |

グループは `display`、`headline`、`title`、`body`、`label` です。`typography` の下のそれ以外の名前は起動を止め、有効な名前を列挙します。

### デザインライブラリなしで

タイプスケールはスターター自身のものなので、15 のスタイルはデザインライブラリのないアプリでも動きます。`SpringTypeScale` は Material 3 のサイズとプラットフォームのデフォルトのフォントを表として持ちます。種類 `widgets` のアプリは、`MaterialApp` が与えるのと同じスタイルを持ちます。`SpringTheme.of(context).textStyle(name)` は、プロパティが設定したものを持つスタイルを返します。`localizedTextStyle(name, script)` は、文字体系 (`TextScript.englishLike`。中国語、日本語、韓国語には `dense`。アラビア語、ヒンディー語、タイ語などには `tall`) に応じたタイプスケールのサイズ、太さ、行の高さ、文字間隔を加えます。これは `MaterialApp` で `Theme.of(context).textTheme` が与えるものです。

### `code` スタイル

`code` はサイズ 14 の `monospace` ファミリーとして始まり、その上に `typography.code` のキーが重なります。`SpringTheme.of(context).textStyle('code')` で読みます。プラットフォームに等幅のフォントがない場合、テキストはテーマの `font-family` と `font-family-fallback` にフォールバックします。

```yaml
spring:
  flutter:
    theme:
      typography:
        code: { font-family: JetBrains Mono, size: 13, letter-spacing: 0 }
```

## アセットからのフォント

フォントファイルを、`pubspec.yaml` の `flutter: assets:` の下に列挙した任意のディレクトリに置きます。`flutter: fonts:` のセクションは不要です。

```yaml
# pubspec.yaml
flutter:
  assets:
    - assets/fonts/     # Inter-Regular.ttf、Inter-SemiBold.ttf、PlayfairDisplay-Bold.ttf
```

スターターは、最初のフレームの前にすべての `.ttf` と `.otf` のアセットを読み込みます。ファミリーの名前はファイル名ではなくフォントファイルの中に格納されたものなので、`Inter-SemiBold.ttf` は `Inter` のウェイトの一つに、`PlayfairDisplay-Bold.ttf` は `Playfair Display` のウェイトの一つになります。`font-family` ではその名前を使ってください。

- ファミリーの名前を読めないファイル (`.ttc` のコレクションや壊れたファイル) は、警告とともにスキップされます。
- 他のパッケージから来るアセット (`packages/` で始まるパス) は、この方法では読み込まれません。パッケージのフォントは、そのパッケージ自身の `pubspec.yaml` で宣言してください。
- テーマが指定しながら、読み込まれたアセットでも `flutter: fonts:` の下でもないファミリーは、起動時に警告としてログに出ます。それでもプラットフォームのフォントである可能性があります。`monospace` は決して報告されません。

| プロパティ | 型 | 値 | デフォルト | 働き |
|---|---|---|---|---|
| `spring.flutter.fonts.auto-load` | bool | `true`、`false` | `true` | `false` はこの方法ではフォントファイルを読み込まない。`flutter: fonts:` の下のフォントは引き続き動く |
| `spring.flutter.fonts.exclude` | glob のリスト | `assets/pdf/**` | なし | 読み込まないフォントのアセット。PDF の作成にだけ使うフォントなど。`*` はディレクトリの中にとどまり、`**` はディレクトリをまたぐ |
| `spring.flutter.fonts.families.<family>.files` | アセットのリスト | `assets/fonts/NotoSansJP.woff2` | なし | 名前で宣言したファミリーのファイル。プラットフォームが読める任意の形式 (`.ttf`、`.otf`。ウェブでは `.woff2`) でそのファミリーに読み込まれる。`auto-load` はこれらに触れない |
| `spring.flutter.fonts.families.<family>.languages` | 言語タグのリスト | `ja`、`zh-Hant` | なし | ファミリーが対象とする言語。アプリがその言語で起動するときは最初のフレームの前に、そうでなければその言語に切り替わるときに読み込まれる (`ja` は `ja-JP` を含む)。なし: 起動時に読み込まれる |

```yaml
spring:
  flutter:
    fonts:
      auto-load: true
      exclude: [assets/pdf/**]
```

### 言語のためのフォント

名前で宣言したファミリーは、列挙したファイルから読み込まれます。`languages` を持つものは、アプリがその言語の一つを表示するときにだけ読み込まれます。他の言語はそれをダウンロードすることがなく、ウェブエンジンは、主フォントにない文字のために自前の代替フォントを取りに行きません (そうしないと、ページごとに取りに行き、そのたびにページをレイアウトし直します)。ファミリーを `typography.font-family-fallback` に指定してください。ナビゲーションスターターでは、`/ja/...` は最初のフレームの前にそれを持ち、`switchLanguage` はテキストが変わる前にそれを読み込みます。

```yaml
spring:
  flutter:
    fonts:
      families:
        Noto Sans JP:
          files: [assets/fonts/NotoSansJP.woff2]
          languages: [ja]
    theme:
      typography:
        font-family: Inter
        font-family-fallback: [Noto Sans JP]
```

## Dart で読む

```dart
Text('NEON Books', style: Theme.of(context).textTheme.displaySmall);   // MaterialApp
Text(
  'NEON Books',
  style: SpringTheme.of(context).localizedTextStyle(                 // 任意のアプリ
    'display-small',
    SpringTypeScale.scriptOf(Localizations.maybeLocaleOf(context)),
  ),
);
Text(isbn, style: SpringTheme.of(context).textStyle('code'));
Text('Total', style: context.theme.typography.titleLarge);   // 型付き
```

`textStyle` は、任意の綴り (`titleLarge`、`title-large`) のスタイル名か `code` を受け付けます。それ以外の名前は `ArgumentError` を投げます。ジェネレーターがあれば、`context.theme.typography` は、宣言した 15 のスタイルと `code` のそれぞれのゲッターを持ちます。

コンポーネントは、これらのスタイルの一つを名前で受け取れます: `components.app-bar.title-text-style: title-large`。[コンポーネント](../../spring-boot-starter-flutter-material/components/index.md) を参照してください。

## 関連項目

- [プロパティ](properties.md)
- [Cupertino](../../spring-boot-starter-flutter-cupertino/theme-properties.md): テキストスタイルが iOS スタイルのテキストにどう反映されるか
- [コンポーネント](../../spring-boot-starter-flutter-material/components/index.md): `text-style` のプロパティ
