إتاحة استخدام Structured Clone في المراسلة بين إضافات Chrome

Justin Lulejian

تاريخ النشر: 22 أبريل 2026

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

يسرّنا الإعلان عن أنّه بدءًا من الإصدار 148 من Chrome، يمكن لمطوّري الإضافات اختيار استخدام خوارزمية الاستنساخ المنظَّم لتسلسل الرسائل بدلاً من 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 بتوفير كلا تنسيقي التسلسل في المستقبل المنظور.

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

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

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