chrome.offscreen

คำอธิบาย

สิทธิ์

หากต้องการใช้ API นอกหน้าจอ ให้ประกาศสิทธิ์ "offscreen" ในไฟล์ Manifest ของส่วนขยาย เช่น

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

ความพร้อมใช้งาน

แนวคิดและการใช้งาน

Service Worker ไม่มีสิทธิ์เข้าถึง DOM และเว็บไซต์จำนวนมากมีนโยบายความปลอดภัยของเนื้อหาที่ จำกัดฟังก์ชันการทำงานของสคริปต์เนื้อหา Offscreen API อนุญาตให้ส่วนขยายใช้ DOM API ในเอกสารที่ซ่อนอยู่โดยไม่รบกวนประสบการณ์ของผู้ใช้ด้วยการเปิดหน้าต่างใหม่หรือ runtime API เป็น API ส่วนขยายเพียงรายการเดียว รองรับโดยเอกสารภายนอกหน้าจอ

หน้าที่โหลดเป็นเอกสารนอกหน้าจอจะได้รับการจัดการแตกต่างจากหน้าส่วนขยายประเภทอื่นๆ สิทธิ์ของส่วนขยายจะมีผลกับเอกสารนอกหน้าจอ แต่จะมีขีดจำกัดของ API ส่วนขยาย สิทธิ์การเข้าถึง ตัวอย่างเช่น เนื่องจาก chrome.runtime API เป็นเพียง API ส่วนขยายที่รองรับโดยเอกสารนอกหน้าจอ ต้องมีการจัดการการรับส่งข้อความ โดยใช้สมาชิกของ API นั้น

ต่อไปนี้เป็นวิธีอื่นๆ ที่เอกสารนอกหน้าจอทำงานแตกต่างจากหน้าปกติ

• URL ของเอกสารนอกหน้าจอต้องเป็นไฟล์ HTML แบบคงที่ที่รวมเข้ากับส่วนขยาย
• โฟกัสเอกสารที่ปิดหน้าจอไม่ได้
• เอกสารนอกหน้าจอเป็นอินสแตนซ์ของ window แต่ค่าของพร็อพเพอร์ตี้ opener จะเป็น null เสมอ
• แม้ว่าแพ็กเกจส่วนขยายจะมีเอกสารนอกหน้าจอได้หลายรายการ แต่ส่วนขยายที่ติดตั้งจะทำได้เพียง เปิดทีละรายการ หากส่วนขยายทำงานอยู่ ในโหมดแยกที่มีโปรไฟล์ที่ไม่ระบุตัวตนที่ใช้งานอยู่ โปรไฟล์ปกติและโปรไฟล์ที่ไม่ระบุตัวตนจะสามารถ มีเอกสารนอกหน้าจอ 1 รายการ

ใช้ 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);
    });
  }
}

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

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