إتاحة استخدام Structured Clone في المراسلة بين إضافات 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 للإضافة.

من خلال دعم خوارزمية الاستنساخ المنظَّم، نقرّب واجهة برمجة التطبيقات لمراسلة الإضافة من التوافق مع إمكانات منصة الويب العادية (على غرار postMessage المستخدَمة في Web Workers والتواصل عبر iframe)، ما يمنحك مزيدًا من المرونة والفعالية.

إمكانية التشغيل التفاعلي والمشاكل المحتملة

على الرغم من أنّ تنفيذ تسلسل الاستنساخ المنظَّم يتيح استخدام أنواع أكثر بكثير من JSON، هناك بعض الافتراضات المعمارية وحالات عدم التوافق مع التنفيذ التي يجب أخذها في الاعتبار.

الأنواع غير المتوافقة

لا يتوافق تنفيذنا مع الكائنات المشترَكة، مثل SharedArrayBuffer ونقل الكائنات، مثل ArrayBuffer سيتعذّر تسلسل SharedArrayBuffer أو إلغاء تسلسله (حسب الحالة)، وستؤدي محاولة إرسال كائن قابل للنقل، مثل Uint8Array، إلى إرسال نسخة بدلاً من ذلك.

التواصل بين الإضافات

نفرض مطابقة تنسيقات التسلسل لضمان صحّة البيانات. لا يمكن للإضافات التي تتضمّن تنسيقات نشر على نحو متسلسِل غير متطابقة التواصل مباشرةً عبر runtime.sendMessage أو runtime.connect. على سبيل المثال، إذا كانت الإضافة "أ" تستخدم تسلسل JSON وحاولت إرسال رسالة إلى الإضافة "ب" باستخدام الاستنساخ المنظَّم، سيتعذّر إرسال الرسالة وسيتم إغلاق المنفذ (والعكس صحيح).

التواصل مع صفحة الويب

ستتكيّف صفحات الويب التي تستخدم externally_connectable تلقائيًا مع تنسيق التسلسل الخاص بالإضافة المستهدَفة. إذا كانت إضافتك تستخدم الاستنساخ المنظَّم، ستستخدم سياقات الويب التي ترسل رسائل باستخدام واجهة برمجة التطبيقات runtime الاستنساخ المنظَّم (والعكس صحيح) تلقائيًا. يعني ذلك أنّه يجب أن يكون الموقع الإلكتروني والإضافة متزامنين بشأن تنسيق النشر على نحو متسلسِل المتوقّع لمنع أخطاء النشر على نحو متسلسِل.

المُراسلة الأصلية

تستمر قنوات المراسلة الأصلية في فرض تسلسل JSON دائمًا. ستفشل محاولة إرسال أنواع لا يمكن استخدامها إلا مع الاستنساخ المنظَّم (مثل BigInt) إلى مضيف أصلي قبل أن تغادر الرسالة سياق إضافتك.

طُرق toJSON()

إذا كنت تستخدم فئات أو كائنات تتضمّن طُرق toJSON() مخصّصة لإجراء تسلسل مخصّص (على سبيل المثال، تنظيف البيانات عن طريق إزالة كلمات المرور قبل إرسال كائن)، يُرجى العِلم أنّ الاستنساخ المنظَّم يتجاهل 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 بدعم كلا تنسيقَي التسلسل في المستقبل المنظور.

مشاركة الملاحظات

نأمل أن تتيح هذه الإمكانية الجديدة مهام سير عمل أكثر سلاسة وفعالية لتطوير إضافتك.

على الرغم من أنّنا أنشأنا مجموعة اختبار للتحقّق من وظائف تنفيذ الاستنساخ المنظَّم، تتضمّن منصة الويب مجموعة كبيرة ومتنوّعة من الكائنات. يمكنك تجربة هذه الميزة الجديدة و الإبلاغ عن أي أخطاء أو حالات خاصة تواجهها. ستساعدنا ملاحظاتك في تحسين التنفيذ للمجتمع بأكمله.