chrome.offscreen

คำอธิบาย

สิทธิ์

หากต้องการใช้ Offscreen API ให้ประกาศสิทธิ์ "offscreen" ใน manifest ของส่วนขยาย เช่น

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

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

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

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

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

เอกสารนอกหน้าจอมีลักษณะการทำงานที่แตกต่างจากหน้าเว็บปกติในลักษณะอื่นๆ ดังนี้

• URL ของเอกสารนอกหน้าจอต้องเป็นไฟล์ HTML แบบคงที่ที่รวมอยู่ในส่วนขยาย
• ระบบจะโฟกัสเอกสารที่อยู่นอกหน้าจอไม่ได้
• เอกสารนอกหน้าจอคืออินสแตนซ์ของ window แต่ค่าของพร็อพเพอร์ตี้ opener จะเป็น null เสมอ
• แม้ว่าแพ็กเกจส่วนขยายจะมีเอกสารนอกหน้าจอได้หลายรายการ แต่ส่วนขยายที่ติดตั้งแล้วจะเปิดได้ครั้งละ 1 รายการเท่านั้น หากส่วนขยายทำงานในโหมดแยกกับโปรไฟล์ไม่ระบุตัวตนที่ใช้งานอยู่ โปรไฟล์ปกติและโปรไฟล์ไม่ระบุตัวตนแต่ละโปรไฟล์จะมีเอกสารนอกหน้าจอได้ 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-clipboard และ 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 matchedClients.some(client => {       return client.url.includes(chrome.runtime.id);     });   } } 

chrome.offscreen.closeDocument(): Promise<void>

chrome.offscreen.createDocument(
  parameters: CreateParameters,
): Promise<void>