Esta página foi traduzida pela API Cloud Translation.

Atalhos do teclado

O Blockly mantém um registro de atalhos de teclado que mapeiam teclas (ou combinações de teclas, como ctrl-C) para ações. O registro é pré-preenchido com vários atalhos, como ctrl-C e meta-C para copiar. É possível adicionar e excluir atalhos do registro.

Como os atalhos de teclado funcionam

O registro de atalhos contém objetos que modelam atalhos de teclado. Quando o usuário pressiona uma tecla (ou combinação de teclas), o Blockly:

Verifica o registro para saber se algum atalho se aplica à chave. Se mais de um atalho usar a tecla, eles serão testados na ordem inversa do registro. Ou seja, o atalho registrado mais recentemente é testado primeiro.
Chama a função preconditionFn do atalho, que determina se o atalho se aplica à situação atual. Por exemplo, o atalho de cópia se aplica a blocos, mas não ao espaço de trabalho. Se o atalho não se aplicar, o Blockly vai tentar o próximo atalho na lista, se houver.
Chama a função callback do atalho, que executa a ação do atalho. Por exemplo, o atalho de cópia faz uma cópia do objeto em foco no momento, como um bloco. Se essa função retornar true, o processamento será interrompido. Se ele retornar false, o Blockly vai tentar o próximo atalho na lista, se houver.

Escopo

Um objeto Scope identifica o componente do Blockly que está em foco. Os objetos de escopo são transmitidos para preconditionFn e callback, que os usam para decidir se um atalho se aplica a um componente específico e, em caso afirmativo, como aplicá-lo.

Para usar um objeto Scope, use a propriedade focusedNode. Este é um objeto que implementa IFocusableNode. Essa interface é implementada por todos os componentes do Blockly em que o usuário pode focar, incluindo espaços de trabalho, blocos, campos, comentários e seus próprios componentes personalizados. Para mais informações, consulte Sistema de foco.

Por exemplo, um preconditionFn pode usar focusedNode para garantir que um atalho se aplique apenas a blocos.

preconditionFn(workspace, scope) {
  return (scope.focusedNode instanceof Blockly.BlockSvg);
}

A interface KeyboardShortcut

Os objetos no registro de atalhos implementam a interface KeyboardShortcut. Ele contém as seguintes propriedades.

Nome (obrigatório)

Um nome exclusivo para o atalho. Ele não é mostrado aos usuários e não precisa ser legível para humanos. Não traduza.

const logFieldsShortcut = {
  name: 'logFields',
  // ...
};

preconditionFn (opcional)

O Blockly chama essa função para decidir se um atalho se aplica à situação atual. Se ele retornar true, o Blockly vai chamar callback. Se ele retornar false, o Blockly vai ignorar esse atalho. Exemplo:

const logFieldsShortcut = {
  // ...
  preconditionFn(workspace, scope) {
    // This shortcut only applies to blocks.
    return (scope.focusedNode instanceof Blockly.BlockSvg);
  },
  // ...
};

Um atalho pode omitir essa função se ela sempre se aplicar (incomum). Os atalhos não podem omitir essa função e realizar ações condicionais em callback. Isso evita que o Blockly faça coisas como criar menus de ajuda contextual que mostram atalhos aplicáveis.

callback (opcional)

Essa função executa a ação associada ao atalho. Ele é chamado somente se preconditionFn retornar true ou não existir. Os parâmetros são:

workspace: o WorkspaceSvg atual.
e: o Event que iniciou o atalho.
shortcut: o próprio KeyboardShortcut.
scope: o Scope a que o atalho se aplica.

Ele retorna true se for bem-sucedido e false se falhar.

Exemplo:

const logFieldsShortcut = {
  // ...
  callback(workspace, event, shortcut, scope) {
    // preconditionFn required focusedNode to be a BlockSvg.
    for (input of scope.focusedNode.inputList) {
      // Log the values of all named fields. (Label fields usually don't have names.)
      for (field of input.fieldRow) {
        if (field.name) {
          console.log(field.name + ': ' + field.getText());
        }
      }
    }
    return true;
  },
  // ...
};

Embora callback seja opcional, geralmente não há motivo para não implementá-lo.

keyCodes (opcional)

Uma matriz de chaves (ou combinações de chaves) que ativam esse atalho. Para identificar as teclas, use os keycodes em Blockly.utils.KeyCodes. Exemplo:

const logFieldsShortcut = {
  // ...
  keyCodes: [Blockly.utils.KeyCodes.L],
  // ...
};

Se você quiser mapear outras teclas para um atalho existente, por exemplo, adicionar teclas a um atalho padrão, chame Blockly.ShortcutRegistry.registry.addKeyMapping. Isso não é comum.

