คำอธิบาย
ใช้ offscreen
API เพื่อสร้างและจัดการเอกสารนอกหน้าจอ
สิทธิ์
offscreen
หากต้องการใช้ API นอกหน้าจอ ให้ประกาศสิทธิ์ "offscreen"
ในไฟล์ Manifest ของส่วนขยาย เช่น
{
"name": "My extension",
...
"permissions": [
"offscreen"
],
...
}
ความพร้อมใช้งาน
แนวคิดและการใช้งาน
โปรแกรมทำงานของบริการไม่มีสิทธิ์เข้าถึง 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,
)
สร้างเอกสารใหม่นอกหน้าจอสำหรับส่วนขยาย
พารามิเตอร์
-
พารามิเตอร์
พารามิเตอร์ที่อธิบายเอกสารนอกหน้าจอที่จะสร้าง
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
Promise<void>
Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