
# キーボードショートカットとタップ

アクションのキーは設定で、そのハンドラーは Bean のメソッドです。`application.yml` に `search.open: primary+k` と書き、メソッドに `@Shortcut('search.open')` を付けます。`primary` は Apple のプラットフォームでは ⌘、それ以外では Ctrl なので、一行ですべてのプラットフォームに対応します。アクションは、素早い 4 回のタップと 3 秒間押し続ける 5 回目のタップのような、画面のタップのパターンにも割り当てられます。デスクトップと同じくスマートフォンでも使えます。

## 使う理由

ウィジェットのコードに書いたキーはビルドごとに固定され、見つけにくいものです。設定にあれば、コードに触れずにプラットフォームやプロファイルごとに変えられ (`application-macos.yml`)、画面は表示中にアクションを引き受けることができ、ラベルは同じ場所からプラットフォームの流儀でキーを表示します。

## 例

```yaml
# lib/resources/application.yml
spring:
  flutter:
    shortcuts:
      search.open: [primary+k, slash]           # macOS では ⌘K か /、それ以外では Ctrl+K か /
      navigation.back: [alt+left, primary+bracket-left]
      help.show: char:?                         # どのキーで入力するかにかかわらず、その文字
      debug.open: [primary+shift+d, taps:5+hold:2s]
```

```dart
@Component()
class SearchActions {
  // keys: 設定がこのアクションに何も指定しない場合に使われる。
  @Shortcut('search.open', keys: ['primary+k'])
  void open(BuildContext context) => SearchDialog.show(context);
}
```

```dart
// 同じ設定から、Mac では "⌘K"、それ以外では "Ctrl+K" と表示する。
const ShortcutLabel('search.open')
```

## キーの書き方

| 形式 | 意味 |
|---|---|
| `primary+shift+k` | 修飾キーと一つのキーを `+` でつなぐ |
| `char:?` | 入力される文字。どのキーボードレイアウトでも |
| `taps:4+hold:3s` | キーではなく画面のタップ (後述) |
| リスト | そのいずれか: `[primary+k, slash, taps:3]` |

修飾キー: `primary` (Apple のプラットフォームでは ⌘、それ以外では Ctrl)、`shift`、`alt` (または `option`)、`control` (または `ctrl`)、`meta` (または `cmd`)。

キー: 英字、数字、`f1` から `f12`、`enter`、`escape`、`space`、`tab`、`backspace`、`delete`、`home`、`end`、`page-up`、`page-down`、`up`、`down`、`left`、`right`、`slash`、`backslash`、`comma`、`period`、`semicolon`、`quote`、`minus`、`equal`、`bracket-left`、`bracket-right`、`backquote`。

どの記法でも読めない値は、プロパティを示して起動を止めます (`spring.flutter.shortcuts.search.open: 'moon' is no key ...`)。二つのアクションに同じキーを与えると、警告がログに出ます。

## タップのパターン

`taps:<n>` は、画面のどこでもよい素早いタップで、1 から 10 回です。`+hold:<time>` (`ms` または `s`) を付けると、最後の押下をその時間押し続けます。付けなければ、最後のタップがショートカットになります (`taps:3`)。指、ペン、マウスで、すべてのプラットフォームで動きます。

- リッスンするだけです。すべてのタッチは引き続きアプリに届きます。
- 一回のタップは最大 300 ms で、二つのタップの間隔は最大 400 ms です。
- 18 ポイントより多く動いた指はスクロールとみなされ、パターンは最初からになります。

キーボードのないスマートフォンでの隠れたアクション、例えば [デバッグパネル](debug-panel.md) (デフォルトは `taps:4+hold:3s`) に使ってください。

## ハンドラー

アクションのハンドラーには、どれかが押下を処理するまで、順序の小さいものから順に問い合わせます (`@Shortcut(order:)`、または `Ordered`)。

**`@Shortcut` メソッド**は Bean の上にあり、何も取らないか、`BuildContext` (フォーカスのあるウィジェットのもので、ナビゲーターの下にあるため、ダイアログを表示できます)、または `ShortcutInvocation` (アクションとコンテキスト) を取ります。何も返さない (処理済み) か、`bool` を返します。`false` は押下を次へ渡します。それ以外のシグネチャーは起動を止めます。

