Menús contextuales

Un menú contextual contiene una lista de acciones que puedes realizar en relación con algún elemento del lugar de trabajo. Se muestra un menú contextual cuando se hace clic con el botón derecho y se mantiene presionado.

Es posible que desees crear una opción de menú contextual personalizado si deseas agregar un nuevo tipo de acción que el usuario pueda realizar. Por ejemplo, para organizar todos los bloques en el espacio de trabajo o descargar una imagen de los bloques. Si crees que la acción se usará con poca frecuencia, el menú contextual es un excelente lugar para ponerla. De lo contrario, es posible que desees crear una forma más detectable para acceder a la acción.

Nota: Consulta el codelab del menú contextual para ver ejemplos útiles de cómo agregar opciones de menú contextual.

Implementa una opción nueva

Para implementar una opción nueva de menú contextual, debes entregar la interfaz RegistryItem.

ID

La propiedad id debe ser una cadena única que indique lo que hace tu opción de menú contextual.

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

Alcance

La propiedad scopeType le indica a Blockly en qué contexto se podría mostrar la opción de menú y qué información pasar a sus displayText, preconditionFn y callback. Los menús contextuales se pueden limitar a bloques, comentarios del lugar de trabajo y lugares de trabajo.

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

Si quieres que tu menú contextual funcione en varios alcances, debes duplicar la opción de menú contextual y volver a definir el parámetro de alcance para cada alcance.

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

Texto visible

displayText es lo que se debe mostrar al usuario como parte de la opción del menú. El texto visible puede ser una cadena, HTML o una función que muestra una cadena o HTML.

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

Si deseas mostrar una traducción del Blockly.Msg, debes usar una función. Si intentas asignar el valor de forma directa, es posible que los mensajes no se cargan y que recibas un valor de undefined en su lugar.

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

Si usas una función, también se le pasa un valor Scope, que te brinda acceso al elemento con el que está asociado el menú contextual (p.ej., el bloque o el lugar de trabajo). Puedes usar esto para agregar información sobre el elemento a tu texto visible.

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

Peso

El weight determina el orden en el que se muestran los elementos del menú contextual. Los valores más positivos se muestran en los niveles inferiores de la lista que los menos positivos. (Puedes imaginar que las opciones con pesos más altos son "más pesadas", por lo que se hunde hasta el fondo).

const deleteOption = {
  weight: 10;
}

Los pesos de las opciones del menú contextual integradas van en orden creciente a partir de 1 y, luego, en 1.

Condición previa

Además del scopeType, puedes usar el preconditionFn para restringir cuándo y cómo se debe mostrar una opción de menú contextual.

Debe mostrar uno de un conjunto de cadenas: 'enabled', 'disabled' o 'hidden'.

Valor	Descripción	De imagen
habilitado	Muestra que la opción está activa.
inhabilitado	Muestra que la opción no está activa.
de pesos	Oculta la opción.

A preconditionFn también se le pasa un Scope que puedes usar para determinar el estado de tu opción.

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

Devolución de llamada

La propiedad callback realiza la acción del elemento de menú contextual. Le pasa un Scope y un PointerEvent. El PointerEvent es el evento original que activó la apertura del menú contextual, no el que seleccionó una opción. Puedes usar el evento para averiguar dónde se produjo el clic. Esto te permite, por ejemplo, crear un bloque nuevo en la ubicación del clic.

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

Registro

Para utilizar la opción de menú contextual, debes registrarla. Debes hacer esto una vez cuando se carga la página. Puede ocurrir antes o después de inyectar el espacio de trabajo.

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

Modificar opciones por tipo de bloque

Los bloques tienen una forma adicional de modificar los menús contextuales, que consiste en reemplazar su propiedad customContextMenu. Este método toma un array de objetos ContextMenuOption (que se recopilan de los elementos de menú registrados) y, luego, modifica ese array en su lugar para determinar el conjunto final de opciones que se muestran.

Para obtener más información, consulta Define bloques, menús contextuales personalizados.

Los lugares de trabajo también tienen un método configureContextMenu que funciona de manera similar.

Cómo quitar una opción

Para quitar una opción del menú contextual, puedes cancelar el registro por ID.

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

Los ID para las opciones predeterminadas se encuentran en contextmenu_items.ts.

Cómo modificar una opción

Para modificar una opción existente, obtén el elemento del registro y, luego, modifícalo en su ubicación.

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