
# MarkdownView

`MarkdownView` は、GitHub の Markdown を、表示中のテーマの色とテキストスタイルで Flutter のウィジェットとして表示します。見出し、リンク、リスト、表、引用、コールアウト、コードブロックはすべて、どのアプリの種類 (`material`、`cupertino`、`widgets`) でもテーマに従います。コードブロックはテーマの言語で色付けされ、それぞれにテキストをコピーするボタンがあります。

## 使う理由

ドキュメント、リリースノート、ヘルプページ、法的なテキストは Markdown で書かれます。汎用のパッケージで描画すると、別のアプリのように見えます。ここではそれらはアプリのテーマを使います。ダークテーマならコードブロックも暗くなり、テーマを切り替えると即座に変わり、デザイナーはアプリの残りと同じ YAML でスタイルを付けます。今読んでいるサイトも、この方法でページを表示しています。

## 例

```dart
// Markdown の文字列。リンクはコールバックに渡される。
MarkdownView(text, onLink: (href) => launchUrl(Uri.parse(href)));

// lib/resources/ のファイル。日本語では代わりに beans.ja.md が表示される。
const MarkdownView.resource('resources:content/docs/beans.md');

// ページのフェンス付きブロックとまったく同じ、一つのコードブロック。
const MarkdownView.code('server:\n  port: 8080', language: 'yaml');
```

```yaml
# lib/resources/application.yml
spring:
  flutter:
    theme:
      source: github:farum-azula/themes/themes/code.yml@code-v0.2.0  # コードの言語
      typography:
        code: { font-family: JetBrains Mono, size: 13 }
      styles:
        code:
          background: $colors.surface-container-low
          keyword: '#C678DD'
          string: '#98C379'
          copy: true
        heading:
          color: $colors.primary
        link:
          color: $colors.secondary
        table:
          cell-width: 240
          fill: true
        callout:
          warning: '#FF5C7A'
```

## コンストラクター

| コンストラクター | パラメーター | 表示するもの |
|---|---|---|
| `MarkdownView(markdown)` | `onLink`、`selectable` (`true`)、`outline` | Markdown の文字列 |
| `MarkdownView.resource(location)` | `onLink`、`selectable` (`true`)、`outline` | リソース (`resources:content/beans.md`)。隣に翻訳 (`beans.ja.md`) があればアプリの言語で表示し、言語に追従する。次のページが読まれるまで表示中のページを保ち、その後テーマの方法 (`motion.content-change`) で切り替える |
| `MarkdownView.code(code)` | `language`、`selectable` (`true`) | 一つのコードブロック |

- Markdown に書かれた HTML はテキストとして表示されます。フロントマター (`---` ... `---`) は省かれます。
- テキストは、アプリのデザインライブラリの方法で選択できます。`MaterialApp` では Material の `SelectionArea` で、`CupertinoApp` では iOS と macOS で Cupertino のハンドルで選択します。デザインライブラリがなければ、メニューのない `SelectableRegion` と、スターター自身のハンドル (`SpringTextSelectionControls`) です。マウスで選択する場所ではハンドルはなく、タッチスクリーンではテーマの primary の色の丸いハンドルが二つ表示されます。
- `#id` へのリンクはその見出しまでスクロールし、それ以外のリンクは `onLink` に渡されます。

## 見出しとテキスト

見出しはタイポグラフィのサイズを使い (`#` は `headline-large`、`##` は `headline-medium`、`###` は `headline-small`、次に `title-large`、`title-medium`、`title-small`)、テキストは `body-large` を使います。Material の `Theme` を持たない `WidgetsApp` では、テーマのテキストスタイルが、ロケールの文字体系に応じた、スターターのタイプスケール (`SpringTypeScale`) の Material 3 のサイズで使われます。

| キー | デフォルト | 意味 |
|---|---|---|
| `styles.heading.color` | テキストの色 | すべての見出しの色 |
| `styles.heading.h1` ... `styles.heading.h6` | `styles.heading.color` | 一つのレベルの色 |
| `styles.link.color` | `$colors.primary` | リンク |

## 表

表の列はそのテキストの幅になり、最大で `cell-width` まで広がり、そこでテキストが折り返されます。ビューより広い表は、列を詰める代わりに横にスクロールするため、スマートフォンでも読めます。ビューより狭い表は、周りのテキストと揃うよう、列をビューの幅まで広げます。

