Anatomia de um bloco

Este documento explica as diferentes partes de um bloco.

Conexões

As conexões definem onde os blocos podem se conectar e a que tipo de bloco eles podem se conectar.

Há quatro tipos de conexões:

Tipo de conexão Imagem
Conexão de saída uma conexão de saída
Conexão de entrada uma conexão de entrada
Conexão anterior uma conexão anterior
Próxima conexão uma próxima conexão

As conexões de saída e de entrada podem se conectar, e as conexões seguintes e anteriores podem se conectar. É possível restringir ainda mais as conexões com verificações de conexão.

É possível personalizar as formas das conexões usando um renderizador personalizado.

Conexões de nível superior

Os blocos têm três conexões cujo uso é opcional.

Um bloco pode ter uma única conexão de saída, representada como um conector de quebra-cabeça macho na borda frontal de um bloco. Uma conexão de saída transmite o valor (expressão) de um bloco para outro. Um bloco com uma conexão de saída é chamado de bloco de valor.

Um bloco math_number.

Um bloco pode ter uma conexão anterior na parte de cima (representada por um entalhe) e uma próxima conexão na parte de baixo (representada por uma guia). Isso permite que os blocos sejam empilhados verticalmente, representando uma sequência de instruções. Um bloco sem uma conexão de saída é chamado de bloco de instrução e geralmente tem conexões anteriores e seguintes.

Um bloco variables_set.

Para mais informações, consulte Conexões de nível superior.

Campos

Os campos definem a maioria dos elementos da interface em um bloco. Isso inclui rótulos de string, menus suspensos, caixas de seleção, imagens e entradas para dados literales, como strings e números. Por exemplo, este bloco de loop usa campos de rótulo, um campo de menu suspenso e campos de números.

Um bloco com vários campos.

O Blockly oferece vários campos integrados, incluindo entradas de texto, seletores de cores e imagens. Também é possível criar seus próprios campos.

Para mais informações, consulte Campos.

Entradas

As entradas são contêineres para campos e conexões. Um bloco é criado renderizando as entradas em uma ou mais linhas, como tijolos.

Há quatro tipos diferentes de entradas, que podem conter campos (incluindo rótulos) e duas delas contêm uma única conexão. Também é possível criar entradas personalizadas, que oferecem suporte à renderização personalizada.

Tipo de entrada Tipo de conexão Imagem
Entrada fictícia Nenhum entrada fictícia
Entrada de fim de linha Nenhum entrada de fim de linha
Entrada de valor Conexão de entrada entrada de valor
Entrada de extrato Próxima conexão entrada de instrução

Vamos apresentar essas entradas em uma série de exemplos. Para informações sobre como definir as entradas, conexões e campos que compõem um bloco, consulte Estrutura de bloco em JSON e Estrutura de bloco em JavaScript.

Entradas fictícias

Uma entrada fictícia é apenas um contêiner para campos. Ela não tem uma conexão. Por exemplo, o bloco de números a seguir tem uma única entrada fictícia que contém um único campo de número.

Um bloco numérico com uma entrada fictícia e um campo numérico.

Como exemplo mais complexo, considere um bloco que soma dois números. Isso pode ser criado a partir de uma única entrada fictícia com três campos (número, rótulo e número):

Um bloco de adição criado a partir de uma entrada fictícia com três campos.

ou três entradas fictícias, cada uma com um único campo:

Um bloco de adição criado a partir de três entradas fictícias, cada uma com um único campo.

Entradas de fim de linha

O Blockly usa heurísticas para decidir se renderiza todas as entradas em uma única linha ou renderiza cada entrada em uma linha separada. Se você quiser ter certeza de que uma entrada inicia uma nova linha, use uma entrada de fim de linha como a anterior.

Assim como as entradas fictícias, as entradas de fim de linha podem conter campos, mas não têm uma conexão. Por exemplo, aqui está o bloco de adição criado a partir de uma entrada de fim de linha com dois campos e uma entrada fictícia com um campo. A entrada de fim de linha força a entrada fictícia a ser renderizada em uma nova linha.

Um bloco de adição dividido em duas linhas por uma entrada de fim de linha.

Entradas de valor

Os campos são limitados em relação ao que podem aceitar. Por exemplo, campos numéricos só aceitam números. Mas e se você quiser adicionar duas variáveis? Ou adicionar o resultado de uma chamada de procedimento ao resultado de um cálculo diferente? Para resolver esse problema, use conexões de entrada em vez de campos. Isso permite que os usuários usem blocos de valor como valores de entrada.

