Разблокируйте структурированный клон для расширений Chrome для обмена сообщениями.

Justin Lulejian

Опубликовано: 13 апреля 2026 г.

Традиционно обмен данными между различными компонентами расширений (фоновыми скриптами, скриптами контента, всплывающими окнами) осуществлялся с помощью сериализации в формате JSON. Несмотря на свою надежность, JSON имеет свои ограничения.

Мы рады сообщить, что начиная с Chrome 148 разработчики расширений могут использовать алгоритм структурированного клонирования для сериализации сообщений вместо JSON! Это обновление позволяет передавать более сложные типы данных между контекстами ваших расширений без необходимости ручной сериализации.

Почему именно структурированный клон?

Сериализация JSON (с помощью JSON.stringify внутри) функциональна, но иногда требует от разработчиков дополнительных усилий при работе с современными типами данных JavaScript.

Вот конкретный пример, с которым вы могли столкнуться при разработке расширения:

// 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 дает сбой и которые вам, возможно, пришлось обходить, относятся объекты Set , BigInt , NaN и Infinity , Date и Error .

Использование структурированной клонированной сериализации позволяет теперь отправлять различные объекты, которые ранее было сложно или невозможно передать через расширенные сообщения. Например, отправка объекта Map теперь осуществляется напрямую:

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

Больше поддерживаемых типов

Структурированное клонирование поддерживает широкий спектр других типов , таких как File и Blob .

Как принять участие

Для обеспечения обратной совместимости и предотвращения сбоев в работе существующих расширений эта функция является необязательной . Вы можете включить её глобально для своего расширения, добавив один ключ в файл manifest.json :

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

Если этот параметр опущен или используется в версии Chrome ниже 148, браузер по умолчанию использует текущую реализацию расширения на основе JSON.

Поддерживая алгоритм структурированного клонирования, мы приближаем API обмена сообщениями расширений к стандартным возможностям веб-платформы (аналогично postMessage используемому в Web Workers и обмене данными через iframe), предоставляя вам больше гибкости и возможностей.

Взаимодействие и подводные камни

Хотя наша реализация сериализации структурированных клонов поддерживает гораздо больше типов, чем JSON, следует помнить о некоторых архитектурных предположениях и несовместимостях с этой реализацией.

Неподдерживаемые типы

В нашей реализации не поддерживаются разделяемые объекты, такие как SharedArrayBuffer , и передача объектов типа ArrayBuffer . Сериализация или десериализация SharedArrayBuffer завершится неудачей (в зависимости от ситуации), а попытка отправить передаваемый объект, например Uint8Array приведет к отправке его копии.

Коммуникация между расширениями

Мы обеспечиваем соответствие форматов сериализации для гарантии целостности данных. Расширения с несовпадающими форматами сериализации не могут напрямую взаимодействовать через runtime.sendMessage или runtime.connect . Например, если расширение A использует сериализацию JSON и пытается отправить сообщение расширению B, используя структурированное клонирование, отправка сообщения завершится неудачей, и порт будет закрыт (и наоборот).

Связь через веб-страницу

Веб-страницы, использующие externally_connectable автоматически адаптируются к формату сериализации целевого расширения. Если ваше расширение использует структурированное клонирование, веб-контексты, отправляющие сообщения с помощью API runtime , будут автоматически использовать структурированное клонирование (и наоборот). Это означает, что веб-сайт и расширение должны быть синхронизированы по ожидаемому формату сериализации, чтобы предотвратить ошибки сериализации.

Нативная система обмена сообщениями

Встроенные каналы обмена сообщениями по-прежнему всегда принудительно используют сериализацию JSON. Попытка отправки типов, содержащих только структурированные клоны (например, BigInt ), на нативный хост завершится неудачей до того, как сообщение покинет контекст вашего расширения.

методы toJSON()

Если вы используете классы или объекты с пользовательскими методами toJSON() для выполнения пользовательской сериализации (например, для очистки данных путем удаления паролей перед отправкой объекта), имейте в виду, что structured clone игнорирует toJSON() . Он копирует значения свойств напрямую. Если вы полагаетесь на toJSON() для пользовательской сериализации, перед отправкой может потребоваться некоторая ручная работа. Например:

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

Неужели сериализация JSON исчезнет?

Нет! Chrome обязуется поддерживать оба формата сериализации в обозримом будущем.

Поделитесь своим мнением

Мы надеемся, что эта новая возможность откроет более плавные и эффективные рабочие процессы для разработки ваших расширений.

Хотя мы создали набор тестов для проверки функциональности нашей реализации структурированного клонирования, веб-платформа содержит огромное количество различных объектов. Попробуйте эту новую функцию и сообщите о любых обнаруженных ошибках или нестандартных ситуациях! Ваши отзывы помогут нам улучшить реализацию для всего сообщества.