| キー | デフォルト | 意味 |
|---|---|---|
| `styles.table.cell-width` | `280` | テキストが折り返される前に列が広がる最大の幅 |
| `styles.table.fill` | `true` | 狭い表をビューの幅まで広げる。`false` はテキストの幅のままにする |

## コード

インラインとフェンス付きブロックのコードは、`code` テキストスタイル (`typography.code`) と `styles.code` の色を使います。どのキーも省略でき、なければコードはカラースキームに従います。

| キー | デフォルト | 色付けまたは設定するもの |
|---|---|---|
| `styles.code.background` | `$colors.surface-container-highest` | ブロックの塗りとインラインコードの背景 |
| `styles.code.text` | `code` テキストスタイルの色 | 以下に挙げないものすべて |
| `styles.code.keyword` | `$colors.primary` | キーワード、`true`、`false`、`null` |
| `styles.code.string` | `$colors.tertiary` | 文字列、引用符のない YAML と `.properties` の値 |
| `styles.code.comment` | `$colors.outline` | コメント |
| `styles.code.number` | `$colors.secondary` | 数値。単位付きのもの (`120ms`、`35%`) も |
| `styles.code.key` | `$colors.primary` | YAML、`.properties`、JSON のキー。シェルコマンドのオプション |
| `styles.code.annotation` | `$colors.secondary` | アノテーション、YAML のタグ |
| `styles.code.variable` | `$colors.on-tertiary-container` | 参照とプレースホルダー (`$colors.primary`、`${PORT}`、`$HOME`、YAML のアンカー) |
| `styles.code.type` | `$colors.on-secondary-container` | 型の名前 |
| `styles.code.punctuation` | `$colors.on-surface-variant` | 括弧、波括弧、カンマ、コロン |
| `styles.code.inline-text` | `code` テキストスタイルの色 | インラインコード |
| `styles.code.inline-background` | `background` | インラインコードの背景 |
| `styles.code.header` | `background` | タイトルを持つブロックのヘッダー |
| `styles.code.title` | `$colors.on-surface-variant` | ブロックのタイトルとそのコピーボタン |
| `styles.code.padding` | `12` | ブロックの内側の余白: `16`、`[16, 12]` |
| `styles.code.radius` | `6` | 角の半径 |
| `styles.code.border` | なし | 枠線の色 |
| `styles.code.border-width` | `1` | `border` が設定されている場合の枠線の幅 |
| `styles.code.copy` | `true` | ブロックのテキストをコピーするボタン。タイトルを持つブロックではヘッダーに、それ以外では隅に置く。`false` でなし |

言語の後に `title` を持つフェンス付きブロックは、タイトルとコピーボタンを持つヘッダーを得ます。

````markdown
```dart title="lib/orders.dart"
@Service()
class OrderService { ... }
```
````

### コードの言語

スターター自体はどの言語も知りません。フェンス付きブロックのコードが何でできているかは、テーマの `syntax.<language>` から来ます。順に試される正規表現と種類のルール、`keywords`、`types`、`aliases` です。どのテーマも持たない言語のブロックは、`text` の色のプレーンテキストになります。

言語を自分で書くことはまれです。farum-azula/themes リポジトリには、Dart、Java、YAML、プロパティ、シェル、JSON が一つのファイルにあります。`spring.flutter.theme` の `source` で、すべてのテーマのためにそれをダウンロードしてください (上の例のように)。自分で書いた `syntax.<language>` は、ダウンロードしたものより優先されます。ルールについては [スタイルと状態](themes/styles-and-states.md) を参照してください。

## コールアウト

GitHub のコールアウトは、その種類の色の、種類の名前をタイトルとするボックスです。

```markdown
> [!WARNING]
> A missing bean stops the start.
```

| キー | デフォルト | 種類 |
|---|---|---|
| `styles.callout.note` | `primary` | `[!NOTE]` |
| `styles.callout.tip` | `tertiary` | `[!TIP]` |
| `styles.callout.important` | `secondary` | `[!IMPORTANT]` |
| `styles.callout.warning` | `error` | `[!WARNING]` |
| `styles.callout.caution` | `error` | `[!CAUTION]` |

タイトルはメッセージ `markdown.alert.<kind>` です (なければ `Note`、`Tip` など)。そのため `messages_ja.properties` で翻訳できます。

## 長いページ

長いページは数フレームに分けて表示されます。最初のフレームで先頭を、次のフレームごとに残りを一部ずつ表示します (1 フレームあたりテキスト約 3000 文字。表のセルはそれより多く数えます)。そのため、1 つのフレームでページ全体をビルドしてレイアウトすることはありません。表だらけのページは、以前は Web で 1 フレームに 5 分の 1 秒かかっていました。

