スタイルと状態

Material のコンポーネントは、状態 (ホバー、押下、フォーカス、無効など) ごとに見た目を持ちます。独自のウィジェットも同じものを持てます。styles.<name> の下に見た目を書き、各プロパティについて一つの値か、状態ごとの値を書きます。ThemeStates がマウス、フォーカス、タップに従い、正しい値をウィジェットに渡します。

spring:
  flutter:
    theme:
      styles:
        neon-chip:
          padding: [12, 6]
          radius: $shape.small
          border:
            default: $colors.outline
            hovered: $colors.primary
            selected: $colors.primary
          fill:
            default: transparent
            selected: { color: $colors.primary, alpha: 12% }
          text:
            default: $colors.on-surface-variant
            hovered: $colors.primary
            disabled: { color: $colors.on-surface, alpha: 38% }
          transition: 120ms ease-out

プロパティ

プロパティ 型 値 デフォルト 働き
styles.<name> マップ 任意の名前 なし 一つのスタイル。名前はどの綴りでも読まれる: neon-chip、neonChip、neon_chip は同じ
styles.<name>.<property> 値、または状態のマップ 以下の値の種類 なし スタイルの一つのプロパティ。どのプロパティ名でも使える。何を読むかはウィジェットが決める
styles.<name>.<property>.<state> 値 default、hovered、focused、pressed、dragged、selected、scrolled-under、disabled、error なし その状態でのプロパティの値
styles.<name>.transition テキスト <duration> [<curve>] アニメーションなし 状態が変わったときに値が変わるまでの時間と、そのカーブ

値の種類

値は、トークン と同じルールで、見た目によって型が決まります。

種類 書き方 Dart では (StyleValues)
色 #FF40A0、deepPurple、$colors.primary、{ color: $colors.primary, alpha: 12% } values.color('fill')
数値 14、1.5 values.number('radius')
余白 YAML のリスト [12, 6]、または 12, 6 values.insets('padding')
期間 250ms、1.5s、2m、1h、0.5d values.duration('delay')
テキスト それ以外すべて values.text('label')

余白は [all]、[horizontal, vertical]、または [left, top, right, bottom] です。三つ、または五つ以上の数値のリストはエラーです。余白を読む場所では数値を使え、すべての辺で同じ値を意味します。

マップであるプロパティは状態だけを持たなければなりません。別のキーを持つマップは起動を止め、状態を列挙します。

一つの値、または状態ごとの値

spring:
  flutter:
    theme:
      styles:
        field:
          radius: 8                       # すべての状態で同じ
          border:                         # 状態ごとの値
            default: $colors.outline
            focused: $colors.primary
            error: $colors.error

トランジション

transition: <duration> [<curve>] は、状態の間の変化をアニメーションさせます。長さは単位付きの数値 (120ms、0.2s、1h) で、単なるミリ秒の数値でもかまいません。カーブは任意の 名前付きのカーブまたは四つの数値 です。カーブがなければ変化は線形です。transition がなければ値は即座に変わります。

spring:
  flutter:
    theme:
      styles:
        tag:
          fill: { default: transparent, hovered: '#33FFFFFF' }
          transition: $motion.durations.fast ease-out

色、数値、余白、期間は、状態の間で滑らかに混ざります。テキストはトランジションの中間で切り替わります。行き過ぎるカーブ (ease-out-back、elastic-out) でも、パディングが負になることはありません。

状態

状態 ウィジェットがその状態になる時
default 他のどれも当てはまらない、または他のものがこのプロパティの値を持たない
hovered マウスのポインターがその上にある
focused キーボードのフォーカスを持つ
pressed 主マウスボタンまたは指がその上で押されている
dragged ドラッグされている
selected 選択されている (selected 引数)
scrolled-under コンテンツがその下にスクロールしている
disabled 使えない (onPressed が null)
error エラー状態にある (error 引数)

ウィジェットは同時に複数の状態にありえます。各プロパティについて、値を持つ最も強い状態が優先されます。強いものから:

  1. disabled
  2. error
  3. pressed
  4. dragged
  5. hovered
  6. focused
  7. selected
  8. scrolled-under
  9. default

そのため、ホバーされている選択済みのチップは、hovered の値があればそれを、なければ selected の値を、それもなければ default を表示します。各プロパティは独立に決まります。無効なウィジェットで disabled の値を持たないプロパティは、値を持つ次の状態に移ります。

ThemeStates は hovered、focused、pressed、disabled、selected、error を設定します。dragged と scrolled-under は決して設定しません。それらは、独自の状態の集合で StateStyle.resolve を呼ぶコードのためのものです。

ThemeStates

ThemeStates は処理を行うウィジェットです。

