スタイルと状態
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
- 状態を持つプロパティには
defaultが必要です。他のどの状態も当てはまらないときの値です。 - プロパティのすべての状態は同じ種類を持ちます。余白の隣の数値は余白に広げられます。色と数値を混ぜるとエラーです。
- 一つの状態だけについて書いたプロパティは、
defaultを持つ限りエラーではありません。
トランジション
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 引数) |
ウィジェットは同時に複数の状態にありえます。各プロパティについて、値を持つ最も強い状態が優先されます。強いものから:
disablederrorpresseddraggedhoveredfocusedselectedscrolled-underdefault
そのため、ホバーされている選択済みのチップは、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) では、選択にメニューはありません。
関連項目
- トークンと参照: 値の型の決まり方と参照のしかた
- モーションとアニメーション: カーブと長さ
- 形状、余白、エレベーション
- コンポーネントのテーマ: Material のコンポーネントの状態ごとの値
- タイポグラフィ:
codeテキストスタイル