
# デザインライブラリ

`spring_boot_starter_flutter` はデザインライブラリを知りません。Flutter の `widgets` ライブラリだけをインポートし、`spring.flutter.app.type: widgets` (デザインのスターターがないアプリの種類) のアプリのビルドには、Material も Cupertino も入りません。Material と Cupertino は、それぞれ専用のスターター [spring_boot_starter_flutter_material](../spring-boot-starter-flutter-material/index.md) と [spring_boot_starter_flutter_cupertino](../spring-boot-starter-flutter-cupertino/index.md) で加わります。

## 使う理由

Flutter 3.50 は Material と Cupertino を SDK の外に出しました。`package:flutter/material.dart` と `package:flutter/cupertino.dart` は非推奨になり、ライブラリは Flutter チームのパッケージ `material_ui` と `cupertino_ui` になっています。それらをインポートするスターターは、アプリが何を表示するかに関係なく、両方をすべてのアプリに入れてしまいます。そこで Flutter のスターターは、すべてのアプリが必要とするもの (アプリケーション、ウィジェットの中の Bean、プロパティからのテーマ、スプラッシュ、メッセージ、デバッグパネル) を持ち、デザインに属するものはデザインのスターターに移しました。

独自のウィジェットを描くアプリは、より小さなビルドを得ます。独自のデザインシステムも、二つのスターターと同じ方法で組み込めます。

## 三つのアプリの種類

| `spring.flutter.app.type` | アプリのウィジェット | 必要なスターター | アプリが列挙する UI ライブラリ |
|---|---|---|---|
| `widgets` (デザインのスターターがないとき) | `WidgetsApp` | なし: `spring_boot_starter_flutter` | なし |
| `material` | `MaterialApp` | `spring_boot_starter_flutter_material` | `material_ui` |
| `cupertino` | `CupertinoApp` | `spring_boot_starter_flutter_cupertino` | `cupertino_ui` |

種類はテキストです。`SpringAppFactory` の Bean を名前で指します。Flutter のスターターは `widgets` のものを持ち、デザインのスターターはそれぞれ自分のものを加え、独自のデザインはもう一つの Bean になります。スターターのない種類は起動を失敗させ、加えるべきスターターの名前を挙げます。未知の種類は、アプリケーションが持つ種類を挙げて起動を失敗させます。

```yaml
# Material のアプリの pubspec.yaml
dependencies:
  material_ui: ^1.11.0
  spring_boot_starter_flutter_material: ^0.9.0
```

デザインのスターターは Flutter のスターターを持ち込み、再エクスポートするので、アプリは代わりにデザインのスターターを列挙します。

### 種類は推定される

`spring.flutter.app.type` は設定しなくてもかまいません。Spring Boot がクラスパスから `spring.main.web-application-type` を推定するのと同じように、アプリケーションのスターターが決めます。上の Material のアプリはデザインのスターターが一つなので、設定を一行も書かずに `material` の種類になります。

- デザインのスターターが一つ、または独自の種類の `SpringAppFactory` Bean が一つ: アプリはその種類になります。
- なし: `widgets` です。
- 複数の種類のアプリファクトリー (たとえば二つのデザインのスターター): 起動はプロパティと種類を示して失敗し、一つを選ぶよう求めます。

Android では Material、iOS では Cupertino のアプリは両方を列挙するので、種類を設定します。すべてのプラットフォーム向けに設定し、プロファイルでプラットフォームごとにもう一度設定します。

```yaml
# lib/resources/application.yml
spring.flutter.app.type: material
```

```yaml
# lib/resources/application-ios.yml
spring.flutter.app.type: cupertino
```

設定されていれば、プロパティが常に優先されます。デザインのスターターが別のパッケージ経由で入ってきても、`widgets` なら `WidgetsApp` のままです。アプリケーションにデザインのスターターもあるとき、独自のデザインはその種類で選ばれます。

## デザインなしで動くもの

`widgets` のアプリは、`spring.flutter.theme.*` のうちデザインに属さないテーマのすべてを持ちます。

- **パレット。** Flutter のベースラインのパレット (Material 3 のベースライン、`SpringColorScheme.baseline`) に、`colors.*` に設定したロールを重ねたもの。`SpringTheme.of(context).colorScheme` は、Material 3 の名前で 46 のロールすべてを持ちます。
- **タイプスケール。** 15 のテキストスタイル (`display-large` ... `label-small`) は、Material 3 のタイプスケールのサイズとプラットフォームのデフォルトのフォントを持ちます (`SpringTypeScale`)。つまり Material なしで、`MaterialApp` が与えるものと同じです。`localizedTextStyle(style, script)` は文字体系のサイズを与えます (中国語、日本語、韓国語は dense、アラビア語、ヒンディー語、タイ語は tall)。
- **テーマの残り。** 余白、形状、エレベーション、トークン、状態のスタイル、背景、画像、ローダー、スプラッシュ、そしてページ遷移 `fade`、`fade-upwards`、`content`、`none`。Material 3 のイージングはスターターの数値です (`ThemeValues.standardEasing`)。
- **`MarkdownView`**。テーマのテキストスタイルと、スターター自身の選択ハンドル (`SpringTextSelectionControls`) を使います。マウスで選択する環境ではハンドルなし、タッチスクリーンではテーマの primary の色の丸いハンドルが二つです。
- セキュリティのスターターの**ログインフォーム**。`SpringTheme` から描かれる素のウィジェットになります。

