chrome.offscreen

الوصف

استخدِم واجهة برمجة تطبيقات offscreen لإنشاء المستندات خارج الشاشة وإدارتها.

الأذونات

offscreen

لاستخدام واجهة برمجة التطبيقات Offscreen، يُرجى تعريف الإذن "offscreen" في بيان الإضافة. مثال:

{
  "name": "My extension",
  ...
  "permissions": [
    "offscreen"
  ],
  ...
}

مدى توفّر الخدمة

Chrome 109 والإصدارات الأحدث MV3 والإصدارات الأحدث

المفاهيم والاستخدام

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

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

في ما يلي طرق أخرى لاختلاف المستندات التي تظهر خارج الشاشة عن الصفحات العادية:

• يجب أن يكون عنوان URL للمستند خارج الشاشة ملف HTML ثابتًا مضمّنًا مع الإضافة.
• لا يمكن التركيز على المستندات خارج الشاشة.
• المستند خارج الشاشة هو مثيل لـ window، ولكن قيمة السمة opener تكون دائمًا null.
• على الرغم من أنّ حزمة الإضافة يمكن أن تحتوي على مستندات متعدّدة خارج الشاشة، لا يمكن أن تحتوي الإضافة المُثبَّتة إلا على مستند واحد مفتوح في كل مرة. إذا كانت الإضافة تعمل في وضع التقسيم مع ملف شخصي نشط للتصفّح المتخفي، يمكن أن يحتوي كل من الملفات الشخصية العادية والملفات الشخصية في وضع التصفّح المتخفي على مستند واحد خارج الشاشة.

استخدِم chrome.offscreen.createDocument() وchrome.offscreen.closeDocument() لإنشاء مستند خارج الشاشة وإغلاقه. تتطلّب السمة createDocument() السمة url للمستند وسببًا وتبريرًا:

chrome.offscreen.createDocument({
  url: 'off_screen.html',
  reasons: ['CLIPBOARD'],
  justification: 'reason for needing the document',
});

الأسباب

للحصول على قائمة بالأسباب الوجيهة، يُرجى مراجعة قسم الأسباب. يتم تعيين الأسباب أثناء إنشاء الوثيقة لتحديد عمر الوثيقة. يؤدّي السبب AUDIO_PLAYBACK إلى إغلاق المستند بعد مرور 30 ثانية بدون تشغيل الصوت. في جميع الأسباب الأخرى، لا يتم ضبط حدود دائمة.

أمثلة

الحفاظ على دورة حياة المستند خارج الشاشة

يوضح المثال التالي كيفية ضمان توفُّر مستند خارج الشاشة. تستدعي الدالة setupOffscreenDocument() runtime.getContexts() للعثور على مستند حالي خارج الشاشة، أو تنشئ المستند إذا لم يكن موجودًا من قبل.

let creating; // A global promise to avoid concurrency issues
async function setupOffscreenDocument(path) {
  // Check all windows controlled by the service worker to see if one
  // of them is the offscreen document with the given path
  const offscreenUrl = chrome.runtime.getURL(path);
  const existingContexts = await chrome.runtime.getContexts({
    contextTypes: ['OFFSCREEN_DOCUMENT'],
    documentUrls: [offscreenUrl]
  });

  if (existingContexts.length > 0) {
    return;
  }

  // create offscreen document
  if (creating) {
    await creating;
  } else {
    creating = chrome.offscreen.createDocument({
      url: path,
      reasons: ['CLIPBOARD'],
      justification: 'reason for needing the document',
    });
    await creating;
    creating = null;
  }
}

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

chrome.action.onClicked.addListener(async () => {
  await setupOffscreenDocument('off_screen.html');

  // Send message to offscreen document
  chrome.runtime.sendMessage({
    type: '...',
    target: 'offscreen',
    data: '...'
  });
});

للحصول على أمثلة كاملة، يُرجى الاطّلاع على العروض التوضيحية للحافظة خارج الشاشة وoffscreen-dom على GitHub.

قبل Chrome 116: التحقُّق ممّا إذا كان هناك مستند خارج الشاشة مفتوحًا

