Nội dung mô tả
Sử dụng API offscreen
để tạo và quản lý tài liệu ngoài màn hình.
Quyền
offscreen
Để sử dụng API Ngoài màn hình, hãy khai báo quyền "offscreen"
trong tệp kê khai tiện ích. Ví dụ:
{
"name": "My extension",
...
"permissions": [
"offscreen"
],
...
}
Phạm vi cung cấp
Khái niệm và cách sử dụng
Trình chạy dịch vụ không có quyền truy cập vào DOM và nhiều trang web có chính sách bảo mật nội dung hạn chế chức năng của tập lệnh nội dung. API ngoài màn hình cho phép tiện ích sử dụng các API DOM trong tài liệu ẩn mà không làm gián đoạn trải nghiệm người dùng bằng cách mở các thẻ hoặc cửa sổ mới. API runtime
là API tiện ích duy nhất được các tài liệu ngoài màn hình hỗ trợ.
Các trang được tải dưới dạng tài liệu ngoài màn hình được xử lý khác với các loại trang tiện ích khác.
Các quyền của tiện ích sẽ chuyển sang các tài liệu ngoài màn hình, nhưng có giới hạn về quyền truy cập vào API tiện ích. Ví dụ: vì API chrome.runtime
là API tiện ích duy nhất được các tài liệu ngoài màn hình hỗ trợ, nên bạn phải xử lý thông báo bằng các thành phần của API đó.
Sau đây là những điểm khác biệt về cách hoạt động của tài liệu ngoài màn hình so với trang thông thường:
- URL của tài liệu ngoài màn hình phải là một tệp HTML tĩnh đi kèm với phần mở rộng.
- Không thể lấy tiêu điểm tài liệu ngoài màn hình.
- Tài liệu ngoài màn hình là một thực thể của
window
, nhưng giá trị của thuộc tínhopener
của tài liệu đó luôn lànull
. - Mặc dù gói tiện ích có thể chứa nhiều tài liệu ngoài màn hình, nhưng mỗi tiện ích đã cài đặt chỉ có thể mở một tiện ích. Nếu tiện ích đang chạy ở chế độ chia tách có hồ sơ ẩn danh đang hoạt động, thì mỗi hồ sơ thông thường và hồ sơ ẩn danh có thể có một tài liệu ngoài màn hình.
Sử dụng chrome.offscreen.createDocument()
và chrome.offscreen.closeDocument()
để tạo và đóng tài liệu ngoài màn hình. createDocument()
yêu cầu url
của tài liệu, lý do và lý do:
chrome.offscreen.createDocument({
url: 'off_screen.html',
reasons: ['CLIPBOARD'],
justification: 'reason for needing the document',
});
Lý do
Để biết danh sách các lý do hợp lệ, hãy xem mục Lý do. Lý do được đặt ra trong quá trình tạo tài liệu để xác định thời gian tồn tại của tài liệu. Lý do AUDIO_PLAYBACK
khiến tài liệu đóng sau 30 giây mà không phát âm thanh. Tất cả các lý do khác không đặt ra giới hạn toàn thời gian.
Ví dụ
Duy trì vòng đời của tài liệu ngoài màn hình
Ví dụ sau đây cho thấy cách đảm bảo rằng có tài liệu ngoài màn hình. Hàm setupOffscreenDocument()
gọi runtime.getContexts()
để tìm tài liệu hiện có ngoài màn hình hoặc tạo tài liệu nếu tài liệu đó chưa tồn tại.
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;
}
}
Trước khi gửi thông báo đến tài liệu ngoài màn hình, hãy gọi setupOffscreenDocument()
để đảm bảo tài liệu tồn tại, như minh hoạ trong ví dụ sau.
chrome.action.onClicked.addListener(async () => {
await setupOffscreenDocument('off_screen.html');
// Send message to offscreen document
chrome.runtime.sendMessage({
type: '...',
target: 'offscreen',
data: '...'
});
});
Để biết ví dụ đầy đủ, hãy xem bản minh hoạ offscreen-clipboard và offscreen-dom trên GitHub.
Trước Chrome 116: kiểm tra xem tài liệu ngoài màn hình có đang mở hay không
runtime.getContexts()
đã được thêm vào Chrome 116. Trong các phiên bản Chrome cũ hơn, hãy sử dụng clients.matchAll()
để kiểm tra một tài liệu hiện có ngoài màn hình:
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);
});
}
}
Loại
CreateParameters
Thuộc tính
-
căn đều
string
Một chuỗi do nhà phát triển cung cấp để giải thích chi tiết hơn về nhu cầu của ngữ cảnh nền. Tác nhân người dùng _may_ sẽ hiển thị thông tin này cho người dùng.
-
lý do khác
Lý do[]
(Các) lý do khiến tiện ích đang tạo tài liệu ngoài màn hình.
-
url
string
URL (tương đối) sẽ tải trong tài liệu.
Reason
Liệt kê
"THỬ NGHIỆM"
Lý do chỉ dùng cho mục đích thử nghiệm.
"AUDIO_PLAYBACK"
Chỉ định rằng tài liệu ngoài màn hình chịu trách nhiệm phát âm thanh.
"IFRAME_SCRIPTING"
Chỉ định rằng tài liệu ngoài màn hình cần nhúng và viết tập lệnh cho một iframe để sửa đổi nội dung của iframe đó.
"DOM_ buộc bệnh viện"
Chỉ định rằng tài liệu ngoài màn hình cần nhúng iframe và trích xuất DOM của nội dung để trích xuất thông tin.
"BLOBS"
Chỉ định rằng tài liệu ngoài màn hình cần tương tác với đối tượng Blob (bao gồm cả URL.createObjectURL()
).
"DOM_PARSER"
Chỉ định rằng tài liệu ngoài màn hình cần sử dụng API DOMParser.
"USER_MEDIA"
Chỉ định rằng tài liệu ngoài màn hình cần tương tác với luồng nội dung nghe nhìn từ nội dung nghe nhìn của người dùng (ví dụ: getUserMedia()
).
"DISPLAY_MEDIA"
Chỉ định rằng tài liệu ngoài màn hình cần tương tác với các luồng nội dung nghe nhìn từ nội dung nghe nhìn hiển thị (ví dụ: getDisplayMedia()
).
"WEB_RTC"
Chỉ định rằng tài liệu ngoài màn hình cần sử dụng API WebRTC.
"CLIPboard"
Chỉ định rằng tài liệu ngoài màn hình cần tương tác với Clipboard API.
"LOCAL_STORAGE"
Chỉ định rằng tài liệu ngoài màn hình cần quyền truy cập vào localStorage.
"WORKERS"
Chỉ định rằng tài liệu ngoài màn hình cần để tạo worker.
"BATTERY_STATUS"
Chỉ định rằng tài liệu ngoài màn hình cần sử dụng navigator.getBattery.
"MATCH_MEDIA"
Chỉ định rằng tài liệu ngoài màn hình cần sử dụng window.matchMedia.
"GEOLOCATION"
Chỉ định rằng tài liệu ngoài màn hình cần sử dụng navigator.geolocation.
Phương thức
closeDocument()
chrome.offscreen.closeDocument(
callback?: function,
)
Đóng tài liệu hiện đang mở ngoài màn hình cho tiện ích.
Tham số
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Promise<void>
Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
createDocument()
chrome.offscreen.createDocument(
parameters: CreateParameters,
callback?: function,
)
Tạo tài liệu mới ngoài màn hình cho tiện ích.
Tham số
-
tham số
Các tham số mô tả tài liệu ngoài màn hình cần tạo.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Promise<void>
Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.