Uma entrada de valor contém zero ou mais campos e termina em uma conexão de entrada. O bloco a seguir substitui os campos numéricos no bloco de adição por conexões de entrada. Ele é criado com base em duas entradas de valor: a primeira não contém campos e a segunda contém um campo de rótulo. Ambos terminam em conexões de entrada.

Um bloco de adição com duas entradas de valor.

Entradas de extratos

O último tipo de entrada é uma entrada de instrução, que contém zero ou mais campos e termina com uma próxima conexão. A próxima conexão permite aninhar uma pilha de blocos de instruções dentro do bloco. Por exemplo, considere o seguinte bloco de repetição. A segunda linha desse bloco consiste em uma entrada de instrução com um único campo de rótulo e uma próxima conexão.

Um bloco de repetição com uma entrada de instrução para aninhar instruções repetidas.

As entradas de declaração são sempre renderizadas na própria linha. Você pode conferir isso no bloco "se-então-senão" abaixo, que tem uma entrada de valor na primeira linha e entradas de instrução nas duas próximas linhas.

Um bloco "se-então-senão" com entradas de instrução separadas para instruções "então" e "senão".

Entradas inline e externas

As entradas podem ser renderizadas inline ou externamente. Isso controla se os conectores para entradas de valor são renderizados dentro do bloco (inline) ou na borda externa (externo), bem como se as entradas são renderizadas na mesma linha ou em linhas diferentes.

O mesmo bloco renderizado uma vez com entradas inline e outra com entradas externas.

Ao criar um bloco personalizado, você pode especificar qual usar ou deixar que o Blockly tome a decisão. Para mais informações, consulte Entradas inline e externas.

Vamos jogar!

A melhor maneira de aprender sobre entradas, campos e conexões é criar blocos nas Ferramentas para desenvolvedores do Blockly e escolher diferentes configurações para o menu suspenso inputs (automatic, external, inline).

Ícones

Além de entradas, conexões e campos, os blocos podem ter um ou mais ícones. Eles têm vários usos, como exibir avisos, inserir comentários no nível do bloco ou mostrar a interface do modificador. Por exemplo, aqui está um bloco com um ícone de comentário e o editor associado a ele.

Um bloco com um ícone de comentário e um editor de comentários aberto.

Para mais informações, consulte Ícones.

Blocos e objetos JavaScript

Blocos, entradas, conexões, campos e ícones são objetos JavaScript.

Componente do Blockly Classe base Subclasses
Bloquear Block BlockSvg
Entrada Input DummyInput
EndRowInput
ValueInput
StatementInput
entrada personalizada
Conexão Connection RenderedConnection
Campo Field FieldTextInput
FieldNumber
FieldLabel
campo personalizado
etc.
Ícone Icon CommentIcon
MutatorIcon
WarningIcon
ícone personalizado

Os objetos em um bloco formam um objeto em forma de árvore. Entender como a representação gráfica de um bloco corresponde a essa árvore é útil ao escrever código para manipular blocos programaticamente. Por exemplo, um bloco controls_for:

Um bloco de loop com um campo variável, entradas de valor para "para", "de" e "por" e uma entrada de instrução para instruções repetidas.

corresponde à seguinte árvore de objetos JavaScript.

// <Object> means an instance of an Object.
{                                   // Block
  nextConnection: <Connection>,     // ConnectionType NEXT_STATEMENT
  outputConnection: null,
  previousConnection: <Connection>, // ConnectionType PREVIOUS_STATEMENT
  inputList: [                      // Array of Inputs in block
    {                               // ValueInput
      connection: <Connection>,     // ConnectionType INPUT_VALUE
      fieldRow: [                   // Array of fields in Input
        <FieldLabel>,               // 'count with'
        <FieldVariable>,            // i
        <FieldLabel>,               // 'from'
      ],
    },
    {                               // ValueInput
      connection: <Connection>,     // ConnectionType INPUT_VALUE
      fieldRow: [
        <FieldLabel>,               // 'to'
      ],
    },
    {                               // ValueInput
      connection: <Connection>,     // ConnectionType INPUT_VALUE
      fieldRow: [
        <FieldLabel>,               // 'by'
      ],
    },
    {                               // StatementInput
      connection: <Connection>,     // ConnectionType NEXT_STATEMENT
      fieldRow: [
        <FieldLabel>,               // 'do'
      ],
    },
  ]
}