## デザインが必要なもの

次のものは、デザインのスターターがなければ起動を失敗させ、メッセージがスターターの名前を挙げます。

| プロパティ | 理由 | スターター |
|---|---|---|
| `seed-color`、`scheme-variant`、`contrast` | シードからのパレットは Material 3 のアルゴリズム | どちらのデザインのスターターでも: 両方が同じパレットを作る |
| `motion.page-transition: zoom` | Material の遷移 | `spring_boot_starter_flutter_material` |
| `motion.page-transition: cupertino` | スワイプで戻れる iOS のスライド | `spring_boot_starter_flutter_cupertino` |

デザインがなければ、テーマはシードの代わりに `colors.*` にロールを書きます。設定しないものはベースラインです。リポジトリの例の neon テーマはそうしています。使うロールをすべて挙げ、`seed-color` を持ちません。ナビゲーションのスターターで画面自身が持つ `zoom` や `cupertino` の遷移は、起動の失敗にはなりません。ログに報告され、ページは遷移なしで表示されます。`platform` は、これまでどおり、デザインがなければ遷移なしです。

## 検査されずに受け付けられるもの

デザインのテーマのプロパティは、そのスターターのないアプリでも受け付けられます。テーマのライブラリはそのデザインのアプリのためにそれらを持ち、別のデザインのアプリはそれを表示しないだけです。Flutter が `MaterialApp` の外で `ThemeData` を表示しないのと同じです。

| プロパティ | 読むもの |
|---|---|
| `components.*` | `spring_boot_starter_flutter_material` |
| `visual-density` | `spring_boot_starter_flutter_material` |
| `tap-target-size` | `spring_boot_starter_flutter_material` |
| 一つの値の `splash` (`ripple`、`sparkle`、`none`: インクのスプラッシュ) | `spring_boot_starter_flutter_material` |
| `cupertino.*` | `spring_boot_starter_flutter_cupertino` |

スターターがなければ、表示も検査もされません。`spring_boot_starter_flutter.SpringThemes` の INFO の 1 行が、それぞれを一度だけ挙げます。

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

キーは引き続き検査されます。`componets` は起動を失敗させます。`splash` のマップはデザインのものではありません。起動時のスプラッシュ画面で、すべてのアプリが読みます。`SpringThemeData.unreadDesignProperties` は、テーマの読まれないプロパティを、それぞれを読むスターターとともに挙げます。

## 独自のデザイン

デザインシステム (会社独自のウィジェット、たとえば「Ocean」) は、Material と Cupertino と同じ四つの点から組み込みます。どれも `spring_boot_starter_flutter` にあり、テーマの部分はライブラリ `package:spring_boot_starter_flutter/theme_design.dart` にあります。

### テーマ: ThemeDesign

`ThemeDesign` は、デザインが加えるものをテーマに伝えます。アプリの種類、そのウィジェットだけが読むテーマのプロパティ、シードから作るパレット、ページ遷移、起動時のプロパティの検査です。

```dart
import 'package:flutter/widgets.dart';
import 'package:spring_boot_starter_flutter/theme_design.dart';

final class OceanDesign implements ThemeDesign {
  const OceanDesign();

  @override
  String get appType => 'ocean';

  @override
  List<String> get themeProperties => const ['ocean'];   // spring.flutter.theme.ocean.*

  @override
  List<String> get schemeVariants => const [];           // パレットの作り方は一つ

  @override
  SpringColorScheme colorScheme(ColorSchemeSpec spec) =>
      OceanPalette.of(spec.seedColor ?? OceanPalette.seed, spec.brightness);

  @override
  PageTransitionsBuilder? pageTransition(PageTransitionType type) => null;

  @override
  void check(SpringThemeData theme) {
    // テーマの `ocean` のプロパティをここで読む: 誤った値は、プロパティの名前を
    // 挙げる ThemePropertyException を投げ、起動が失敗する。
  }
}
```

テーマは Bean が存在する前に読まれる (起動時のスプラッシュがテーマの中にある) ため、デザインは Bean ではありません。スターターは、それをモジュールのファクトリーに挙げます。