ThemeStates(
  style: context.theme.styles.neonChip,
  selected: selected,
  onPressed: onPressed,          // null: チップは無効
  builder: (context, s) => Container(
    padding: s.padding,           // EdgeInsets
    decoration: BoxDecoration(
      color: s.fill,              // Color
      borderRadius: BorderRadius.circular(s.radius),
      border: Border.all(color: s.border),
    ),
    child: Text(label, style: TextStyle(color: s.text)),
  ),
)
引数 型 デフォルト 働き
style ThemeStyle 必須 スタイル: context.theme.styles.<name> (生成される) または StateStyle
builder 関数 必須 現在の状態の値から子を組み立てる
selected bool false ウィジェットが選択されているかどうか
error bool false ウィジェットがエラー状態にあるかどうか
onPressed コールバック なし タップ、クリック、Enter、Space で呼ばれる。null はウィジェットを無効にする
focusNode FocusNode 独自のもの 使うフォーカスノード
autofocus bool false 最初に表示されたときにフォーカスを取る
mouseCursor MouseCursor クリック (無効なときは基本) ウィジェットの上のカーソル
showFocusAlways bool false キーボードだけでなく、どの方法でフォーカスが来ても (タップやクリックでも) focused を表示する。ユーザーがタップしたときに枠が光らなければならないテキスト入力で有効にする。ボタンは Flutter と同じく無効のままにする

マウス、フォーカス、押下に従い、Enter と Space を扱い、カーソルを設定し、transition にわたって値を混ぜます。デバイスが動きを減らすよう求めている場合 (MediaQuery.disableAnimations)、値は即座に変わります。

生成されるクラス

ジェネレーターがあれば、styles.<name> はクラス AppStyle<Name> に、その値はクラス AppStyle<Name>Values になります。そのため、text や button という名前のスタイルが Flutter の TextStyle や ButtonStyle を隠すことはありません。値のクラスは、プロパティごとに型付きのゲッター (Color fill、double radius、EdgeInsets padding、Duration delay、String label) を持ちます。プロパティは、すべてのテーマとすべての状態で一つの種類を持たなければなりません。そうでなければビルドは失敗し、両方の場所を示します。

context.theme.styles.neonChip;     // AppStyleNeonChip、ThemeStyle<AppStyleNeonChipValues>

ジェネレーターがなければ、スタイルを名前で読みます。

final style = SpringTheme.of(context).styles['neonchip']!;   // StateStyle
final values = style.resolve({WidgetState.hovered});
values.color('fill');

コンポーネントの状態ごとの値

Material のアプリのコンポーネントのテーマ (spring_boot_starter_flutter_material が読む) は、Flutter が状態ごとに扱うもの (ボタンの塗り、アウトラインのボタンの辺、チェックボックスの塗り) について、同じ状態と同じ順序で、同じ状態のマップを受け取ります。その書き方と、どのプロパティが状態を受け取るかは、コンポーネントのテーマにあります。

Markdown とコード: styles.code

MarkdownView (と、ルートの Markdown を表示するナビゲーションの RouteContentView) は、その見た目をテーマから得ます。見出しは headline-* と title-* から、テキストは body-large から、リンクは colors.primary から得ます。インラインとフェンス付きブロックのコードは、code テキストスタイル (typography.code) とスタイル styles.code の色を使います。

spring:
  flutter:
    theme:
      typography:
        code: { font-family: JetBrains Mono, size: 13 }
      styles:
        code:
          background: $colors.surface-container-low
          text: $colors.on-surface
          keyword: '#C678DD'     # final、class、true
          string: '#98C379'      # 'text'、"text"
          comment: '#5C6370'     # // と #
          number: '#D19A66'      # 42、1.5
          key: '#E06C75'         # YAML と .properties のキー
          annotation: '#61AFEF'  # @Service
          variable: '#E5C07B'    # $colors.primary、${PORT}、&anchor
          type: '#56B6C2'        # String、Basket、int
          punctuation: '#ABB2BF' # { } [ ] , : -
プロパティ デフォルト 色付けするもの
background $colors.surface-container-highest ブロックの塗りとインラインコードの背景
text code テキストスタイルの色 以下に挙げないものすべて
keyword $colors.primary キーワード、true / false / null
string $colors.tertiary 文字列、引用符のない YAML と .properties の値 (ease-out)
comment $colors.outline コメント
number $colors.secondary 数値。単位付きのもの (120ms、1.5s、35%) も
key $colors.primary YAML、.properties、JSON のキー。シェルコマンドのオプション (--port)
annotation $colors.secondary アノテーション、YAML のタグ (!include)
variable $colors.on-tertiary-container 参照とプレースホルダー: $colors.primary、${PORT}、シェルの $HOME、YAML のアンカーとエイリアス (&base、*base)
type $colors.on-secondary-container Dart の型: String、Basket、int
punctuation $colors.on-surface-variant 括弧、波括弧、カンマ、コロン、リストのダッシュ
inline-text code テキストスタイルの色 インラインコード (`@Bean()`)
inline-background background インラインコードの背景
header background タイトルを持つブロックのヘッダー
title $colors.on-surface-variant ブロックのタイトルとそのコピーボタン

ブロック自体はさらに四つのプロパティを取ります。

プロパティ デフォルト 意味
padding 12 ブロックの内側の余白: 16、[16, 12]
radius 6 角の半径
border なし 枠線の色
border-width 1 border が設定されている場合の枠線の幅
copy true ブロックのテキストをコピーするボタン。title= を持つブロックではヘッダーに、それ以外では隅に置く。false でなし

