プロパティからのテーマ

このスターターを持つアプリでは、spring.flutter.theme.* のすべてのテーマが Material の ThemeData でもあります。テーマは一度だけ、すべてのアプリが共有するプロパティ (色、タイポグラフィ、形状、モーション、背景: テーマ を参照) と、Material だけが持ついくつかのプロパティで書きます。スターターは各テーマの ThemeData を作り、MaterialApp、Theme.of(context)、すべての Material のウィジェットがそれを使います。Flutter 自身の Material 3 のテーマと異なるのは、プロパティが設定したものだけです。

使う理由

Material のアプリは、ふつう ThemeData を Dart で組み立てます。ColorScheme、TextTheme、十数個のコンポーネントのテーマを、ライトとダークで一度ずつです。ここでは、同じテーマが設定です。デザイナーが application.yml を変え、プロファイルがプラットフォームごとにそれを変え、実行時にダウンロードされたテーマがリリースなしにそれを変えます。そして同じファイルが、Material のアプリ、Cupertino のアプリ、デザインライブラリのないアプリに使えます。

例

フレームワークの例の Theme Showcase の Material のアプリから:

# lib/resources/application.yml
spring:
  flutter:
    theme:
      active: system
      seed-color: '#3F51B5'
      scheme-variant: tonalSpot
      typography:
        font-family: Inter
        title-large: { weight: 600 }
      shape:
        medium: 16
      components:
        app-bar:
          center-title: true
          background-color: $colors.primary-container
        card:
          elevation: 2
      themes:
        dark:
          brightness: dark
        ocean:
          extends: light
          seed-color: teal
          scheme-variant: vibrant
          shape: { medium: 20, large: 28 }
          colors:
            secondary: '#0277BD'
          components:
            card: { elevation: level0 }
        ocean-night:
          extends: ocean
          brightness: dark
spring.flutter.theme.active=system
spring.flutter.theme.seed-color=#3F51B5
spring.flutter.theme.scheme-variant=tonalSpot
spring.flutter.theme.typography.font-family=Inter
spring.flutter.theme.typography.title-large.weight=600
spring.flutter.theme.shape.medium=16
spring.flutter.theme.components.app-bar.center-title=true
spring.flutter.theme.components.app-bar.background-color=$colors.primary-container
spring.flutter.theme.components.card.elevation=2
spring.flutter.theme.themes.dark.brightness=dark
spring.flutter.theme.themes.ocean.extends=light
spring.flutter.theme.themes.ocean.seed-color=teal
spring.flutter.theme.themes.ocean.scheme-variant=vibrant
spring.flutter.theme.themes.ocean.colors.secondary=#0277BD
spring.flutter.theme.themes.ocean-night.extends=ocean
spring.flutter.theme.themes.ocean-night.brightness=dark

ウィジェットは、どの Material のアプリとも同じようにテーマを読みます。

final scheme = Theme.of(context).colorScheme;
final title = Theme.of(context).textTheme.titleLarge;
Card(color: scheme.surfaceContainerLow, child: Text('Ocean', style: title));

ThemeData の作られ方

  1. Flutter のスターターがテーマを読みます。 SpringThemeData に、light または dark の層、ルート、extends、テーマ自身のキーを読み、すべての $ の参照を解決します。これはどのアプリでも同じです。
  2. パレットが作られます。 このスターターのデザインが、seed-color、scheme-variant、contrast から Material の ColorScheme.fromSeed で、どれも設定されていなければ Flutter のベースラインから作り、その上に colors.* のロールを置きます (シードからのパレット を参照)。
  3. ThemeData が作られます。 テーマから (toMaterial())。その後、components.* の下の各コンポーネントがそれに適用されます。
  4. ThemeCustomizer Bean がそれを変更します。 @Order の順です。theme または darkTheme という名前の ThemeData Bean は、それより前に、作られた light または dark のテーマに取って代わります (コードでのテーマ を参照)。
  5. MaterialThemes Bean が結果を保持します。 テーマごとに一度だけ作られ、MaterialApp がそれを表示します。

Flutter のスターターから来るもの