```dart
// デザインのパッケージの lib/spring_auto_configuration.dart
@AutoConfigurationModule(factories: [OceanDesign()])
final BeanModule oceanAutoConfiguration = $oceanBeans;
```

ジェネレーターはすべてのスターターのファクトリーを生成されたアプリケーションにコピーし、`SpringThemes` は `SpringApplication.factories.load<ThemeDesign>()` でデザインを見つけます。`factories` については [自動構成](../spring-boot-dart/auto-configuration.md) を参照してください。

### アプリのウィジェット: SpringAppFactory

`SpringAppFactory` を実装する Bean が、その種類のアプリのウィジェットを作ります。`SpringAppRequest` は、`spring.flutter.app.*` の設定、テーマ、表示中のテーマ、スターターの `builder` (そのまま渡します)、そして `home` かアプリケーションのルーターを持ちます。

```dart
@Component()
class OceanAppFactory implements SpringAppFactory {
  @override
  String get type => 'ocean';

  @override
  List<LocalizationsDelegate<Object?>> get localizationsDelegates =>
      const [GlobalWidgetsLocalizations.delegate];

  @override
  Widget build(BuildContext context, SpringAppRequest app) => OceanApp(
    title: app.settings.title,
    theme: OceanTheme.of(app.shown),
    builder: (context, child) => DesignScope(
      textStyle: (context, style) => OceanTheme.of(app.shown).text[style],
      selectable: (context, child) => OceanSelectionArea(child: child),
      controls: const OceanControls(),
      child: app.builder(context, child),
    ),
    home: app.home,
  );
}
```

### ページのルート: DesignPageRoutes

ナビゲーションのスターターのルーターは、遷移が `platform` か `cupertino` のページのルートを、`DesignPageRoutes` の Bean に `@Order` の順で尋ね、最初に得たルートを表示します。デザインの Bean は自分のアプリの種類のときに答え、それ以外では `null` を返します。`heroController(appType)` は、そのナビゲーターのヒーローの飛び方を与えます。

```dart
@Component()
class OceanPageRoutes implements DesignPageRoutes {
  @override
  PageRoute<Object?>? pageRoute(
    PageTransitionType transition,
    String appType,
    SpringPageRequest page,
  ) => transition == PageTransitionType.platform && appType == 'ocean'
      ? OceanPageRoute(settings: page.settings, builder: page.childOf)
      : null;

  @override
  HeroController? heroController(String appType) => null;
}
```

### スターター自身のウィジェット: DesignScope と DesignControls

`MarkdownView` とセキュリティのスターターのログインフォームは、デザインを知りません。アプリのページの上にある `DesignScope` (上の例のようにファクトリーの `builder` の中) が、それらにデザインのテキストスタイル (`textStyle`、スタイルの正規の名前 `titlelarge` で。`null` なら `SpringTheme` のもの)、テキストの選択の仕方 (`selectable`)、フォームのコントロール (`controls`) を与えます。`DesignControls` は、テキストフィールド (`DesignTextField`)、塗りつぶしのボタン (`DesignButton`)、エラーの色、そしてコントロールがその上に必要とするもの (`surface`) を描きます。`DesignControls` の Bean は、手で書いたアプリのウィジェットの下でも、その `isAppAbove(context)` がデザインのアプリがあると答えれば見つかります。

## ビルドのサイズ

このサイトは `widgets` の Flutter の Web アプリです。Flutter 3.50 でビルドすると、そのバンドルは、Material と Cupertino を持っていた 0.7 のスターターでの 4.39 MB から、デザインライブラリなしの 3.53 MB になりました (gzip: 1.31 MB から 1.09 MB)。ページはピクセル単位で同じです。

## Spring (Java) との対応

Spring にデザインライブラリはありません。似ているのは仕組みです。アプリの種類は名前で Bean を選びます。Spring Boot のプロパティが自動構成された実装の中から選ぶのと同じです。設定されていなければスターターから推定されます。Spring Boot がクラスパスから Web アプリケーションの種類を推定するのと同じです (ただし候補が二つあると、Spring Boot が reactive より servlet を優先するように一方を選ぶのではなく、起動が失敗します)。そして Bean より前に存在しなければならないデザインはスターターのファクトリーです。Spring Boot が `META-INF/spring.factories` のエントリーを `SpringFactoriesLoader` で見つけるのと同じです。

## 関連項目

- [spring_boot_starter_flutter_material](../spring-boot-starter-flutter-material/index.md)
- [spring_boot_starter_flutter_cupertino](../spring-boot-starter-flutter-cupertino/index.md)
- [0.8 への移行](moving-to-0-8.md)
- [テーマ](themes/index.md)
- [アプリのウィジェット](app-widget.md)