Combinações de teclas

Se o atalho de teclado for ativado por uma combinação de teclas, como pressionar Control e C simultaneamente, crie um código de tecla serializado chamando Blockly.ShortcutRegistry.registry.createSerializedKey:

const ctrlC = Blockly.ShortcutRegistry.registry.createSerializedKey(
  Blockly.utils.KeyCodes.C,       // Keycode of main key
  [Blockly.utils.KeyCodes.CTRL],  // Array of modifier keys
);

const copyShortcut = {
  // ...
  keyCodes: [ctrlC], // Use the serialized keycode
  // ...
};

Control e Meta

No Windows, muitos atalhos são ativados com a tecla Control. No Mac, esses atalhos de teclado usam a tecla Command, que é reconhecida como o código de tecla META. Para oferecer suporte aos dois sistemas operacionais, registre seus atalhos com os códigos de tecla CTRL e META.

const ctrlC = Blockly.ShortcutRegistry.registry.createSerializedKey(
  Blockly.utils.KeyCodes.C,
  [Blockly.utils.KeyCodes.CTRL],
);
const metaC = Blockly.ShortcutRegistry.registry.createSerializedKey(
  Blockly.utils.KeyCodes.C,
  [Blockly.utils.KeyCodes.META],
);

const copyShortcut = {
  // ...
  keyCodes: [ctrlC, metaC],
  // ...
};

Observação sobre a implementação

Os manipuladores de eventos de teclado do Blockly usam a propriedade keycode de KeyboardEvent mesmo que ela esteja descontinuada.

allowCollision (opcional)

Por padrão, só é possível registrar um atalho para uma determinada tecla ou combinação de teclas. Definir essa propriedade como true permite registrar uma tecla (ou combinação de teclas) mesmo que um atalho com a mesma tecla (ou combinação de teclas) já tenha sido registrado.

Essa propriedade só se aplica ao tentar registrar o atalho. Ele não impede que outros atalhos usem a mesma tecla (ou combinação de teclas). A possibilidade de registro depende do valor da propriedade allowCollision.

Independente de quantos atalhos estejam registrados para uma determinada tecla ou combinação de teclas, no máximo um será executado. Os atalhos são testados na ordem inversa do registro (do último registrado ao primeiro). Depois que um deles retorna true do callback, nenhum outro atalho é testado.

metadados (opcional)

É um objeto arbitrário que contém informações adicionais. Ele está disponível para callback pelo parâmetro shortcut.

Adicionar, excluir e modificar atalhos

Para adicionar um novo atalho de teclado, chame Blockly.ShortcutRegistry.registry.register:

Blockly.ShortcutRegistry.registry.register(logFieldsShortcut);

Essa função tem um segundo parâmetro (allowOverrides) que permite substituir um atalho existente com o mesmo nome do seu atalho. Isso é diferente de KeyboardShortcut.allowCollision, que permite adicionar um atalho com um nome diferente, mas usa a mesma tecla ou combinação de teclas de um atalho existente.

Para excluir um atalho do teclado, chame Blockly.ShortcutRegistry.registry.unregister e transmita o nome do atalho:

Blockly.ShortcutRegistry.registry.unregister('logFields');

Não é possível modificar um atalho de teclado no lugar. Em vez disso, é necessário excluir o atalho atual e adicionar um novo. Exemplo:

// Get the existing shortcut. getRegistry returns an object keyed by shortcut name.
const allShortcuts = Blockly.ShortcutRegistry.registry.getRegistry();
const modLogFieldsShortcut = allShortcuts[logFieldsShortcut.name];
// Apply the shortcut only to math blocks,
modLogFieldsShortcut.preconditionFn = function (workspace, scope) {
  return (scope.focusedNode instanceof Blockly.BlockSvg &&
          scope.focusedNode.type.startsWith('math_'));
}
// Delete the existing shortcut and add the modified shortcut.
Blockly.ShortcutRegistry.registry.unregister(logFieldsShortcut.name);
Blockly.ShortcutRegistry.registry.register(modLogFieldsShortcut);

Atalhos padrão

O registro de atalhos é pré-preenchido com vários atalhos. Você pode encontrar esses itens em https://github.com/google/blockly/blob/master/core/shortcut_items.ts. Os atalhos são definidos nas funções registerXxxx.

Atalhos de navegação pelo teclado

O plug-in de navegação pelo teclado contém atalhos que permitem aos usuários navegar pelo Blockly com o teclado, como usar as teclas de seta. A navegação por teclado é essencial para usuários que não podem usar um mouse, como pessoas com deficiências motoras ou visuais. Também é útil para usuários avançados que querem usar atalhos de teclado para aumentar a eficiência.

Atalhos do teclado Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.