これらの部分は Flutter のスターターのプロパティで、どのアプリでも同じです。このスターターは、それらを Material のテーマに置き場所のあるところに置きます。

テーマのプロパティ ThemeData では
46 のパレットのロール: colors.*、またはシードから作られたもの colorScheme: テーマのパレットのすべてのロールを持つ Material の ColorScheme
typography.font-family、typography.font-family-fallback fontFamily、fontFamilyFallback
15 のテキストスタイル (display-large ... label-small) textTheme: テーマが設定したスタイルは Material のものを置き換え、それ以外は Material のまま
shape.* 専用のフィールドはない: トークンに従うコンポーネント (カードは medium、ダイアログは extra-large、ボタンは full、...) は、テーマがそのトークンを変えるとそれを受け取り、コンポーネントの shape: large はそれを読む (コンポーネント を参照)
elevation.* コンポーネントの elevation: level2 がそのレベルを読む
motion.page-transition pageTransitionsTheme: すべてのプラットフォームで同じトランジション。platform (または何も設定しない) では、プラットフォームごとの Flutter 自身のもの
background scaffoldBackgroundColor が透明になり、すべての Scaffold 越しに背景が見える
Material に置き場所のないもの: spacing、tokens、styles、code のスタイル、animations、loaders extensions の中の SpringThemeExtension (後述 を参照)

このスターターが追加するもの

テーマのプロパティ ThemeData では ページ
seed-color、scheme-variant、contrast それらから Material 3 が作るパレット シードからのパレット
components.<name>.* 約 50 のコンポーネントのテーマ: cardTheme、appBarTheme、filledButtonTheme、inputDecorationTheme、... コンポーネントのテーマ
visual-density visualDensity 密度とインク
tap-target-size materialTapTargetSize 密度とインク
splash (一語) splashFactory 密度とインク
motion.page-transition: zoom ZoomPageTransitionsBuilder: Material のズームのトランジション モーション

どれも名前付きのテーマの中にも書けます (themes.<name>.components.card.*)。seed-color、scheme-variant、contrast は Cupertino のスターター も同じ色で計算します。それ以外は Material だけのものです。

ライト、ダーク、システム

light と dark は常に存在します。表示されるものは spring.flutter.theme.active が選びます。

active MaterialApp が受け取るもの
system (デフォルト) theme: system-light のテーマ (デフォルトは light)、darkTheme: system-dark のテーマ (デフォルトは dark)、themeMode: ThemeMode.system。Material はデバイスに従ってそれらを切り替える
テーマの名前 theme: そのテーマ、themeMode: ThemeMode.light。ダークのテーマは、パレットがダークなので、そのまま表示される

ThemeSelection Bean は実行時に選択を変え、アプリは新しいテーマを即座に表示します。

class ThemeMenu extends SpringStatelessWidget<(ThemeSelection,)> {
  const ThemeMenu({super.key});

  @override
  Widget build(BuildContext context) {
    final (selection,) = beans;
    return PopupMenuButton<String>(
      onSelected: selection.select,
      itemBuilder: (_) => [
        for (final name in ['system', 'light', 'dark', 'ocean'])
          PopupMenuItem(value: name, child: Text(name)),
      ],
    );
  }
}

system-light、system-dark、remember、extends については テーマ を参照してください。

実行時に読み込まれるテーマ

テーマは起動の後に届くこともあります。プロパティの中の URL から (themes.<name>.source。URL からのテーマ を参照)、またはコードから SpringThemes Bean で読み込みます。

@Service()
class WinterThemes {
  WinterThemes(this.themes, this.selection);

  final SpringThemes themes;
  final ThemeSelection selection;

  Future<void> show() async {
    themes.loadYaml(
      await http.read(Uri.parse('https://themes.example.com/winter.yml')),
    );
    selection.select('winter');
  }
}

読み込まれたテーマは、ファイルのテーマと同じように、Material の部分も含めてチェックされます。未知のコンポーネントや誤った値は ThemePropertyException を投げ、何も変えません。その後、MaterialThemes Bean が、最初に表示されるときに、その ThemeData を (カスタマイザーとともに) 作ります。

このスターターが読むプロパティ

