fswp-block-developer

FSWP Block Developer

Fundamental (sempre aplicado): fswp-developer/references/lean-coding.md (escreva menos, reutilize primeiro), fswp-developer/references/coding-standards.md (padrões de codificação, documentação, i18n, acessibilidade) e fswp-security-engineer (entrada, saída, autorização).

Use blocos principais primeiro; escreva um bloco personalizado somente quando os blocos principais e padrões não puderem expressar o requisito. Referências oficiais: links do Manual do Editor de Blocos em fswp-developer/references/official-docs.md. Verifique a versão mínima do WordPress para cada API em relação à versão mínima declarada do projeto.

Anatomia

blocks/meu-bloco/
  block.json      nome, título, categoria, atributos, suportes, render, editorScript, viewScriptModule, estilo
  edit.js         interface do editor (usa useBlockProps)
  save.js         marcação estática, ou omita para blocos dinâmicos
  render.php      renderização no servidor para blocos dinâmicos
  view.js         comportamento no front-end (módulo)
  style.scss / editor.scss

Registre a partir dos metadados: register_block_type( __DIR__ . '/build/meu-bloco' ) em init (use uma função nomeada para o callback init). Defina "apiVersion": 3 (atual desde WordPress 6.3) e adicione "$schema": "https://schemas.wp.org/trunk/block.json". Referência campo por campo, verificada em relação ao Manual do Editor de Blocos: references/block-json.md.

Decisões

Pergunta	Escolha
A saída depende apenas de atributos salvos	Bloco Estático (save.js)
A saída depende de dados ao vivo, deve mudar sem salvar novamente ou contém lógica	Bloco Dinâmico (render.php); save retorna null ou apenas InnerBlocks
Conteúdo aninhado	InnerBlocks com allowedBlocks e template
Vincular um atributo a dados (meta de post, fonte personalizada)	API de Bindings de Bloco (register_block_bindings_source) onde a versão mínima do WordPress permite
Predefinições alternativas de um bloco existente	Variações ou estilos de bloco, não um novo bloco
Layout reutilizável	Um padrão, não um bloco

Regras

• Atributos: dê a cada atributo um type e default; obtenha-os da marcação ou comentários consistentemente; valide em render.php.
• Use supports (cor, espaçamento, tipografia, alinhamento, âncora) em vez de escrever controles.
• A marcação do editor deve usar useBlockProps(); PHP dinâmico usa get_block_wrapper_attributes().
• render.php (render no block.json, WordPress 6.1+) recebe $attributes, $content e $block (um WP_Block). Ele carrega uma vez por instância de bloco na página, portanto, nunca declare funções ou classes dentro dele; chame código compartilhado de outro arquivo.
• Scripts vs módulos: viewScript é para scripts clássicos (e qualquer coisa que dependa de scripts do WordPress); viewScriptModule (6.5+) é para módulos de script, como a API de Interatividade. Eles não são intercambiáveis, portanto, não misture dependências entre os dois.
• Escape tudo em render.php (fswp-security-engineer); atributos são entrada do usuário.
• Alterar a marcação salva de um bloco estático já enviado quebra o conteúdo existente. Adicione uma entrada deprecated com o save antigo, atributos e uma função migrate, depois altere o bloco.
• Traduza strings (__() com o domínio de texto) em JS e PHP; wp_set_script_translations ou textdomain no block.json.
• Carregue scripts de front-end apenas onde o bloco renderiza (viewScriptModule/script no block.json fazem isso).

Padrões

Mais detalhes sobre padrões, variações, hooks de bloco e bindings: references/patterns-variations.md. Profundidade da API de Interatividade (renderização no servidor, ações assíncronas, data-wp-each, observadores, desempenho): references/interactivity.md.

Registre em PHP com register_block_pattern() (e register_block_pattern_category()), ou como arquivos no diretório patterns/ de um tema. Padrões usam predefinições e texto traduzido; sem imagens remotas; dê a eles um título claro, categorias e palavras-chave.

API de Interatividade

Marcação renderizada no servidor mais comportamento reativo pequeno, sem necessidade de framework.

• Habilite com "supports": { "interactivity": true } e "viewScriptModule": "file:./view.js".
• Diretivas de marcação: data-wp-interactive="namespace", data-wp-context='{"open":false}', data-wp-on--click="actions.toggle", data-wp-bind--hidden="!context.open", data-wp-class--is-open="context.open", data-wp-text="state.label".
• Store em view.js: import { store, getContext } from '@wordpress/interactivity'; store( 'namespace', { state: {...}, actions: { toggle() { const c = getContext(); c.open = ! c.open; } } } );
• Semeie estado do servidor com wp_interactivity_state( 'namespace', array(...) ) para que a primeira pintura seja correta e não haja flash. Mantenha o estado serializável.
• Namespace tudo para evitar colisões; nunca coloque segredos no estado ou contexto (ambos são impressos na página).
• Para acessibilidade, associe aria-expanded e o gerenciamento de foco ao estado, e teste o uso do teclado.

Construir e testar

npx @wordpress/create-block para um ponto de partida; @wordpress/scripts para build, start, lint-js, lint-style, test-unit-js. Envie os arquivos compilados juntamente com src/, package.json e o arquivo de bloqueio (regra de diretório para código compilado). Teste no editor (inserir, editar, salvar, recarregar, alternar para visualização de código) e no front-end. Passe para fswp-qa-engineer.