Gestire scorciatoie e azioni da tastiera in Flutter con Shortcuts e Actions

Prima di scrivere codice è importante capire i tre pezzi del puzzle:

• Intent: una classe che rappresenta cosa vuoi fare (es. IncrementIntent). Non contiene logica, è solo un'etichetta.
• Shortcuts: un widget che associa una combinazione di tasti (LogicalKeySet o SingleActivator) a un Intent.
• Actions: un widget che associa un Intent a un Action, ovvero la logica che viene realmente eseguita.

Questa separazione permette di riutilizzare gli stessi Intent con scorciatoie diverse su piattaforme diverse (ad esempio Cmd su macOS e Ctrl altrove).

Definiamo per prima cosa i nostri Intent.

import 'package:flutter/material.dart';

// Ogni Intent rappresenta un'intenzione astratta.
class IncrementIntent extends Intent {
  const IncrementIntent();
}

class DecrementIntent extends Intent {
  const DecrementIntent();
}

class ResetIntent extends Intent {
  const ResetIntent();
}

Costruiamo un semplice widget StatefulWidget che mantiene un contatore. In seguito collegheremo le scorciatoie ai metodi che modificano questo stato.

Per ora l'interfaccia mostra solo il valore corrente e alcuni pulsanti tradizionali, così potrai confrontare i due approcci.

class ShortcutDemo extends StatefulWidget {
  const ShortcutDemo({super.key});

  @override
  State<ShortcutDemo> createState() => _ShortcutDemoState();
}

class _ShortcutDemoState extends State<ShortcutDemo> {
  int _counter = 0;

  void _increment() => setState(() => _counter++);
  void _decrement() => setState(() => _counter--);
  void _reset() => setState(() => _counter = 0);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Shortcuts & Actions')),
      body: Center(
        child: Text(
          'Contatore: $_counter',
          style: Theme.of(context).textTheme.headlineMedium,
        ),
      ),
    );
  }
}

Avvolgiamo il contenuto con il widget Shortcuts, passando una mappa che associa i tasti agli Intent.

Usiamo SingleActivator, il modo moderno e consigliato per descrivere una combinazione: accetta il tasto principale più i modificatori (control, shift, meta, alt).

Nota: il widget Shortcuts deve avere un discendente con il focus per ricevere gli eventi. Useremo Focus con autofocus: true nel prossimo passo, oppure puoi usare FocusableActionDetector per semplificare.

Shortcuts(
  shortcuts: <ShortcutActivator, Intent>{
    // freccia su / giù
    const SingleActivator(LogicalKeyboardKey.arrowUp): const IncrementIntent(),
    const SingleActivator(LogicalKeyboardKey.arrowDown): const DecrementIntent(),
    // Ctrl + R per il reset
    const SingleActivator(LogicalKeyboardKey.keyR, control: true):
        const ResetIntent(),
  },
  child: /* Actions + Focus verranno aggiunti dopo */ const SizedBox(),
)

Ora avvolgiamo il tutto con Actions, che associa ogni tipo di Intent a un Action.

Usiamo CallbackAction<T>, la forma più semplice di Action: il suo onInvoke viene chiamato quando l'Intent corrispondente viene invocato.

È fondamentale che il tipo generico dell'Action corrisponda al tipo dell'Intent nella mappa, altrimenti l'azione non verrà trovata.

Actions(
  actions: <Type, Action<Intent>>{
    IncrementIntent: CallbackAction<IncrementIntent>(
      onInvoke: (intent) {
        _increment();
        return null;
      },
    ),
    DecrementIntent: CallbackAction<DecrementIntent>(
      onInvoke: (intent) {
        _decrement();
        return null;
      },
    ),
    ResetIntent: CallbackAction<ResetIntent>(
      onInvoke: (intent) {
        _reset();
        return null;
      },
    ),
  },
  child: /* Focus */ const SizedBox(),
)

Il sistema di scorciatoie funziona solo se un widget nell'albero ha il focus. Aggiungiamo un widget Focus con autofocus: true come figlio di Actions.

Mettiamo insieme tutti i pezzi nel metodo build. L'ordine dall'esterno all'interno è: Shortcuts → Actions → Focus → UI.

Ricorda di importare package:flutter/services.dart per accedere a LogicalKeyboardKey.

import 'package:flutter/services.dart';

@override
Widget build(BuildContext context) {
  return Shortcuts(
    shortcuts: <ShortcutActivator, Intent>{
      const SingleActivator(LogicalKeyboardKey.arrowUp): const IncrementIntent(),
      const SingleActivator(LogicalKeyboardKey.arrowDown): const DecrementIntent(),
      const SingleActivator(LogicalKeyboardKey.keyR, control: true):
          const ResetIntent(),
    },
    child: Actions(
      actions: <Type, Action<Intent>>{
        IncrementIntent: CallbackAction<IncrementIntent>(
            onInvoke: (i) { _increment(); return null; }),
        DecrementIntent: CallbackAction<DecrementIntent>(
            onInvoke: (i) { _decrement(); return null; }),
        ResetIntent: CallbackAction<ResetIntent>(
            onInvoke: (i) { _reset(); return null; }),
      },
      child: Focus(
        autofocus: true,
        child: Scaffold(
          appBar: AppBar(title: const Text('Shortcuts & Actions')),
          body: Center(
            child: Column(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                Text('Contatore: $_counter',
                    style: Theme.of(context).textTheme.headlineMedium),
                const SizedBox(height: 12),
                const Text('↑ incrementa  ·  ↓ decrementa  ·  Ctrl+R reset'),
              ],
            ),
          ),
        ),
      ),
    ),
  );
}

Su macOS gli utenti usano il tasto Cmd (meta) al posto di Ctrl. Per offrire un'esperienza nativa possiamo aggiungere entrambe le scorciatoie oppure rilevare la piattaforma.

Un approccio pulito è definire la mappa in modo condizionale usando defaultTargetPlatform. Ricorda di importare package:flutter/foundation.dart.

È una buona pratica offrire scorciatoie coerenti con le convenzioni del sistema operativo su cui gira l'app.

import 'package:flutter/foundation.dart';

Map<ShortcutActivator, Intent> _buildShortcuts() {
  final bool isApple = defaultTargetPlatform == TargetPlatform.macOS;
  return <ShortcutActivator, Intent>{
    const SingleActivator(LogicalKeyboardKey.arrowUp): const IncrementIntent(),
    const SingleActivator(LogicalKeyboardKey.arrowDown): const DecrementIntent(),
    // Cmd+R su macOS, Ctrl+R altrove
    SingleActivator(
      LogicalKeyboardKey.keyR,
      control: !isApple,
      meta: isApple,
    ): const ResetIntent(),
  };
}

A volte vuoi eseguire un'azione dal codice (ad esempio da un pulsante) riutilizzando la stessa logica delle scorciatoie. Puoi farlo con Actions.invoke o Actions.maybeInvoke, che cercano l'Action associata all'Intent nel contesto.

Questo è utile per garantire che pulsanti e scorciatoie condividano esattamente lo stesso comportamento, evitando duplicazione di logica.

Collega ad esempio un FloatingActionButton all'IncrementIntent.

FloatingActionButton(
  onPressed: () {
    // Invoca l'Action registrata per IncrementIntent nel contesto corrente.
    Actions.maybeInvoke<IncrementIntent>(
      context,
      const IncrementIntent(),
    );
  },
  child: const Icon(Icons.add),
)

// In alternativa, per bottoni con il focus puoi usare:
// Actions.invoke(context, const IncrementIntent());