Anatomia de um bloco

Este documento explora as diferentes partes de um bloco.

Conexões

As conexões definem onde os blocos podem se conectar e a que tipo de blocos 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 entrada podem se conectar, assim como as conexões seguintes e anteriores. Você pode 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 de 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 como um entalhe) e uma próxima conexão na parte de baixo (representada como uma guia). Eles permitem 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 os rótulos de string, menus suspensos, caixas de seleção, imagens e entradas para dados literais como strings e números. Por exemplo, este bloco de loop usa campos de rótulo, um campo suspenso e campos numéricos.

Um bloco com vários campos.

O Blockly oferece vários campos integrados, incluindo entradas de texto, seletores de cores e imagens. Você também pode 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, todas com campos (incluindo rótulos), e duas delas contêm uma única conexão. Você também pode 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 instrução Próxima conexão entrada de instrução

Vamos apresentar essas entradas com 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 blocos em JSON e Estrutura de blocos 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úmero 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 um exemplo mais complexo, considere um bloco que soma dois números. Isso pode ser criado com base em uma única entrada fictícia com três campos (número, rótulo, número):

Um bloco de adição criado com 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 com três entradas fictícias, cada uma com um único campo.

Entradas de fim de linha

O Blockly usa heurísticas para decidir se vai renderizar todas as entradas em uma única linha ou cada entrada em uma linha separada. Se quiser garantir que uma entrada comece uma nova linha, use uma entrada de fim de linha como a entrada 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 com 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 têm limitações quanto ao que podem aceitar. Por exemplo, campos numéricos só aceitam números. Mas e se você quiser somar 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 de número 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 instrução

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 seu 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 ver isso no bloco if-then-else a seguir, que tem uma entrada de valor na primeira linha e entradas de instrução nas duas linhas seguintes.

Um bloco if-then-else com entradas de instrução separadas para instruções then e else.

Entradas em linha x 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 (externa), bem como se as entradas são renderizadas na mesma 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 o Blockly decidir por você. Para mais informações, consulte Entradas inline x externas.

Vamos lá!

A melhor maneira de aprender sobre entradas, campos e conexões é criar blocos nas Ferramentas para desenvolvedores do Blockly e escolher configurações diferentes no 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 mostrar avisos, inserir comentários no nível do bloco ou exibir a interface do mutator. Por exemplo, aqui está um bloco com um ícone de comentário e o editor associado.

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

Para mais informações, consulte Icons.

Blocos e objetos JavaScript

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

Componente do Blockly Classe de 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 de maneira programática. Por exemplo, um bloco controls_for:

Um bloco de loop com um campo de 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'
      ],
    },
  ]
}