Membuka Kloning Terstruktur untuk Pengiriman Pesan Ekstensi Chrome

Justin Lulejian

Dipublikasikan: 13 April 2026

Komunikasi antara berbagai komponen ekstensi (skrip latar belakang, skrip konten, pop-up) secara tradisional mengandalkan serialisasi JSON. Meskipun dapat diandalkan, JSON memiliki batasan.

Dengan senang hati kami mengumumkan bahwa mulai Chrome 148, developer ekstensi dapat memilih untuk menggunakan algoritma clone terstruktur untuk serialisasi pesan, bukan JSON. Modernisasi ini memungkinkan Anda mengirim jenis data yang lebih kompleks antar-konteks ekstensi tanpa solusi sementara serialisasi manual.

Mengapa harus menggunakan clone terstruktur?

Serialisasi JSON (melalui JSON.stringify di balik layar) berfungsi, tetapi terkadang mengharuskan developer melakukan banyak langkah saat menangani jenis JavaScript modern.

Berikut contoh spesifik yang mungkin Anda temui saat mengembangkan ekstensi:

// 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);
});

Situasi lain saat JSON gagal yang mungkin harus Anda atasi adalah Objek Set, BigInt, NaN, Infinity, Date, dan Error.

Dengan serialisasi clone terstruktur, Anda kini dapat mengirim berbagai objek yang sebelumnya sulit atau tidak mungkin dikirim melalui pesan ekstensi. Misalnya, pengiriman objek Map kini dilakukan secara langsung:

// 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
});

Jenis yang lebih banyak didukung

Clone terstruktur mendukung berbagai jenis lainnya seperti File dan Blob.

Cara ikut serta

Untuk memastikan kompatibilitas mundur dan mencegah kerusakan pada ekstensi yang ada, fitur ini bersifat keikutsertaan. Anda dapat mengaktifkannya secara global untuk ekstensi dengan menambahkan satu kunci ke manifest.json:

{
  "name": "My Extension",
  "version": "1.0",
  "manifest_version": 3,
  "message_serialization": "structured_clone"
}

Jika tidak ada, atau pada Chrome versi di bawah 148, browser akan menggunakan implementasi berbasis JSON saat ini untuk ekstensi.

Dengan mendukung algoritma clone terstruktur, kami menyelaraskan API pesan ekstensi dengan kemampuan platform web standar (mirip dengan postMessage yang digunakan dalam Web Workers dan komunikasi iframe), sehingga memberi Anda lebih banyak fleksibilitas dan kemampuan.

Interoperabilitas dan masalah yang perlu diwaspadai

Meskipun implementasi serialisasi clone terstruktur kami mendukung lebih banyak jenis daripada JSON, ada beberapa asumsi arsitektur dan ketidakcocokan dengan implementasi yang harus Anda ingat.

Jenis yang tidak didukung

Objek bersama seperti SharedArrayBuffer dan transfer objek seperti ArrayBuffer tidak didukung dengan implementasi kami. SharedArrayBuffer akan gagal diserialisasi atau dideserialisasi (bergantung pada situasinya), dan mencoba mengirim objek yang dapat ditransfer seperti Uint8Array akan mengirim salinan.

Komunikasi antar-ekstensi

Kami menerapkan format serialisasi yang cocok untuk memastikan integritas data. Ekstensi dengan format serialisasi yang tidak cocok tidak dapat berkomunikasi secara langsung melalui runtime.sendMessage atau runtime.connect. Misalnya, jika ekstensi A menggunakan serialisasi JSON dan mencoba mengirim pesan ke Ekstensi B menggunakan clone terstruktur, pesan akan gagal dikirim dan port akan ditutup (dan sebaliknya).

Komunikasi halaman web

Halaman Web yang menggunakan externally_connectable akan otomatis menyesuaikan dengan format serialisasi ekstensi target. Jika ekstensi Anda menggunakan clone terstruktur, konteks web yang mengirim pesan menggunakan runtime API akan menggunakan clone terstruktur (dan sebaliknya) secara otomatis. Artinya, situs dan ekstensi harus disinkronkan pada format serialisasi yang diharapkan untuk mencegah error serialisasi.

Pesan native

Saluran pesan native akan selalu menerapkan serialisasi JSON. Mencoba mengirim jenis hanya-clone-terstruktur (seperti BigInt) ke host native akan gagal sebelum pesan keluar dari konteks ekstensi Anda.

Metode toJSON()

Jika Anda menggunakan class atau objek dengan metode toJSON() kustom untuk melakukan serialisasi kustom (misalnya, membersihkan data dengan menghapus sandi sebelum mengirim objek), perlu diketahui bahwa clone terstruktur mengabaikan toJSON(). Properti ini menyalin nilai properti secara langsung. Jika Anda mengandalkan toJSON() untuk serialisasi kustom, beberapa pekerjaan manual mungkin diperlukan sebelum mengirim. Contoh:

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" }

Apakah serialisasi JSON akan dihentikan?

Tidak! Chrome berkomitmen untuk mendukung kedua format serialisasi tersebut dalam waktu dekat.

Berikan masukan

Kami harap kemampuan baru ini akan menghadirkan alur kerja yang lebih lancar dan efektif untuk pengembangan ekstensi Anda.

Meskipun kami telah membuat rangkaian pengujian untuk memvalidasi fungsi penerapan clone terstruktur kami, platform web memiliki berbagai macam objek. Coba fitur baru ini dan laporkan bug atau kasus ekstrem yang Anda temui. Masukan Anda akan membantu kami meningkatkan kualitas penerapan untuk seluruh komunitas.