Atajos de teclado

Introducción

Cuando necesitas escuchar una tecla de acceso rápido, normalmente usarías el evento onKeyDown. En twenty-front, sin embargo, podrías tener conflictos entre los mismos atajos de teclado utilizados en diferentes componentes, montados al mismo tiempo. Por ejemplo, si tienes una página que escucha la tecla Enter y un modal que escucha la tecla Enter, con un componente Select dentro de ese modal que también escucha la tecla Enter, podrías tener un conflicto cuando todos están montados al mismo tiempo.

El gancho `useScopedHotkeys`

Para manejar este problema, tenemos un gancho personalizado que hace posible escuchar atajos de teclado sin ningún conflicto. Lo colocas en un componente, y escuchará los atajos de teclado solo cuando el componente está montado Y cuando el ámbito del atajo de teclado especificado está activo.

¿Cómo escuchar atajos de teclado en la práctica?

Hay dos pasos involucrados en configurar la escucha de atajos de teclado:

Establece el ámbito del atajo de teclado que escuchará los atajos de teclado
Usa el gancho useScopedHotkeys para escuchar atajos de teclado

Configurar los ámbitos de atajos de teclado es necesario incluso en páginas simples, porque otros elementos de la interfaz de usuario como el menú lateral o el menú de comandos también podrían escuchar atajos de teclado.

Casos de uso para atajos de teclado

En general, tendrás dos casos de uso que requieren atajos de teclado:

En una página o un componente montado en una página
En un componente tipo modal que toma el enfoque debido a la acción del usuario

El segundo caso de uso puede ocurrir recursivamente: un desplegable en un modal, por ejemplo.

Escuchando atajos de teclado en una página

Ejemplo:

const PageListeningEnter = () => {
  const {
    setHotkeyScopeAndMemorizePreviousScope,
    goBackToPreviousHotkeyScope,
  } = usePreviousHotkeyScope();

  // 1. Set the hotkey scope in a useEffect
  useEffect(() => {
    setHotkeyScopeAndMemorizePreviousScope(
      ExampleHotkeyScopes.ExampleEnterPage,
    );

    // Revert to the previous hotkey scope when the component is unmounted
    return () => {
      goBackToPreviousHotkeyScope();
    };
  }, [goBackToPreviousHotkeyScope, setHotkeyScopeAndMemorizePreviousScope]);

  // 2. Use the useScopedHotkeys hook
  useScopedHotkeys(
    Key.Enter,
    () => {
      // Some logic executed on this page when the user presses Enter
      // ...
    },
    ExampleHotkeyScopes.ExampleEnterPage,
  );

  return <div>My page that listens for Enter</div>;
};

Para este ejemplo utilizaremos un componente modal que escucha la tecla Escape para indicar a su padre que lo cierre. Aquí la interacción del usuario está cambiando el ámbito.

const ExamplePageWithModal = () => {
  const [showModal, setShowModal] = useState(false);

  const {
    setHotkeyScopeAndMemorizePreviousScope,
    goBackToPreviousHotkeyScope,
  } = usePreviousHotkeyScope();

  const handleOpenModalClick = () => {
    // 1. Set the hotkey scope when user opens the modal
    setShowModal(true);
    setHotkeyScopeAndMemorizePreviousScope(
      ExampleHotkeyScopes.ExampleModal,
    );
  };

  const handleModalClose = () => {
    // 1. Revert to the previous hotkey scope when the modal is closed
    setShowModal(false);
    goBackToPreviousHotkeyScope();
  };

  return <div>
    <h1>My page with a modal</h1>
    <button onClick={handleOpenModalClick}>Open modal</button>
    {showModal && <MyModalComponent onClose={handleModalClose} />}
  </div>;
};

Luego, en el componente modal:

const MyDropdownComponent = ({ onClose }: { onClose: () => void }) => {
  // 2. Use the useScopedHotkeys hook to listen for Escape.
  // Note that escape is a common hotkey that could be used by many other components
  // So it's important to use a hotkey scope to avoid conflicts
  useScopedHotkeys(
    Key.Escape,
    () => {
      onClose()
    },
    ExampleHotkeyScopes.ExampleModal,
  );

  return <div>My modal component</div>;
};

Es importante usar este patrón cuando no está seguro de que sólo usar useEffect con montaje/desmontaje sea suficiente para evitar conflictos. Esos conflictos pueden ser difíciles de depurar y podría ocurrir con más frecuencia que con useEffects.

¿Qué es un ámbito de atajo de teclado?

Un ámbito de atajo de teclado es una cadena que representa un contexto en el que los atajos de teclado están activos. Por lo general, se codifica como un enum. Cuando cambias el ámbito del atajo de teclado, se habilitarán los atajos que están escuchando este ámbito y se deshabilitarán los atajos que escuchan otros ámbitos. Solo puedes establecer un ámbito a la vez. Como ejemplo, los ámbitos de atajos de teclado para cada página se definen en el enum PageHotkeyScope:

export enum PageHotkeyScope {
  Settings = 'settings',
  CreateWorkspace = 'create-workspace',
  SignInUp = 'sign-in-up',
  CreateProfile = 'create-profile',
  PlanRequired = 'plan-required',
  ShowPage = 'show-page',
  PersonShowPage = 'person-show-page',
  CompanyShowPage = 'company-show-page',
  CompaniesPage = 'companies-page',
  PeoplePage = 'people-page',
  OpportunitiesPage = 'opportunities-page',
  ProfilePage = 'profile-page',
  WorkspaceMemberPage = 'workspace-member-page',
  TaskPage = 'task-page',
}

Internamente, el ámbito seleccionado actualmente se almacena en un átomo de Jotai que se comparte en toda la aplicación:

export const currentHotkeyScopeState = createState<HotkeyScope>({
  key: 'currentHotkeyScopeState',
  defaultValue: INITIAL_HOTKEYS_SCOPE,
});

¡Pero este átomo nunca debe manejarse manualmente! Veremos cómo usarlo en la siguiente sección.

¿Cómo funciona internamente?

Hicimos un contenedor delgado sobre react-hotkeys-hook que lo hace más eficiente y evita renders innecesarios. También creamos un átomo de Jotai para manejar el estado del ámbito de atajos de teclado y hacerlo disponible en toda la aplicación.

Welcome

Core Concepts

Introducción

El gancho `useScopedHotkeys`

¿Cómo escuchar atajos de teclado en la práctica?

Casos de uso para atajos de teclado

Escuchando atajos de teclado en una página

¿Qué es un ámbito de atajo de teclado?

¿Cómo funciona internamente?

​Introducción

​El gancho useScopedHotkeys

​¿Cómo escuchar atajos de teclado en la práctica?

​Casos de uso para atajos de teclado

​Escuchando atajos de teclado en una página

​Escuchando atajos de teclado en un componente tipo modal

​¿Qué es un ámbito de atajo de teclado?

​¿Cómo funciona internamente?

Introducción

El gancho `useScopedHotkeys`

¿Cómo escuchar atajos de teclado en la práctica?

Casos de uso para atajos de teclado

Escuchando atajos de teclado en una página

Escuchando atajos de teclado en un componente tipo modal

¿Qué es un ámbito de atajo de teclado?

¿Cómo funciona internamente?