تمت إضافة runtime.getContexts() في Chrome 116. في الإصدارات السابقة من Chrome، استخدِم clients.matchAll() للتحقّق من توفُّر مستند حالي خارج الشاشة:

async function hasOffscreenDocument() {
  if ('getContexts' in chrome.runtime) {
    const contexts = await chrome.runtime.getContexts({
      contextTypes: ['OFFSCREEN_DOCUMENT'],
      documentUrls: [OFFSCREEN_DOCUMENT_PATH]
    });
    return Boolean(contexts.length);
  } else {
    const matchedClients = await clients.matchAll();
    return await matchedClients.some(client => {
        client.url.includes(chrome.runtime.id);
    });
  }
}

الأنواع

CreateParameters

أماكن إقامة

• السبب

  سلسلة

  سلسلة يقدّمها المطوّر توضّح بالتفصيل الحاجة إلى سياق الخلفية. وكيل المستخدم _مايو_ يستخدم هذا لعرض المستخدم.

• سبب

  السبب[]

  سبب(أسباب) الإضافة هو إنشاء المستند خارج الشاشة.

• url

  سلسلة

  عنوان URL (النسبي) المطلوب تحميله في المستند

Reason

التعداد

"TESTING"
سبب مُستخدَم لأغراض الاختبار فقط

"AUDIO_PLAYBACK"
تحديد أنّ المستند خارج الشاشة مسؤول عن تشغيل الصوت

"Iframe_scriptING"
يحدد أن المستند خارج الشاشة يحتاج إلى تضمين وكتابة iframe لتعديل محتوى الإطار.

"DOM_SCRAPING"
يحدد أن المستند خارج الشاشة يجب أن يتضمن إطار iframe واستخراج نموذج العناصر في المستند (DOM_SCRAPING) لاستخراج المعلومات.

"BLOBS"
يجب تحديد أنّ المستند خارج الشاشة يجب أن يتفاعل مع كائنات الكائنات الثنائية الكبيرة (بما في ذلك URL.createObjectURL()).

"DOM_PARSER"
يجب أن يستخدم المستند الذي يظهر خارج الشاشة واجهة برمجة تطبيقات DOMParser.

"USER_MEDIA"
يجب تحديد أنّ المستند الذي يظهر خارج الشاشة يجب أن يتفاعل مع ساحات مشاركات الوسائط من وسائط المستخدم (مثل getUserMedia()).

"DISPLAY_MEDIA"
يجب تحديد أنّ المستند الذي يظهر خارج الشاشة يجب أن يتفاعل مع ساحات مشاركات الوسائط من وسائط العرض (مثل getDisplayMedia()).

"WEB_RTC"
يجب أن يستخدم المستند الذي يظهر خارج الشاشة واجهات برمجة تطبيقات WebRTC.

"CLIPBOARD"
يجب استخدام المستند الذي يظهر خارج الشاشة للتفاعل مع Clipboard API.

"LOCAL_STORAGE"
يحدد هذا الإعداد أن المستند خارج الشاشة يحتاج إلى الوصول إلى localStorage.

"WORKERS"
يحدد أن المستند خارج الشاشة يحتاج إلى إنتاج العمال.

"BATTERY_STATUS"
يحدد أن المستند خارج الشاشة يجب استخدام navigator.getBattery.

"MATCH_MEDIA"
يجب أن يستخدم المستند خارج الشاشة window.matchMedia.

"geoLOCATION"
يحدد أن المستند خارج الشاشة يجب استخدام navigator.geolocation.

الطُرق

closeDocument()

وعد

chrome.offscreen.closeDocument(
  callback?: function,
)

يؤدي هذا الإجراء إلى إغلاق المستند المفتوح حاليًا للإضافة خارج الشاشة.

المَعلمات

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

  تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

createDocument()

وعد

chrome.offscreen.createDocument(
  parameters: CreateParameters,
  callback?: function,
)

تنشئ هذه الإضافة مستندًا جديدًا خارج الشاشة.

المَعلمات

• المَعلَمات

  CreateParameters

  تمثّل هذه السمة المعلَمات التي تصف المستند خارج الشاشة المطلوب إنشاؤه.

• معاودة الاتصال

  الدالة اختيارية

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

  تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.