キーボードショートカットとタップ
アクションのキーは設定で、そのハンドラーは 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)。指、ペン、マウスで、すべてのプラットフォームで動きます。
- リッスンするだけです。すべてのタッチは引き続きアプリに届きます。
- 一回のタップは最大 300 ms で、二つのタップの間隔は最大 400 ms です。
- 18 ポイントより多く動いた指はスクロールとみなされ、パターンは最初からになります。
キーボードのないスマートフォンでの隠れたアクション、例えば デバッグパネル (デフォルトは 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 のメソッド、複数のものの間の順序です。