chrome.offscreen

คำอธิบาย

ใช้ offscreen API เพื่อสร้างและจัดการเอกสารนอกหน้าจอ

สิทธิ์

offscreen

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

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

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

Chrome 109 ขึ้นไป MV3 ขึ้นไป

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

โปรแกรมทำงานของบริการไม่มีสิทธิ์เข้าถึง DOM และเว็บไซต์จำนวนมากมีนโยบายรักษาความปลอดภัยเนื้อหาที่จำกัดฟังก์ชันการทำงานของสคริปต์เนื้อหา 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 await matchedClients.some(client => {
        client.url.includes(chrome.runtime.id);
    });
  }
}

ประเภท

CreateParameters

พร็อพเพอร์ตี้

• การให้เหตุผล

  string

  สตริงที่นักพัฒนาแอประบุไว้ซึ่งอธิบายรายละเอียดเพิ่มเติมเกี่ยวกับความต้องการบริบทในเบื้องหลัง User Agent _may_ จะใช้ข้อมูลนี้ในการแสดงผลต่อผู้ใช้

• เหตุผล

  เหตุผล[]

  เหตุผลที่ส่วนขยายคือการสร้างเอกสารนอกหน้าจอ

• url

  string

  URL (สัมพัทธ์) ที่จะโหลดในเอกสาร

Reason

ค่าแจกแจง

"การทดสอบ"
เหตุผลที่ใช้สำหรับการทดสอบเท่านั้น

"AUDIO_PLAYBACK"
ระบุว่าเอกสารนอกหน้าจอมีหน้าที่เล่นเสียง

"IFRAME_scriptING"
ระบุว่าเอกสารนอกหน้าจอต้องฝังและเขียนสคริปต์ iframe เพื่อแก้ไขเนื้อหาของ iframe

"DOM_SCRAPING"
ระบุว่าเอกสารนอกหน้าจอต้องฝัง iframe และคัดลอก DOM เพื่อดึงข้อมูล

"BLOB"
ระบุว่าเอกสารนอกหน้าจอจะต้องโต้ตอบกับออบเจ็กต์ Blob (รวมถึง URL.createObjectURL())

"DOM_PARSER"
ระบุว่าเอกสารนอกหน้าจอต้องใช้ DOMParser API

"USER_MEDIA"
ระบุว่าเอกสารนอกหน้าจอจะต้องโต้ตอบกับสตรีมสื่อจากสื่อของผู้ใช้ (เช่น getUserMedia())

"DISPLAY_MEDIA"
ระบุว่าเอกสารนอกหน้าจอจะต้องโต้ตอบกับสตรีมสื่อจากสื่อดิสเพลย์ (เช่น getDisplayMedia())

"WEB_RTC"
ระบุว่าเอกสารนอกหน้าจอต้องใช้ WebRTC API

"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

  ฟังก์ชัน ไม่บังคับ

  พารามิเตอร์ callback มีลักษณะดังนี้

  ()=>void

การคืนสินค้า

• Promise<void>

  Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

createDocument()

สัญญา

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

สร้างเอกสารใหม่นอกหน้าจอสำหรับส่วนขยาย

พารามิเตอร์

• พารามิเตอร์

  CreateParameters

  พารามิเตอร์ที่อธิบายเอกสารนอกหน้าจอที่จะสร้าง

• Callback

  ฟังก์ชัน ไม่บังคับ

  พารามิเตอร์ callback มีลักษณะดังนี้

  ()=>void

การคืนสินค้า

• Promise<void>

  Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