CKTIS / JavaScript
Worker: tratar `message`, `error` e `messageerror`
Distingue três eventos de um worker dedicado: uma mensagem recebida, um erro do worker e uma mensagem que o destinatário não consegue desserializar.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
const worker = new Worker(url);
worker.onmessage = (event) => { /* use event.data */ };
worker.onerror = (event) => { /* handle a worker error */ };
worker.onmessageerror = (event) => { /* handle a receive-side deserialization failure */ };
// Alternative for any of the three properties:
worker.addEventListener("message", handleMessage);
worker.addEventListener("error", handleError);
worker.addEventListener("messageerror", handleMessageError);worker.onmessage, worker.onerror e worker.onmessageerror são propriedades de tratamento de eventos da instância de Worker dedicado, do lado que a criou. São definidas pelo padrão HTML, não pelo ECMAScript 2024. O suporte depende do ambiente de execução, sobretudo para messageerror. Configura os gestores de eventos antes de enviares o primeiro pedido.
onmessage recebe um MessageEvent quando uma mensagem do worker é desserializada com sucesso. Lê o conteúdo em event.data e confirma que tem a estrutura esperada pela aplicação: a clonagem estruturada não valida o teu protocolo. Dentro do worker, self.onmessage trata o sentido inverso, ou seja, as mensagens do contexto que o criou.
onerror recebe um único objeto de evento. Uma exceção síncrona não capturada que seja comunicada ao contexto criador origina um ErrorEvent; não contes com event.error para obter a exceção original. Uma falha no carregamento do script pode originar um simples Event. Se o evento for cancelável, event.preventDefault() pode impedir que o erro continue a ser comunicado, mas não retoma o código interrompido. Dentro do worker, self.onerror tem uma forma histórica com cinco argumentos para ErrorEvent e pode cancelar a comunicação com return true; esta regra não se aplica a worker.onerror.
onmessageerror recebe um MessageEvent não cancelável em vez de message quando o destinatário não consegue desserializar uma mensagem. Não há conteúdo descodificado para ler. Em contrapartida, passar uma função a postMessage() lança DataCloneError de forma síncrona do lado do remetente e não gera messageerror do lado do destinatário.
Cada propriedade guarda um único gestor: uma nova atribuição substitui-o e a atribuição de null remove-o. Usa addEventListener() com o nome do evento sem on para registar ouvintes independentes. Chama worker.terminate() quando já não precisares do worker; o método não espera que o trabalho pendente termine.
Exemplos
(() => {
const inNode = typeof require === "function" &&
typeof process !== "undefined" && Boolean(process.versions?.node);
const handler = `
function handleMessage(data, reply) {
if (data === "fail") throw new Error("demo failure");
reply(data * 2);
}
`;
let worker;
let messageErrorTarget;
function reportMessageError(event) {
console.log(event.isTrusted ? "messageerror" : "messageerror (synthetic)");
}
function receiveReply(data) {
console.log(`message: ${data}`);
messageErrorTarget.dispatchEvent(new MessageEvent("messageerror"));
worker.postMessage("fail");
}
if (inNode) {
const { Worker: ThreadWorker } = require("node:worker_threads");
worker = new ThreadWorker(handler + `
const { parentPort } = require("node:worker_threads");
parentPort.on("message", (data) => {
handleMessage(data, (value) => parentPort.postMessage(value));
});
`, { eval: true });
// Node worker threads do not use the browser's handler properties.
messageErrorTarget = new EventTarget();
messageErrorTarget.addEventListener("messageerror", reportMessageError);
worker.on("message", receiveReply);
worker.on("error", (error) => {
if (error.message !== "demo failure") throw error;
console.log("error: runtime");
});
} else {
const script = handler + `
self.onmessage = ({ data }) => {
handleMessage(data, (value) => self.postMessage(value));
};
`;
const url = URL.createObjectURL(new Blob([script], { type: "text/javascript" }));
try {
worker = new Worker(url);
} catch (error) {
URL.revokeObjectURL(url);
throw error;
}
messageErrorTarget = worker;
worker.onmessage = (event) => receiveReply(event.data);
worker.onmessageerror = reportMessageError;
worker.onerror = (event) => {
event.preventDefault();
console.log(event instanceof ErrorEvent ? "error: runtime" : "error: startup");
worker.terminate();
URL.revokeObjectURL(url);
};
}
try {
worker.postMessage(() => {});
} catch (error) {
console.log(`send: ${error.name}`);
}
worker.postMessage(21);
})();Resultado
send: DataCloneError message: 42 messageerror (synthetic) error: runtime
Para experimentares as propriedades de tratamento de eventos de Web Workers, executa o exemplo completo na consola do navegador, numa página cuja política de segurança permita workers `blob:`. Em Node.js 24, guarda o código em `main.cjs` e executa `node main.cjs`; este ramo usa `node:worker_threads`, não as propriedades de tratamento de eventos do `Worker` do navegador. Nos dois ambientes, `messageerror (synthetic)` testa apenas o gestor, não uma falha real de desserialização nem o suporte nativo do evento.
Lições relacionadas
- JavaScript · Lição 32 · Avançado · Versão: 4
Fontes
- HTML Standard — Dedicated workers and the Worker interface
- HTML Standard — The worker's lifetime
- HTML Standard — Runtime script errors
- HTML Standard — Event handlers
- HTML Standard — Message ports
- HTML Standard — StructuredSerializeInternal
- Worker: message event
- Worker: messageerror event
- Worker: Worker() constructor
- HTML Standard — Processing model