Tipos de campo
Blockstudio oferece vários tipos de campo para criar interfaces de blocos.
Os projetos também podem registrar seus próprios tipos de campo com namespace usando blockstudio/field_types. Use essa opção quando precisar de um novo controle de editor ou de um formato de valor estruturado. Use campos custom/{name} quando precisar apenas reutilizar um grupo de campos existentes.
Receitas práticas: grupos condicionais, seleções inteligentes, repetidores e armazenamento consultável.
Propriedades gerais
A tabela abaixo lista propriedades compartilhadas e opções de valores comuns. default e
fallback são compatíveis quando indicadas na tabela Propriedades de cada tipo de campo.
| Propriedade | Tipo | Descrição |
|---|---|---|
id |
string | Identificador exclusivo do atributo |
type |
string | O tipo de campo |
label |
string | Rótulo exibido no editor |
description |
string | Texto de descrição exibido abaixo do campo |
default |
mixed | Valor padrão do campo |
fallback |
mixed | Valor alternativo quando o campo está vazio |
help |
string | Texto de ajuda exibido como dica de ferramenta ao lado do rótulo |
hidden |
boolean | Oculta o campo de UI |
switch |
boolean | Exibe um botão de alternância que pode desativar o campo. O padrão é false. |
translate |
boolean | Defina como false para omitir o campo da configuração WPML |
conditions |
array | Regras de lógica condicional |
Campos de arquivos com "returnFormat": "id" preservam referências de string importadas,
incluindo valores individuais dentro de repetidores. Nomes não resolvidos exibem cartões alternativos
sem miniaturas; Blockstudio não os resolve para IDs de anexos. Consulte
referências portáteis de mídia para obter detalhes.
Consulte Carregamento de ícones para solicitações do seletor, novas tentativas e subconjuntos de ícones.
attributes
Renderiza campos de entrada para atributos de dados.
{
"type": "attributes"
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
array |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
array |
Valor alternativo exibido quando o valor do campo está vazio. |
link |
boolean |
Ativa a seleção de links em uma lista suspensa. |
media |
boolean |
Ativa a seleção de mídia em uma lista suspensa. |
bloco
Faz referência a outro bloco Blockstudio, expandindo seus campos em linha. Nos modelos, o valor retorna a saída renderizada do bloco.
{
"type": "block"
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
block |
string |
Nome do bloco a ser referenciado (e.g., "mytheme/card"). |
returnFormat |
string |
Como o valor deve ser retornado nos modelos. |
caixa de seleção
Renderiza um conjunto de caixas de seleção.
{
"type": "checkbox",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
]
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
array | string | number |
Valor padrão a ser aplicado ao adicionar o bloco pela primeira vez. |
fallback |
array | string | number |
Valor alternativo que será exibido quando o valor do campo estiver vazio. |
options |
array |
Opções disponíveis para seleção. |
returnFormat |
string |
Especifica o formato do valor retornado. |
populate |
object |
|
toggle |
boolean | string |
Adiciona uma caixa de seleção acima das opções para selecionar ou limpar todas. Uma string é usada como rótulo; true usa o rótulo padrão. |
classes
Renderiza um campo para selecionar classes CSS.
{
"type": "classes"
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
string |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
string |
Valor alternativo exibido quando o valor do campo está vazio. |
tailwind |
boolean |
Define se as classes Tailwind devem ser ativadas para este campo de entrada. |
código
Renderiza um editor de código.
{
"type": "code"
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
string |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
string |
Valor alternativo exibido quando o valor do campo está vazio. |
autoCompletion |
boolean |
Se o preenchimento automático deve ser ativado. |
foldGutter |
boolean |
Se a margem de recolhimento deve ser exibida. |
height |
string |
Altura do editor. |
language |
string |
Linguagem usada para realce de sintaxe. |
lineNumbers |
boolean |
Se os números das linhas devem ser exibidos. |
maxHeight |
string |
Altura máxima do editor. |
minHeight |
string |
Altura mínima do editor. |
popout |
boolean |
Se deve ser exibido um botão para abrir o editor em uma janela pop-up. |
asset |
boolean |
Renderiza CSS, SCSS ou JavaScript do campo como um recurso do bloco, para que o modelo não precise imprimir a tag de estilo ou de script. |
cor
Renderiza uma paleta de cores e um seletor de cores.
{
"type": "color",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
]
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
string |
Valor da opção selecionada ao adicionar o bloco pela primeira vez. |
fallback |
string |
Valor da opção exibida quando o valor do campo está vazio. |
options |
array |
|
populate |
object |
|
clearable |
boolean |
Se a paleta deve ter um botão para limpar a seleção. |
disableCustomColors |
boolean |
Se cores personalizadas devem ser permitidas. |
data
Renderiza um seletor de datas.
{
"type": "date"
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
string |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
string |
Valor alternativo exibido quando o valor do campo está vazio. |
startOfWeek |
number |
O dia em que a semana deve começar. 0 para domingo, 1 para segunda-feira etc. |
data e hora
Renderiza um seletor de data e hora.
{
"type": "datetime"
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
string |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
string |
Valor alternativo exibido quando o valor do campo está vazio. |
is12Hour |
boolean |
Define se usamos o formato de 12 horas. Nesse formato, é exibido um seletor AM/PM e o formato de data é MM-DD-YYYY (em vez do formato padrão DD-MM-YYYY). |
arquivos
Renderiza um botão para a biblioteca de mídia. Os itens selecionados podem ser reordenados em linha.
{
"type": "files",
"min": 0,
"max": 100,
"multiple": false
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
array | object | number |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
array | object | number |
Valor alternativo exibido quando o valor do campo está vazio. |
addToGallery |
boolean |
Se true, a janela modal de mídia da galeria abre diretamente na biblioteca de mídia, onde o usuário pode adicionar imagens. Se false, a janela modal de mídia da galeria abre no modo de edição, onde o usuário pode editar imagens existentes reordenando-as, removendo-as ou alterando seus atributos. Aplica-se somente se gallery === true. |
allowedTypes |
array | string |
Array com os tipos de mídia que podem ser enviados ou selecionados na biblioteca de mídia. Cada tipo é uma string que pode conter o tipo MIME geral e.g: ‘image’, ‘audio’, ‘text’ ou o tipo MIME completo e.g: ‘audio/mpeg’, ‘image/gif’. Se allowedTypes não estiver definido, todos os tipos MIME serão permitidos. |
gallery |
boolean |
Se true, o componente inicializa todos os estados necessários para representar uma galeria. Por padrão, a janela modal de mídia abre no quadro de edição da galeria, mas isso pode ser alterado usando a flag addToGallery. |
max |
number |
Quantidade máxima de arquivos que podem ser adicionados. |
min |
number |
Quantidade mínima de arquivos que podem ser adicionados. |
multiple |
boolean |
Define se várias seleções são permitidas. |
size |
boolean |
Adiciona ao campo uma lista suspensa de tamanhos de mídia. |
textMediaButton |
string |
Texto do botão de mídia. |
title |
string |
Título exibido na janela modal de mídia. |
returnFormat |
string |
Especifica o formato do valor retornado. |
returnSize |
string |
O tamanho de mídia retornado ao usar o formato de retorno URL. |
gradiente
Renderiza uma paleta de gradientes e um seletor de gradientes.
{
"type": "gradient",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
]
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
string |
Valor da opção selecionada ao adicionar o bloco pela primeira vez. |
fallback |
string |
Valor da opção exibida quando o valor do campo está vazio. |
options |
array |
|
populate |
object |
|
clearable |
boolean |
Se a paleta deve ter um botão para limpar a seleção. |
disableCustomGradients |
boolean |
Se cores personalizadas devem ser permitidas. |
grupo
Renderiza vários campos em um contêiner (opcionalmente) recolhível.
{
"type": "group"
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
title |
string |
Texto do título. Ele é exibido mesmo quando o componente está fechado. |
opened |
boolean |
Quando definido como true, o componente permanece aberto independentemente da propriedade initialOpen e do |
initialOpen |
boolean |
Define se o painel começa aberto. |
scrollAfterOpen |
boolean |
Rola o conteúdo até que fique visível. |
class |
string |
Classe CSS personalizada aplicada ao grupo. |
style |
object |
Estilos CSS personalizados aplicados ao grupo. |
attributes |
array |
Aceita todos os outros tipos de campo, exceto outro tabs. |
html-tag
Renderiza um seletor de tags HTML. Útil para escolher níveis de cabeçalho ou elementos semânticos.
{
"type": "html-tag"
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
string |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
string |
Valor alternativo exibido quando o valor do campo está vazio. |
tags |
string | array |
Quais tags incluir. Use uma string predefinida ou um array de nomes de tags. |
exclude |
array |
Tags a excluir da predefinição. Aplica-se somente ao usar uma string predefinida para tags. |
ícone
Renderiza um ícone SVG de um conjunto de ícones.
{
"type": "icon"
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
object |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
object |
Valor alternativo exibido quando o valor do campo está vazio. |
sets |
array | string |
Qual conjunto de ícones incluir. Deixe vazio para incluir todos. |
subSets |
array | string |
Qual subconjunto de ícones incluir. Deixe vazio para incluir todos. |
returnFormat |
string |
O formato em que o ícone deve ser retornado. |
link
Renderiza um controle de link para escolher links internos ou externos.
{
"type": "link"
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
object |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
object |
Valor alternativo exibido quando o valor do campo está vazio. |
hasRichPreviews |
boolean |
Define se prévias avançadas devem ser exibidas ao adicionar um URL. |
noDirectEntry |
boolean |
Define se é possível transformar diretamente uma consulta de pesquisa semelhante a URL em um link. |
noURLSuggestion |
boolean |
Define se deve ser adicionada uma sugestão alternativa que trate a consulta de pesquisa como um URL. |
opensInNewTab |
boolean |
Adiciona um controle de alternância à janela modal de link. |
showSuggestions |
boolean |
Define se sugestões devem ser exibidas ao digitar o URL. |
textButton |
string |
Texto personalizado a ser exibido dentro do botão de link. |
withCreateSuggestion |
boolean |
Define se pesquisas de links sem correspondência podem criar uma sugestão de nova página de rascunho. |
mensagem
Renderiza uma mensagem com conteúdo personalizado.
{
"type": "message"
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
string |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
string |
Valor alternativo exibido quando o valor do campo está vazio. |
value |
string |
Mensagem a exibir. Os dados do bloco e dos atributos estão disponíveis na sintaxe entre colchetes, e.g.: {block.title} ou {attributes.text} |
número
Renderiza um campo de entrada numérica.
{
"type": "number",
"min": 0,
"max": 100,
"step": 1
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
number |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
number |
Valor alternativo exibido quando o valor do campo está vazio. |
dragDirection |
string |
Determina o eixo de arraste para aumentar ou diminuir o valor. |
dragThreshold |
number |
Se isDragEnabled for true, controla quantos px precisam ser arrastados antes que o valor mude. |
hideHTMLArrows |
boolean |
Se true, as setas padrão HTML do campo de entrada ficam ocultas. |
isShiftStepEnabled |
boolean |
Se true, ativa o gesto de arrastar com o mouse para aumentar ou diminuir o valor numérico. Manter SHIFT pressionado durante o arraste aumenta o valor em shiftStep. |
max |
number |
Comprimento máximo do valor. |
min |
number |
Comprimento mínimo do valor. |
required |
boolean |
Se true, exige um número válido dentro do intervalo min/max do controle. Se false, permite uma string vazia como valor válido. |
shiftStep |
number |
Quantidade a adicionar quando a tecla SHIFT estiver pressionada. Esse valor de shift é um multiplicador do valor de step. Por exemplo, se o valor de step for 5 e shiftStep for 10, cada salto aumentará ou diminuirá o valor em 50. |
step |
number |
Quantidade pela qual o valor muda ao aumentá-lo ou diminuí-lo. Também é usada na validação: para ser válido, o valor deve ser múltiplo de step (com deslocamento de min, se especificado). Aceita a string especial any, que elimina a restrição de validação e faz com que as ações de incremento ou decremento alterem o valor em 1. |
opção
Renderiza um conjunto de opções de seleção única.
{
"type": "radio",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
]
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
string | number |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
string | number |
Valor alternativo exibido quando o valor do campo está vazio. |
options |
array |
Opções disponíveis para seleção. |
returnFormat |
string |
Especifica o formato do valor de retorno. |
populate |
object |
|
display |
string |
Defina como buttonGroup para exibir as opções em um grupo de botões em vez de entradas de opção. |
allowNull |
boolean |
Permite que o usuário limpe o valor clicando novamente na opção selecionada. |
intervalo
Renderiza um campo deslizante para definir um valor numérico entre dois pontos.
{
"type": "range",
"min": 0,
"max": 100,
"step": 1
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
number |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
number |
Valor alternativo exibido quando o valor do campo está vazio. |
allowReset |
boolean |
Se esta propriedade for true, será renderizado um botão para redefinir o controle deslizante. |
initialPosition |
number |
A posição inicial do controle deslizante, usada quando nenhum valor é informado. initialPosition será limitado aos valores min e max fornecidos como propriedades. |
isShiftStepEnabled |
boolean |
Se true, ativa o gesto de arrastar com o mouse para aumentar ou diminuir o valor numérico. Manter SHIFT pressionado durante o arraste aumenta o valor em shiftStep. |
marks |
array |
Renderiza uma representação visual das marcas de step. É possível fornecer indicadores de marca personalizados em um Array. |
max |
number |
Comprimento máximo do valor. |
min |
number |
Comprimento mínimo do valor. |
railColor |
string |
String de cor CSS para personalizar o plano de fundo do trilho. |
resetFallbackValue |
number |
Valor para o qual retornar se o botão Reset for clicado (ativado por allowReset). |
separatorType |
string |
Define se a linha separadora acima ou abaixo da linha do controle deve ser desativada ou ocupar toda a largura. Por padrão, ela fica abaixo, sem sublinhar o ícone do controle. |
shiftStep |
number |
Quantidade a adicionar quando a tecla SHIFT estiver pressionada. Esse valor de shift é um multiplicador do valor de step. Por exemplo, se o valor de step for 5 e shiftStep for 10, cada salto aumentará ou diminuirá o valor em 50. |
showTooltip |
boolean |
Força a exibição ou ocultação da Tooltip UI. Esse valor é substituído por false quando step recebe a string especial any. |
step |
number |
Quantidade pela qual o valor muda ao aumentá-lo ou diminuí-lo. Também é usada na validação: para ser válido, o valor deve ser múltiplo de step (com deslocamento de min, se especificado). Aceita a string especial any, que elimina a restrição de validação e faz com que as ações de incremento ou decremento alterem o valor em 1. |
trackColor |
string |
String de cor CSS para personalizar o plano de fundo da faixa. |
withInputField |
boolean |
Determina se o campo numérico será renderizado ao lado do RangeControl. Esse valor é substituído por false quando step recebe a string especial any. |
seleção
Renderiza um campo de seleção com suporte a seleções únicas ou múltiplas.
{
"type": "select",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
],
"multiple": false
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
array | string | number |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
array | string | number |
Valor alternativo exibido quando o valor do campo está vazio. |
multiple |
boolean |
Se true, várias opções podem ser selecionadas. "stylisedUi" será ativada automaticamente. |
options |
array |
Opções disponíveis para seleção. |
returnFormat |
string |
Especifica o formato do valor retornado. |
populate |
object |
|
stylisedUi |
boolean |
Renderiza uma versão estilizada de um campo de seleção, com possibilidade de pesquisar os itens. |
allowNull |
boolean | string |
Permite selecionar uma opção vazia. Se true, o rótulo ficará vazio; caso contrário, a opção exibirá a string especificada. |
allowReset |
boolean |
Se esta propriedade for true, será renderizado um botão para redefinir a seleção. |
guias
Renderiza uma interface com guias para agrupar campos.
{
"type": "tabs"
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
tabs |
array |
As guias a exibir. |
texto
Renderiza um campo de entrada de texto de uma linha.
{
"type": "text",
"min": 0,
"max": 100
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
string |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
string |
Valor alternativo exibido quando o valor do campo está vazio. |
max |
number |
Comprimento máximo do valor. |
min |
number |
Comprimento mínimo do valor. |
área de texto
Renderiza um campo de entrada de área de texto.
{
"type": "textarea",
"min": 0,
"max": 100,
"rows": 4
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
string |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
string |
Valor alternativo exibido quando o valor do campo está vazio. |
max |
number |
Comprimento máximo do valor. |
min |
number |
Comprimento mínimo do valor. |
rows |
number |
Número de linhas que a área de texto deve conter. |
alternância
Renderiza um controle de alternância true/false.
{
"type": "toggle"
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
boolean |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
boolean |
Valor alternativo exibido quando o valor do campo está vazio. |
repetidor
Renderiza um conjunto de campos que podem ser repetidos.
{
"type": "repeater",
"min": 0,
"max": 100
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
array |
Linhas com as quais um novo bloco começa. Cada linha é um objeto com valores de campos. Tem precedência sobre as linhas criadas por min. |
min |
number |
Número mínimo de linhas. |
max |
number |
Número máximo de linhas. |
minimized |
boolean |
Recolhe as linhas existentes quando o editor é aberto. As linhas adicionadas no editor começam expandidas. |
textButton |
string |
Texto do botão de adicionar. |
textMinimized |
string | object |
Texto exibido quando as linhas são minimizadas. |
textRemove |
string | boolean |
Pergunta de confirmação exibida no editor ao remover uma linha do repetidor. Uma string não vazia altera a pergunta; false remove a linha imediatamente, sem diálogo. Se omitida, definida como true ou como uma string vazia, usa a pergunta padrão. |
attributes |
array |
Aceita todos os outros tipos de campo, exceto outro campo de abas. |
richtext
Campo de atributo para campos RichText.
{
"type": "richtext"
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
string |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
string |
Valor alternativo exibido quando o valor do campo está vazio. |
unit
Renderiza um campo numérico com uma lista suspensa de unidades.
{
"type": "unit"
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
string |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
string |
Valor alternativo exibido quando o valor do campo está vazio. |
disableUnits |
boolean |
Se verdadeiro, o campo de seleção de unidade fica oculto. |
isPressEnterToChange |
boolean |
Se verdadeiro, é necessário pressionar ENTER para acionar um onChange. Se ativado, uma alteração também é acionada ao sair do campo com Tab. |
isResetValueOnUnitChange |
boolean |
Se verdadeiro e a unidade selecionada tiver um valor padrão, esse valor será definido ao trocar de unidade. |
isUnitSelectTabbable |
boolean |
Determina se é possível navegar até o campo de seleção de unidade com Tab. |
units |
array |
wysiwyg
Renderiza um editor WYSIWYG.
{
"type": "wysiwyg"
}
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
default |
string |
Valor padrão aplicado ao adicionar o bloco pela primeira vez. |
fallback |
string |
Valor alternativo exibido quando o valor do campo está vazio. |
toolbar |
object |
Configuração da barra de ferramentas do editor. |
mode |
string |
code abre o campo na visualização de código. both adiciona um botão para alternar entre a visualização visual e a de código. |
Carregamento de ícones
O editor carrega um conjunto de ícones quando você focaliza seu seletor pela primeira vez ou altera o conjunto ou subconjunto, e não quando seleciona o bloco. Campos que solicitam o mesmo conjunto compartilham a solicitação em andamento. O nome do ícone armazenado continua visível antes do carregamento, e voltar a focalizar o seletor tenta novamente uma solicitação que falhou.
tabler-icons oferece suporte a outline e filled. Um subconjunto configurado explicitamente para o conjunto escolhido tem prioridade; caso contrário, o seletor usa solid, se disponível, ou o primeiro subconjunto do conjunto. Conjuntos sem subconjuntos não incluem subSet.
Os nomes dos conjuntos são resolvidos apenas para arquivos incluídos no pacote. A renderização no frontend armazena em cache ícones individuais, em vez de conjuntos completos de ícones em transientes do banco de dados.
Valores de opções importados
Caixas de seleção e listas suspensas com "multiple": true normalmente armazenam um array de objetos { "value": "...", "label": "..." }. Também aceitam um único objeto de opção, uma string ou um número escalar, ou um array de valores escalares importados por meio de REST API ou de ferramentas de conteúdo. Isso também funciona dentro das linhas do repetidor.
O editor exibe esses valores como seleções sem reescrever sua estrutura armazenada quando o salvamento não envolve alterações. Adicionar ou remover uma seleção grava o array habitual de objetos de opção. 0 numéricos e "0" de texto são seleções válidas.
Os modelos recebem o returnFormat configurado para o campo, assim como ocorre com os valores selecionados no editor. As opções ainda precisam corresponder às escolhas declaradas ou preenchidas no campo.
Um campo de seleção nativo de opção única, sem valor armazenado nem padrão, exibe um espaço reservado vazio e desativado, e não sua primeira opção. A seleção explícita da primeira opção a armazena. Depois que uma opção é armazenada, o espaço reservado desaparece. Use allowNull quando os editores também precisarem poder limpar uma seleção; um espaço reservado vazio não permite limpar uma opção que, de outra forma, é obrigatória.
Linhas iniciais do repetidor
No editor, os padrões incluem as linhas mínimas aninhadas antes da inserção. Não é necessário abrir as configurações do bloco para inicializá-las, e a inserção do bloco não adiciona uma segunda etapa de desfazer para essas linhas.
Quando um repetidor tem min, mas não tem um valor salvo nem um default explícito, o servidor inicializa esse número de linhas usando os valores padrão dos campos da linha. Isso também se aplica a incorporações de PHP, tags de bloco e fontes de página baseadas em arquivos que nunca foram abertas no editor. Por exemplo, "min": 2 com um campo de texto cujo valor padrão é "New item" renderiza duas linhas contendo esse valor.
As linhas armazenadas e um repetidor explícito default têm precedência. Uma lista vazia salva explicitamente, false ou null não recria as linhas removidas. A renderização não grava esses valores padrão gerados de volta na publicação. min e max restringem os controles do editor; não truncam nem completam uma lista salva durante a renderização. Use bs_validate_block() para relatar violações dos limites de linhas no conteúdo importado.
Os campos de linha sem default ficam false em uma linha gerada, portanto essa linha não tem conteúdo. As linhas que os editores adicionam e deixam vazias têm a mesma aparência. Um modelo que imprime um cartão, um título ou um item de lista para cada linha deve ignorar as linhas sem conteúdo fora do editor e mantê-las no editor para que seus campos continuem editáveis:
<?php foreach ( $a['items'] as $item ) : ?>
<?php if ( ! $isEditor && ! $item['title'] && ! $item['text'] ) continue; ?>
<div class="item">
<h3><?php echo $item['title']; ?></h3>
<p><?php echo $item['text']; ?></p>
</div>
<?php endforeach; ?>
Remoção de repetidores
A remoção de uma linha abre a caixa de diálogo de confirmação do editor, com os botões Excluir e Cancelar. Cancelar ou pressionar Escape deixa a linha inalterada. A linha só é removida após a confirmação, inclusive dentro de repetidores aninhados.
textRemove controla o mesmo comportamento para todos os repetidores:
| Valor | Comportamento |
|---|---|
Omitido, true ou "" |
Exibe a pergunta de confirmação padrão. |
| Uma string não vazia | Exibe a pergunta personalizada, usando o mecanismo existente de tradução de texto personalizado. |
false |
Remove a linha imediatamente, sem uma caixa de diálogo. |
Por exemplo, "textRemove": "Remove this team member?" altera a pergunta.
A restrição existente min ainda impede a remoção de linhas abaixo do mínimo.
Aninhamento de repetidores
Uma linha de repetidor aceita todos os tipos de campo, exceto tabs. Um campo tabs em uma linha, também dentro de um grupo sem id, exibe um aviso no editor em vez dos campos. A extensão PHPStan relata isso para block.json e field.json. Mantenha os campos da linha nivelados ou mova as abas para fora do repetidor.
Links do WYSIWYG
Por padrão, a barra de ferramentas de links do WYSIWYG insere links que abrem na mesma aba, sem adicionar target ou rel. Ative a opção de nova aba com toolbar.formats.link.opensInNewTab:
{
"id": "content",
"type": "wysiwyg",
"toolbar": {
"formats": {
"link": {
"opensInNewTab": true
}
}
}
}
Escolher uma nova aba adiciona target="_blank" e rel="noreferrer noopener".
Desativar essa opção remove esses atributos automáticos. Para aplicar atributos a todos os links nesse campo, defina toolbar.formats.link.attributes, por exemplo,
{ "class": "content-link", "rel": "nofollow" }. A configuração explícita é preservada, e os tokens de segurança para novas abas são adicionados ao rel configurado.
Digitar um URL não o transforma automaticamente em link, e clicar em um link existente no campo não tira você do editor. Os atributos de links salvos anteriormente permanecem no conteúdo existente; eles não são migrados automaticamente.