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

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

使う理由

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

例

# 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]
@Component()
class SearchActions {
  // keys: 設定がこのアクションに何も指定しない場合に使われる。
  @Shortcut('search.open', keys: ['primary+k'])
  void open(BuildContext context) => SearchDialog.show(context);
}
// 同じ設定から、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)。指、ペン、マウスで、すべてのプラットフォームで動きます。

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

ハンドラー

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

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

@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:) と同じく、アクションのデフォルトのキーも指定します。

@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 へと進みます。

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 に置きます。

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

独自の記法

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

@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.open (primary+shift+d、taps:4+hold:3s)。

Spring (Java) との対応

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

関連項目