```dart
@Component()
class EditorActions {
  EditorActions(this.drafts);

  final Drafts drafts;

  // 保存するものがあるときだけ保存する。なければ押下は次へ進む。
  @Shortcut('editor.save', keys: ['primary+s'], order: 10)
  bool save() {
    if (!drafts.hasChanges) return false;
    drafts.save();
    return true;
  }
}
```

**`ShortcutHandler` Bean** はその `action` を処理します。`Ordered` を使うと、他のものの間で自分の位置を取ります。`KeyedShortcutHandler` は、`@Shortcut(keys:)` と同じく、アクションのデフォルトのキーも指定します。

```dart
@Component()
class HelpHandler implements KeyedShortcutHandler {
  @override
  String get action => 'help.show';

  @override
  List<String> get keys => const ['f1', 'char:?'];

  @override
  bool handle(ShortcutInvocation invocation) {
    final context = invocation.context;
    if (context == null) return false;
    HelpSheet.show(context);
    return true;
  }
}
```

**画面自身のハンドラー**はウィジェットツリーの中にあり、フォーカスがその下にある間は最初に問い合わせを受けます。それらが持たないアクションや、`false` を返したハンドラーは、上のハンドラー、そして Bean へと進みます。

```dart
ShortcutHandlers(
  handlers: {
    'editor.save': (_) => draft.save(),
    'search.open': (_) => searchInThisBook(), // アプリの検索の代わりに
  },
  child: EditorPage(draft),
)
```

単なるキー (`slash`、`char:?`) は、テキストフィールドにフォーカスがある間は無視されるため、引き続き入力されます。Ctrl、⌘、Alt を伴うキーはそこでも動きます。

## キーを表示する

`ShortcutLabel('search.open')` は、同じ設定から、アクションの最初のキーをプラットフォームの流儀 (`⌘K`、`Ctrl+K`) で書きます。`ShortcutLabel.of(context, action)` は、ツールチップやメニューのためにそのテキストを返します。

## 組み込まれる場所

スターターはショートカットをアプリのナビゲーターの周りに組み込みます (`FlutterAppCustomizer` を通じた `KeyboardShortcutsScope`)。そのためハンドラーはナビゲーターの下のコンテキストを受け取ります。独自の `MaterialApp` を持つアプリは、そのスコープを `builder` に置きます。

```dart
MaterialApp(
  builder: (context, child) => KeyboardShortcutsScope(
    shortcuts: context.bean<KeyboardShortcuts>(),
    child: child!,
  ),
  home: const BookListPage(),
)
```

## 独自の記法

別の方法で書かれたキー (`numpad:5`、コード) を読むには、`ShortcutNotation` Bean を宣言します。記法は責任の連鎖を成します。アプリ独自のものに最初に問い合わせ (`@Order` の順)、次に `CharacterNotation`、`TouchPatternNotation`、`KeyCombinationNotation` です。

```dart
@Component()
class NumpadNotation implements ShortcutNotation {
  @override
  bool supports(String text) => text.startsWith('numpad:');

  @override
  ShortcutKeys parse(String text, TargetPlatform platform) => ...;
}
```

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.flutter.shortcuts.<action>` | キー、タップのパターン、またはそのリスト | なし。アクションの `@Shortcut(keys:)` または `KeyedShortcutHandler.keys` | アクションのハンドラーを実行するキーやタップ。アクション名はキーの残りの部分 (`spring.flutter.shortcuts.search.open`) |

スターターが知っているアクション: [デバッグパネル](debug-panel.md) を開く `debug.open` (`primary+shift+d`、`taps:4+hold:3s`)。

## Spring (Java) との対応

Spring には UI がないため、対応するものはありません。モデルは Spring のハンドラーマッピングのものです。設定の中の名前、それを処理する Bean のメソッド、複数のものの間の順序です。

## 関連項目

- [デバッグパネル](debug-panel.md)
- [アプリのウィジェット](app-widget.md)
- [すべてのプロパティ](properties.md)