まだビルドされていない見出しに対する `MarkdownOutline.show(id)` は、先にページの残りをビルドしてからそこへスクロールするので、[ページの見出し](#ページの見出し) はすぐに使えます。

30 行を超える表は、列の幅を 4 つの最も長いセルから一度だけ測り (`styles.table.cell-width` まで)、行を 1 フレームに少しずつ (1 フレームあたり約 1500 文字) 追加します。すべてのセルを 2 回測ることはありません。短い表はこれまでどおりです。設定するものはありません。

## 設定の値

`spring.flutter.markdown.placeholders: true` にすると、ページの `{{key}}` はそれぞれ、設定のそのキーの値に置き換わります。コードブロックの中もです。値のないキーはそのまま残るので、ほかのツールのプレースホルダー (HTTP ファイルの `{{baseUrl}}`) は保たれます。`\{{` は `{{` という文字として書き出されます。`${...}` には触れません。これは設定そのもののプレースホルダーで、ページは例としてそれを見せるからです。

```yaml
# lib/resources/application.yml
site:
  package-version: 0.7.2
spring:
  flutter:
    markdown:
      placeholders: true
```

```markdown
    spring_boot_starter_cache: ^{{site.package-version}}
```

ページには `spring_boot_starter_cache: ^0.7.2` と表示されます。検索エンジン向けにビルドが書くページ、その Markdown のコピー、`llms.txt` も同じようにプレースホルダーを置き換えます。このサイトはビルドのたびに最新のリリースを `site.package-version` に書き込むので、依存関係の例はリリースのあとも書き直す必要がありません。

## ページの見出し

`MarkdownOutline` は、`MarkdownView` が表示するページの見出しを、それぞれ GitHub のアンカー (`## Bean methods` は `#bean-methods`) とともに受け取ります。「このページの内容」のリストに使います。`show(id)` はその一つまでスクロールします。

```dart
final outline = MarkdownOutline();

MarkdownView.resource('resources:content/docs/beans.md', outline: outline);

// ページのセクションのリスト。
ListenableBuilder(
  listenable: outline,
  builder: (context, _) => Column(children: [
    for (final heading in outline.headings.where((h) => h.level == 2))
      TextButton(
        onPressed: () => outline.show(heading.id),
        child: Text(heading.text),
      ),
  ]),
);
```

### 読んでいる見出し

`outline.current` は、ページをスクロールしている間に読んでいる見出しです。画面の上の部分に達した最後の見出しです。読み手が別の見出しに来たときだけ通知するので、自分の項目に印を付けるリストは、スクロールの一歩ごとではなく、セクションごとに一度だけ再構築されます。`currentAmong(shown)` は、一部のレベルだけを表示するリストで印を付ける項目を返します。

```dart
ListenableBuilder(
  listenable: Listenable.merge([outline, outline.current]),
  builder: (context, _) {
    final shown = outline.headings.where((h) => h.level == 2).toList();
    final reading = outline.currentAmong(shown);
    return Column(children: [
      for (final heading in shown)
        Entry(heading, selected: heading == reading),
    ]);
  },
);
```

| いつ | 現在の見出し |
|---|---|
| 最初の見出しより上 | `null` |
| セクションの `###` の中 | その見出し。第 2 レベルの見出しで `currentAmong` を呼ぶと、その `##` を返します |
| ページの終わり | 画面にある最後の見出し。上まで届かなくてもそうなります |
| `show(id)` の後 | ただちにその見出し。読み手がもう一度スクロールするまで続きます |

`MarkdownView` が、自分が入っているスクロール領域から最新の状態に保ちます。手で配線するものはありません。

## ナビゲーションとともに

[spring_boot_starter_flutter_navigation](../spring-boot-starter-flutter-navigation/index.md) の `RouteContentView` は、ルートの Markdown (`@ScreenRoute(content: ...)`) を `MarkdownView` で表示し、アンカー付きのアドレス (`/docs/beans#scopes`) はその見出しで開きます。同じ Markdown ファイルは、検索エンジンのための HTML ページにもなります ([検索エンジン向けのページ](../spring-core-dart-generator/flutter/seo.md) を参照)。

## 関連項目

- [スタイルと状態](themes/styles-and-states.md)
- [タイポグラフィ](themes/typography.md)
- [モーションとアニメーション](themes/motion-and-animations.md)
