Publicado em 13 de abril de 2026
A comunicação entre diferentes componentes de extensão (scripts de segundo plano, scripts de conteúdo, pop-ups) sempre dependeu da serialização JSON. Embora confiável, o JSON tem limitações.
Temos o prazer de anunciar que, a partir do Chrome 148, os desenvolvedores de extensões podem ativar o uso do algoritmo de clonagem estruturada para serialização de mensagens em vez de JSON. Essa modernização permite enviar tipos de dados mais complexos entre os contextos de extensão sem soluções alternativas de serialização manual.
Por que a clonagem estruturada?
A serialização JSON (via JSON.stringify ) é funcional, mas às vezes exige que os desenvolvedores façam malabarismos ao lidar com tipos modernos de JavaScript.
Confira um exemplo específico que você pode ter encontrado ao desenvolver uma extensão:
// Sending a Map with JSON serialization
const myMap = new Map([['id', 123]]);
// Arrives as {} on the other side!
chrome.runtime.sendMessage(myMap);
// Workaround: Convert Map to an Array of entries before sending
const message = Array.from(myMap.entries());
chrome.runtime.sendMessage(message);
// On the receiving side:
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
const receivedMap = new Map(message);
});
Algumas outras situações em que o JSON falha e que você pode ter precisado contornar são objetos Set, BigInt, NaN e Infinity, Date e Error.
O uso da serialização de clonagem estruturada significa que agora você pode enviar vários objetos que antes eram difíceis ou impossíveis de transmitir por mensagens de extensão.
Por exemplo, o envio de um objeto Map agora é direto:
// Sending a Map with Structured Clone
const myMap = new Map([['id', 123]]);
// Arrives as a Map on the other side!
chrome.runtime.sendMessage(myMap);
// On the receiving side:
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
// message is already a Map instance!
console.log(message.get('id')); // 123
});
Mais tipos com suporte
A clonagem estruturada oferece suporte a uma ampla variedade de outros
tipos
como File e Blob.
Como participar
Para garantir a compatibilidade com versões anteriores e evitar a interrupção de extensões atuais, esse recurso é opcional. É possível ativá-lo globalmente para sua extensão adicionando uma única chave ao manifest.json:
{
"name": "My Extension",
"version": "1.0",
"manifest_version": 3,
"message_serialization": "structured_clone"
}
Se omitido ou em uma versão do Chrome anterior à 148, o navegador usa a implementação atual baseada em JSON para a extensão.
Ao oferecer suporte ao algoritmo de clonagem estruturada, estamos aproximando a API de mensagens de extensão do alinhamento com os recursos padrão da plataforma da Web (semelhante ao postMessage usado em Web Workers e comunicação de iframe), oferecendo mais flexibilidade e poder.
Interoperabilidade e problemas
Embora nossa implementação de serialização de clonagem estruturada ofereça suporte a muito mais tipos do que o JSON, há algumas suposições arquitetônicas e incompatibilidades com a implementação que você precisa ter em mente.
Tipos não compatíveis
Objetos compartilhados, como
SharedArrayBuffer
e a transferência de
objetos
como ArrayBuffer não são compatíveis com nossa implementação.
SharedArrayBuffer não será serializado ou desserializado (dependendo da situação), e tentar enviar um objeto transferível, como Uint8Array, enviará uma cópia.
Comunicação de extensão para extensão
Aplicamos formatos de serialização correspondentes para garantir a integridade de dados. Extensões com formatos de serialização incompatíveis não podem se comunicar diretamente por runtime.sendMessage ou runtime.connect. Por exemplo, se a extensão A usar a serialização JSON e tentar enviar uma mensagem para a extensão B usando a clonagem estruturada, a mensagem não será enviada e a porta será fechada (e vice-versa).
Comunicação de página da Web
As páginas da Web que usam externally_connectable se adaptam automaticamente ao formato de serialização da extensão de destino. Se a extensão usar a clonagem estruturada, os contextos da Web que enviam mensagens usando a API runtime vão usar a clonagem estruturada (e vice-versa) automaticamente. Isso significa que o site e a extensão precisam estar sincronizados no formato de serialização esperado para evitar erros de serialização.
Envio de mensagens nativo
Os canais de mensagens nativas continuam sempre forçando a serialização JSON.
A tentativa de enviar tipos somente de clonagem estruturada (como um BigInt) para um host nativo vai falhar antes que uma mensagem saia do contexto da extensão.
Métodos toJSON()
Se você usa classes ou objetos com métodos toJSON() personalizados para realizar a serialização personalizada (por exemplo, higienizar dados removendo senhas antes de enviar um objeto), saiba que a clonagem estruturada ignora toJSON(). Ela copia os valores das propriedades diretamente. Se você depende de toJSON() para a serialização personalizada, algum trabalho manual pode ser necessário antes do envio. Exemplo:
class User {
constructor(name, password) {
this.name = name;
this.password = password;
}
// This will be ignored by structured clone!
toJSON() {
return { name: this.name };
}
}
const user = new User("Alice", "secret123");
// JSON -> {"name":"Alice"}
// Structured Clone -> { name: "Alice", password: "secret123" }
A serialização JSON vai acabar?
Não! O Chrome está comprometido em oferecer suporte aos dois formatos de serialização no futuro previsível.
Compartilhar feedback
Esperamos que esse novo recurso desbloqueie fluxos de trabalho mais suaves e poderosos para o desenvolvimento de extensões.
Embora tenhamos criado um conjunto de testes para validar a funcionalidade da nossa implementação de clonagem estruturada, a plataforma da Web tem uma grande variedade de objetos. Teste esse novo recurso e informe sobre bugs ou casos extremos encontrados. Seu feedback vai nos ajudar a melhorar a implementação para toda a comunidade.