どのプロパティも省略できます。styles.code がなければコードはカラースキームに従うため、すでにどのテーマにも合います。themes.<name> のテーマは、他のキーと同じく、書いた色だけを上書きします。

フェンス付きブロックは、バッククォートの後に言語を指定します (```dart)。スターター自体はどの言語も知りません。コードが何でできているかは、テーマの syntax.<language> (次のセクション) から来ます。どのテーマも持たない言語のブロックは text の色で表示されます。

コードの言語: syntax

syntax.<language> は、コードを styles.code が色付けする断片に分割します。言語はルールのリストで、それぞれが正規表現とそれが一致するものの種類であり、コードの各位置で順に試されます。最初に一致したものが断片を作ります。

spring:
  flutter:
    theme:
      syntax:
        java:
          aliases: [jav]                    # フェンス付きブロックでの別の名前
          keywords: [class, public, return, new, 'true', 'false', 'null']
          types: '^[A-Z][A-Za-z0-9_]*[a-z]' # 型の名前である単語
          rules:
            - { match: '//[^\n]*|/\*[\s\S]*?\*/', kind: comment }
            - { match: '"(?:\\.|[^"\\\n])*"', kind: string }
            - { match: '@[A-Za-z_][\w.]*', kind: annotation }
            - { match: '\b\d+(?:\.\d+)?\b', kind: number }
            - { match: '[A-Za-z_$][\w$]*', kind: word }
            - { match: '[{}()\[\];,]', kind: punctuation }
プロパティ 意味
rules 必須。それぞれ { match, kind }。match は書いたとおりに解釈される正規表現 ($ の参照なし)。^ と $ は行の始まりと終わり。kind は comment、string、annotation、number、key、keyword、type、variable、punctuation、plain、または word
keywords word のルールが keyword として色付けする単語。YAML が値として読む 'true'、'false'、'null' は引用符で囲む
types 正規表現: これに一致する word のルールの単語は type
aliases フェンス付きブロックでの言語の別の名前 (yaml に対する yml)

どのルールにも一致しないものはプレーンテキストです。不正なルール (未知の種類、コンパイルできない正規表現、ルールのない言語) は、プロパティを示して起動を止めます。

URL からの言語

言語を自分で書くことはまれです。farum-azula/themes リポジトリには、Dart、Java、YAML、プロパティ、シェル、JSON が一つのファイルにあります。spring.flutter.theme 自体の source で、アプリのすべてのテーマのためにそれをダウンロードしてください (URL からのテーマ を参照)。

spring:
  flutter:
    theme:
      source: github:farum-azula/themes/themes/[email protected]
      themes:
        neon:
          syntax:
            java: { ... }   # テーマはそれでも一つの言語を置き換えられる

ダウンロードした値はすべてのテーマで共有され、独自のファイルの下にあります。自分で書いた syntax.<language> が優先されます。

MarkdownView(text, onLink: (href) => launchUrl(Uri.parse(href)));
MarkdownView.resource('resources:content/docs/beans.md');
const MarkdownView.code('server:\n  port: 8080', language: 'yaml'); // 一つのブロック

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

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

リンクは styles.link.color (デフォルトは $colors.primary) を使います。

見出しはタイポグラフィのサイズ (# は headline-large、## は headline-medium、### は headline-small、次に title-large、title-medium、title-small) と styles.heading の色を使います。すべてのレベルには color、一つのレベルには h1 ... h6 です。なければテキストの色になります。

styles:
  heading:
    color: $colors.primary     # すべての見出し
    h1: $colors.on-surface     # ただし # はテキストの色

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

styles:
  table:
    cell-width: 240
    fill: true        # デフォルト

コールアウト

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

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

種類は note、tip、important、warning、caution です。その色は styles.callout.<kind> (デフォルトは primary、tertiary、secondary、error、error) で、タイトルはメッセージ markdown.alert.<kind> です (なければ Note、Tip など)。そのため messages_ja.properties で翻訳できます。

styles:
  callout:
    note: $colors.secondary
    warning: '#FF5C7A'

ページの見出し

MarkdownOutline は、MarkdownView (またはナビゲーションの RouteContentView) が表示するページの見出しを、それぞれ GitHub のアンカー (## Bean methods は #bean-methods) とともに受け取ります。「このページの内容」のリストに使います。show(id) はその一つまでスクロールします。ページ内の #id へのリンクは自動的にスクロールし、アンカー付きのアドレス (/docs/beans#scopes) はその見出しで開きます。

final outline = MarkdownOutline();

RouteContentView(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),
      ),
  ]),
);

リソースの言語

MarkdownView.resource('resources:content/beans.md') は、アプリの言語が日本語でそのファイルが存在する場合、代わりに beans.ja.md を表示し、言語とともに変わります。

MarkdownView.code は、一つのコードブロックを Markdown ページのフェンス付きブロックとまったく同じように表示するため、アプリのすべてのコードサンプルが一つの見た目を共有します。テキストは選択できます。MaterialApp の外 (CupertinoApp、WidgetsApp) では、選択にメニューはありません。

関連項目