Chrome uzantısı mesajlaşması için Yapılandırılmış Klonlama'yı etkinleştirme

Justin Lulejian

Yayınlanma tarihi: 13 Nisan 2026

Farklı uzantı bileşenleri (arka plan komut dosyaları, içerik komut dosyaları, pop-up'lar) arasındaki iletişim geleneksel olarak JSON serileştirmesine dayanır. JSON güvenilir olsa da sınırlamaları vardır.

Chrome 148'den itibaren uzantı geliştiricilerin, mesaj serileştirme için JSON yerine yapılandırılmış klonlama algoritmasını kullanmayı etkinleştirebileceğini duyurmaktan heyecan duyuyoruz. Bu modernizasyon, manuel serileştirme geçici çözümleri olmadan uzantı bağlamlarınız arasında daha karmaşık veri türleri göndermenize olanak tanır.

Neden yapılandırılmış klonlama?

JSON serileştirme (arka planda JSON.stringify aracılığıyla) işlevseldir ancak bazen geliştiricilerin modern JavaScript türleriyle uğraşırken zorlanmasına neden olur.

Uzantı geliştirirken karşılaşmış olabileceğiniz belirli bir örneği aşağıda görebilirsiniz:

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

JSON'un başarısız olduğu ve geçici çözümler bulmanız gereken diğer bazı durumlar şunlardır: Set, BigInt, NaN ve Infinity, Date ve Error nesneleri.

Yapılandırılmış klon serileştirme sayesinde, daha önce uzantı mesajlaşması üzerinden iletilmesi zor veya imkansız olan çeşitli nesneleri artık gönderebilirsiniz. Örneğin, Map nesnesi artık doğrudan gönderilebilir:

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

Daha fazla desteklenen tür

Yapılandırılmış klonlama, File ve Blob gibi birçok diğer türü destekler.

Kaydolma

Geriye dönük uyumluluğu sağlamak ve mevcut uzantıların bozulmasını önlemek için bu özellik etkinleştirilmelidir. manifest.json dosyasına tek bir anahtar ekleyerek uzantınız için küresel olarak etkinleştirebilirsiniz:

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

Atlanırsa veya Chrome'un 148'den eski bir sürümünde tarayıcı, uzantı için geçerli JSON tabanlı uygulamasına varsayılan olarak ayarlanır.

Yapılandırılmış klon algoritmasını destekleyerek uzantı mesajlaşma API'sini standart web platformu özellikleriyle (Web Workers ve iframe iletişiminde kullanılan postMessage'ye benzer şekilde) daha uyumlu hale getiriyoruz. Bu sayede daha fazla esneklik ve güç elde edebilirsiniz.

Birlikte çalışabilirlik ve dikkat edilmesi gereken noktalar

Yapılandırılmış klon serileştirme uygulamamız JSON'dan çok daha fazla türü desteklese de, aklınızda bulundurmanız gereken birkaç mimari varsayım ve uygulamayla ilgili uyumsuzluk vardır.

Desteklenmeyen türler

SharedArrayBuffer gibi paylaşılan nesneler ve ArrayBuffer gibi nesne aktarımı uygulamamızda desteklenmez. SharedArrayBuffer, seri hale getirilemez veya seri halinden çıkarılamaz (duruma bağlı olarak) ve Uint8Array gibi aktarılabilir bir nesne göndermeye çalışıldığında bunun yerine bir kopya gönderilir.

Uzantılar arası iletişim

Veri bütünlüğünü sağlamak için eşleşen serileştirme biçimlerini zorunlu kılıyoruz. Serileştirme biçimleri eşleşmeyen uzantılar, runtime.sendMessage veya runtime.connect üzerinden doğrudan iletişim kuramaz. Örneğin, A uzantısı JSON serileştirmeyi kullanıyorsa ve yapılandırılmış klon kullanarak B uzantısına mesaj göndermeye çalışıyorsa mesaj gönderilemez ve bağlantı noktası kapanır (veya tam tersi).

Web sayfası iletişimi

externally_connectable kullanan web sayfaları, hedef uzantının serileştirme biçimine otomatik olarak uyum sağlar. Uzantınız yapılandırılmış klon kullanıyorsa runtime API'yi kullanarak mesaj gönderen web bağlamları otomatik olarak yapılandırılmış klonu kullanır (ve bunun tersi de geçerlidir). Bu nedenle, serileştirme hatalarını önlemek için web sitesi ve uzantının beklenen serileştirme biçiminde senkronize olması gerekir.

Yerel mesajlaşma

Yerel mesajlaşma kanalları, JSON serileştirmeyi her zaman zorunlu kılmaya devam eder. Yalnızca yapılandırılmış klon türlerini (ör. BigInt) yerel bir ana makineye göndermeye çalışırsanız ileti, uzantınızın bağlamından ayrılmadan önce işlem başarısız olur.

toJSON() yöntemleri

Özel toJSON() yöntemleriyle özel serileştirme (ör. bir nesne gönderilmeden önce şifreleri kaldırarak verileri temizleme) gerçekleştirmek için sınıflar veya nesneler kullanıyorsanız yapılandırılmış klonun toJSON() yoksayacağını unutmayın. Özellik değerlerini doğrudan kopyalar. Özel serileştirme için toJSON() kullanıyorsanız göndermeden önce bazı manuel işlemler yapmanız gerekebilir. Örneğin:

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

Is JSON serialization going away?

Hayır Chrome, öngörülebilir gelecekte her iki serileştirme biçimini de desteklemeye devam edecektir.

Geri bildiriminizi paylaşın

Bu yeni özelliğin, uzantı geliştirme sürecinizde daha sorunsuz ve güçlü iş akışları oluşturmanıza yardımcı olacağını umuyoruz.

Yapılandırılmış klon uygulamamızın işlevselliğini doğrulamak için bir test paketi oluşturmuş olsak da web platformunda çok çeşitli nesneler bulunur. Bu yeni özelliği deneyin ve karşılaştığınız hataları veya uç durumları bildirin. Geri bildirimleriniz, bu özelliği tüm topluluk için daha iyi hale getirmemize yardımcı olacaktır.