キー 値 デフォルト 働き
spring.flutter.theme.seed-color 色 なし パレットを作る元の色
spring.flutter.theme.scheme-variant tonalSpot、fidelity、content、vibrant、expressive、monochrome、neutral、rainbow、fruitSalad tonalSpot シードからパレットをどう作るか
spring.flutter.theme.contrast -1 から 1 0 パレットのコントラスト
spring.flutter.theme.components.<name>.* コンポーネントのリファレンス を参照 Flutter のもの 一つの Material のコンポーネントのテーマ。Flutter のプロパティ名をケバブケースで
spring.flutter.theme.visual-density adaptive、standard、comfortable、compact プラットフォームごとの Flutter のもの Material のコントロールをどれだけ密に並べるか
spring.flutter.theme.tap-target-size padded、shrink-wrap プラットフォームごとの Flutter のもの タップが当たる最小の領域
spring.flutter.theme.splash ripple、sparkle、none プラットフォームごとの Flutter のもの タップのインク。splash の下のマップは別物で、すべてのアプリが読む起動時のスプラッシュ画面
spring.flutter.theme.motion.page-transition zoom Material のズームのトランジション。それ以外の値は Flutter のスターターのもの

起動時にチェックされる

スターターは、ウィジェットが最初に必要とするときではなく、アプリケーションの起動時にすべてのテーマの自分の部分を読みます。未知のコンポーネントやプロパティ、誤った値、Flutter が拒む組み合わせは起動を失敗させ、プロパティと有効な値を示し、近いものがあれば "did you mean" を添えます (ここではリストを短くしています)。

Invalid theme property spring.flutter.theme.components.crad (theme light): ''; expected a component: app-bar, badge, banner, ... (did you mean 'card'?).

実行時に読み込まれたテーマも、何かを置き換える前に、同じようにチェックされます。

このスターターがない場合

このスターターのないアプリでも、テーマは components、visual-density、tap-target-size、一つの値の splash を持てます。テーマのライブラリは、Material を使うアプリのためにそれらを持つからです。その場合それらは受け付けられますが、表示もチェックもされず、それぞれについて一度、ログの INFO の 1 行がそれを伝えます。

The theme property components is not shown and not checked: spring_boot_starter_flutter_material, which reads it, is not in the application.

キーはそれでもチェックされます。componets は起動を失敗させます。SpringThemeData.unreadDesignProperties は、それぞれを読むスターターとともに、それらを列挙します。seed-color、scheme-variant、contrast、zoom のトランジションは異なり、デザインのスターターがなければ、それを示して起動を失敗させます。両方のデザインのスターターを持つアプリでは、Material のプロパティはアプリの種類にかかわらず読まれ、チェックされます。デザインライブラリ を参照してください。

テーマを読む

Material のウィジェットは Theme.of(context) を読みます。Material のテーマに置き場所のないものは、どのアプリでも SpringTheme にあります。

final theme = SpringTheme.of(context);
final gap = theme.space('m');
final code = theme.textStyle('code');

Material の ThemeData しか手元にないコード (関数に渡された ThemeData、独自の Theme の下のウィジェット) は、作られたすべての ThemeData が持つ拡張を通じてそれに届きます。

final spring = Theme.of(context).extension<SpringThemeExtension>()!.data;
final gap = spring.space('s');

表示されているもの以外のテーマは、Material の ThemeData として、アプリのものと同じようにカスタマイズされて、MaterialThemes Bean から得られます。

// ウィジェットの中では: 注入された Bean。
class OceanPreview extends SpringStatelessWidget<(MaterialThemes,)> {
  const OceanPreview({super.key});

  @override
  Widget build(BuildContext context) {
    final (themes,) = beans;
    return Theme(data: themes.theme('ocean'), child: const PreviewCard());
  }
}

// ウィジェットの外では: アプリケーションコンテキストから。
final ocean = MaterialThemes.of(applicationContext).theme('ocean');

SpringThemeData.toMaterial() は一つのテーマの ThemeData をカスタマイザーなしで返し、materialColorScheme はそのパレットを Material の ColorScheme として返します。

Spring (Java) との対応

相当するものはありません。Spring にはアプリのテーマがありません。

関連項目