MarkdownView
MarkdownView は、GitHub の Markdown を、表示中のテーマの色とテキストスタイルで Flutter のウィジェットとして表示します。見出し、リンク、リスト、表、引用、コールアウト、コードブロックはすべて、どのアプリの種類 (material、cupertino、widgets) でもテーマに従います。コードブロックはテーマの言語で色付けされ、それぞれにテキストをコピーするボタンがあります。
使う理由
ドキュメント、リリースノート、ヘルプページ、法的なテキストは Markdown で書かれます。汎用のパッケージで描画すると、別のアプリのように見えます。ここではそれらはアプリのテーマを使います。ダークテーマならコードブロックも暗くなり、テーマを切り替えると即座に変わり、デザイナーはアプリの残りと同じ YAML でスタイルを付けます。今読んでいるサイトも、この方法でページを表示しています。
例
// 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');
# lib/resources/application.yml
spring:
flutter:
theme:
source: github:farum-azula/themes/themes/[email protected] # コードの言語
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 を持つフェンス付きブロックは、タイトルとコピーボタンを持つヘッダーを得ます。
```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> は、ダウンロードしたものより優先されます。ルールについては スタイルと状態 を参照してください。
コールアウト
GitHub のコールアウトは、その種類の色の、種類の名前をタイトルとするボックスです。
> [!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}}) は保たれます。\{{ は {{ という文字として書き出されます。${...} には触れません。これは設定そのもののプレースホルダーで、ページは例としてそれを見せるからです。
# lib/resources/application.yml
site:
package-version: 0.7.2
spring:
flutter:
markdown:
placeholders: true
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) はその一つまでスクロールします。
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) は、一部のレベルだけを表示するリストで印を付ける項目を返します。
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 の RouteContentView は、ルートの Markdown (@ScreenRoute(content: ...)) を MarkdownView で表示し、アンカー付きのアドレス (/docs/beans#scopes) はその見出しで開きます。同じ Markdown ファイルは、検索エンジンのための HTML ページにもなります (検索エンジン向けのページ を参照)。