Menus de contexto

Um menu de contexto contém uma lista de ações que podem ser realizadas em relação a algum elemento no espaço de trabalho. Um menu de contexto é mostrado ao clicar com o botão direito do mouse e tocar na tela e mantê-la pressionada.

Crie uma opção personalizada de menu de contexto se quiser adicionar um novo tipo de ação que o usuário pode realizar. Por exemplo, organizar todos os blocos no espaço de trabalho ou fazer o download de uma imagem dos blocos. Se você acha que a ação será usada com pouca frequência, o menu de contexto é um ótimo lugar para colocá-la. Caso contrário, talvez você queira criar uma maneira mais detectável de acessar a ação.

Observação: confira o codelab do menu de contexto para encontrar exemplos práticos de como adicionar opções do menu de contexto.

Implementar uma nova opção

Para implementar uma nova opção de menu de contexto, você precisa atender à interface RegistryItem.

ID

A propriedade id precisa ser uma string exclusiva que indica o que sua opção de menu de contexto faz.

const deleteOption = {
  id: 'deleteElement',
};

Escopo

A propriedade scopeType informa ao Blockly em qual contexto a opção de menu pode ser mostrada e quais informações transmitir para displayText, preconditionFn e callback. Os menus de contexto podem ter o escopo definido para blocos, comentários e espaços de trabalho.

const deleteOption = {
  scopeType: Blockly.ContextMenuRegistry.ScopeType.BLOCK,
};

Se você quiser que o menu de contexto funcione em vários escopos, duplique a opção do menu de contexto e redefina o parâmetro de escopo para cada escopo.

const otherDeleteOption = {...deleteOption};
otherDeleteOption.scopeType = Blockly.ContextMenuRegistry.ScopeType.COMMENT;

Texto de exibição

O displayText é o que precisa ser mostrado ao usuário como parte da opção do menu. O texto de exibição pode ser uma string ou HTML, ou uma função que retorna uma string ou HTML.

const deleteOption = {
  displayText: 'Delete block',
};

Se você quiser mostrar uma tradução do Blockly.Msg, vai precisar usar uma função. Se você tentar atribuir o valor diretamente, as mensagens poderão não ser carregadas e você receberá o valor undefined.

const deleteOption = {
  displayText: () => Blockly.Msg['MY_DELETE_OPTION_TEXT'],
};

Se você usar uma função, ela também receberá um valor Scope que fornece acesso ao elemento a que o menu de contexto está associado (por exemplo, o bloco ou o espaço de trabalho). Você pode usar isso para adicionar informações sobre o elemento ao texto de exibição.

const deleteOption = {
  displayText: (scope) => `Delete ${scope.block.type} block`,
}

Peso

A weight determina a ordem em que os itens do menu de contexto são mostrados. Valores mais positivos são exibidos mais abaixo na lista do que valores menos positivos. Imagine que as opções com pesos maiores são "mais pesadas", então elas caem para o mínimo.

const deleteOption = {
  weight: 10;
}

Os pesos para as opções integradas do menu de contexto vão em ordem crescente a partir de 1 e aumentando em 1.

Precondition

Além do scopeType, é possível usar preconditionFn para restringir quando e como uma opção de menu de contexto deve ser exibida.

Ela retornará uma das strings 'enabled', 'disabled' ou 'hidden'.

Valor	Descrição	Imagem
ativado	Mostra que a opção está ativa.
desativado	Mostra que a opção não está ativa.
oculto	Oculta a opção.

O preconditionFn também recebe um Scope, que pode ser usado para determinar o estado da sua opção.

const deleteOption = {
  preconditionFn: (scope) => {
    if (scope.block.isDeletable()) {
      return 'enabled';
    }
    return 'disabled';
  }
}

Chamada de retorno

A propriedade callback executa a ação do item do menu de contexto. Ele recebe um Scope e um PointerEvent. O PointerEvent é o evento original que acionou a abertura do menu de contexto, não aquele que selecionou uma opção. Você pode usar o evento para descobrir onde o clique aconteceu. Isso permite, por exemplo, criar um novo bloco no local do clique.

const deleteOption = {
  callback: (scope, e) => {
    scope.block.dispose();
  }
}

Inscrição

Para usar a opção do menu de contexto, é necessário registrá-la. Faça isso uma vez no carregamento da página. Isso pode acontecer antes ou depois da injeção do espaço de trabalho.

const deleteOption = { /* implementations from above */ };
Blockly.ContextMenuRegistry.registry.register(deleteOption);

Modificar opções por tipo de bloco

Os blocos têm outra maneira de modificar menus de contexto, ou seja, usar a substituição da propriedade customContextMenu. Esse método usa uma matriz de objetos ContextMenuOption (que são agrupados dos itens de menu registrados) e modifica essa matriz para determinar o conjunto final de opções mostradas.

Para mais informações, consulte Definir blocos, menus de contexto personalizados.

Os espaços de trabalho também têm um método configureContextMenu que funciona de maneira semelhante.

Remover uma opção

Para remover uma opção do menu de contexto, cancele o registro dela pelo ID.

Blockly.ContextMenuRegistry.registry.unregister('someID');

Os códigos das opções padrão estão em contextmenu_items.ts.

Modificar uma opção

Você pode modificar uma opção existente obtendo o item do registro e, em seguida, modificando-o no local.

const option = Blockly.ContextMenuRegistry.registry.getItem('someID');
option?.displayText = 'some other display text';