Depreciação de Bloco Gutenberg: Atualize Sem Quebrar Conteúdo

Resumo

Atualizar um bloco Gutenberg frequentemente quebra posts existentes que usam a versão antiga. Este artigo mostra como usar a propriedade deprecated em block.json para manter a compatibilidade reversa. Você aprenderá as etapas exatas para capturar a marcação atual do bloco, definir uma ou mais versões depreciadas e mapear atributos corretamente. Abordaremos blocos estáticos e dinâmicos, com exemplos práticos. O artigo também questiona a suposição de que a depreciação é sempre a melhor abordagem, discutindo quando uma quebra limpa pode ser melhor. Ao final, você será capaz de atualizar seus blocos com confiança sem quebrar o conteúdo dos seus usuários.

O Cenário de Mudança que Quebra

Você lançou um bloco de depoimento personalizado há seis meses. Ele gera uma simples <div> com uma citação e um nome de autor. Agora seu cliente quer um novo design: o autor deve aparecer acima da citação, com uma classe CSS diferente. Você atualiza a função save do bloco e o render_callback. Você testa em um post novo—parece ótimo. Então você navega para um post antigo que usa o bloco. Desastre: o texto da citação sumiu, o autor está no lugar errado e a estilização está errada. Você acabou de quebrar toda página que usa o bloco.

Este é o clássico problema de "mudança que quebra" no desenvolvimento de blocos Gutenberg. Blocos são essencialmente estruturas de dados combinadas com marcação. Quando você muda a marcação, o editor não consegue mapear automaticamente o conteúdo antigo para a nova estrutura. O resultado é ou um erro de validação (o bloco se torna inválido) ou—pior—corrupção silenciosa onde o bloco renderiza incorretamente.

O que é Depreciação de Bloco?

A depreciação de bloco é o mecanismo embutido do Gutenberg para lidar com mudanças de versão. Ao definir um array deprecated no block.json do seu bloco, você diz ao editor: "Se você encontrar um bloco que corresponda a uma dessas versões mais antigas, transforme-o na versão atual." Cada entrada depreciada especifica os attributes, supports e função save (ou render_callback) anteriores. Quando o editor carrega um bloco antigo, ele percorre o array depreciado em ordem e aplica a primeira transformação correspondente.

Esse recurso é frequentemente subutilizado porque os desenvolvedores assumem que nunca precisarão alterar a marcação de um bloco. Mas em projetos reais, os requisitos evoluem. Se você pular a depreciação, ou força os usuários a deletar e reinserir blocos (má experiência) ou mantém duas versões separadas do bloco (bagunçado). O manual oficial do desenvolvedor WordPress cobre isso no Manual do Editor de Blocos, mas faltam guias práticos.

Passo 1: Capture o Estado Atual

Antes de fazer qualquer alteração, registre a saída exata de save (ou render_callback para blocos dinâmicos) e os attributes que seu bloco usa atualmente. Pense nisso como tirar uma foto. Para blocos estáticos, salve o JSX retornado pela função save. Para blocos dinâmicos, salve a marcação PHP gerada por render_callback.

Crie um novo arquivo em seu plugin chamado deprecated.js (ou similar) e armazene a função save antiga lá. Alternativamente, mantenha as versões depreciadas diretamente no arquivo JavaScript principal do bloco. O segredo é preservar esse código exatamente como era quando o bloco foi implantado pela primeira vez.

Passo 2: Defina Suas Versões Depreciadas

No seu block.json, adicione um array deprecated. Cada entrada é um objeto que pode incluir:

• attributes (objeto): As definições de atributos anteriores.
• supports (objeto): Quaisquer configurações de suporte anteriores que mudaram.
• save (função ou string): A função save anterior. Para blocos somente JavaScript, você importará a função antiga. Para blocos dinâmicos renderizados em PHP, você pode usar migrate e render_callback em vez disso.
• migrate (função): Uma função que mapeia atributos antigos para novos (opcional).

Exemplo:

"deprecated": [
  {
    "attributes": {
      "quote": { "type": "string", "source": "html", "selector": ".quote" },
      "author": { "type": "string", "source": "html", "selector": ".author" }
    },
    "supports": {},
    "save": "() => <div className=\"testimonial-legacy\"><p className=\"quote\">{attributes.quote}</p><p className=\"author\">{attributes.author}</p></div>"
  }
]

Nota: A função save em block.json é normalmente definida em JavaScript. Se você estiver usando um script externo, precisará enfileirá-lo e referenciar o nome da função. Alternativamente, você pode incluir a função como uma string (embora isso não seja recomendado para blocos complexos).

Passo 3: Mapeie Atributos

Frequentemente, você altera não apenas a marcação, mas também os nomes ou fontes dos atributos. Por exemplo, você pode mudar de armazenar o autor como uma string simples para um campo de texto rico. Nesses casos, use a propriedade migrate para transformar atributos antigos em novos.

migrate: (attributes) => {
  return {
    quote: attributes.quote,
    author: { content: attributes.author, level: 2 }
  };
}

Se você não fornecer uma função migrate, o editor simplesmente passará os atributos antigos diretamente para o novo bloco. Isso pode causar erros se os nomes dos atributos mudaram.

Passo 4: Teste com Conteúdo Real

Após definir a versão depreciada, teste minuciosamente. Crie um novo post, insira o bloco antigo (você pode simular colando o código do bloco serializado de um post existente) e verifique se ele converte para a nova versão sem erros de validação. Teste também editar e salvar o bloco convertido. Repita para várias versões depreciadas, se houver.

Para blocos dinâmicos, o processo é semelhante, mas com uma diferença: a função save para um bloco dinâmico normalmente retorna null (o bloco renderiza via PHP). Na entrada depreciada, você pode definir save para a marcação estática anterior que era usada antes de mudar para renderização dinâmica, ou usar um render_callback em PHP que lida com estruturas de atributos antigas e novas. Isso é mais complexo, mas factível.

Ressalvas e Compensações

A depreciação é poderosa, mas tem desvantagens. Cada versão depreciada adiciona código ao seu plugin. Com o tempo, você pode acabar com uma cadeia de cinco ou seis versões legadas raramente usadas, mas que precisam ser mantidas. A equipe principal do WordPress recomenda manter pelo menos duas versões anteriores, mas além disso, você pode considerar uma quebra limpa se o número de posts afetados for pequeno.

Outra nuance: a ordem das entradas depreciadas importa. O editor itera pelo array do índice 0 para cima e usa a primeira correspondência. Se duas versões depreciadas forem semelhantes, a errada pode ser aplicada. Sempre liste a versão depreciada mais recente primeiro (aquela que precede diretamente a versão atual).

Finalmente, a depreciação não lida com conteúdo que foi editado usando uma mudança de estilo em todo o site (por exemplo, via theme.json). Se a aparência do seu bloco dependia de estilos globais que mudaram, a depreciação não ajustará isso. Você pode precisar adicionar um script de migração que execute ao salvar ou através de um hook de atualização de plugin.

Quando a Depreciação Não é a Resposta

A maioria dos tutoriais apresenta a depreciação como obrigatória. Na realidade, há situações em que uma quebra limpa é melhor. Se seu bloco é novo e usado em apenas alguns posts, atualizar manualmente essas poucas instâncias pode ser mais rápido do que escrever e testar código de depreciação. Da mesma forma, se o modelo de dados subjacente do bloco é fundamentalmente diferente (por exemplo, você está mesclando dois blocos em um), a depreciação pode não ser flexível o suficiente. Nesse caso, escreva um script de migração único que execute quando o plugin for atualizado, convertendo blocos antigos para o novo formato.

Outro ponto contrário: a depreciação não deve ser usada como substituto para um bom design. Se você antecipa mudanças frequentes, projete seu bloco com versionamento em mente desde o início—por exemplo, armazenando um atributo version e usando renderização condicional. Essa abordagem, discutida em Além dos Blocos Básicos, é mais leve que a depreciação, mas requer previsão.

Conclusão

A depreciação de blocos é uma ferramenta essencial para qualquer desenvolvedor Gutenberg sério. Ela permite evoluir seus blocos sem quebrar o conteúdo dos usuários. Os passos principais são: capture o estado atual, defina a versão depreciada em block.json, mapeie atributos se necessário e teste com conteúdo real. Mas lembre-se de que a depreciação vem com custos de manutenção. Às vezes, uma quebra limpa ou um design de bloco versionado é mais pragmático. Use a depreciação estrategicamente, não automaticamente, e seus blocos permanecerão robustos através de muitas atualizações.

Para uma perspectiva mais ampla sobre construção de plugins sustentáveis, veja Construindo Plugins WordPress Robustos. E se você é novo no desenvolvimento de blocos, Além dos Blocos Básicos ajudará você a começar.