chrome.offscreen

Mô tả

Quyền

Để sử dụng Offscreen API, 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

Các worker 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 giới hạn chức năng của tập lệnh nội dung. Offscreen API cho phép tiện ích sử dụng DOM API trong một 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 cửa sổ hoặc thẻ mới. API runtime là API tiện ích duy nhất đượ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ẽ được chuyển sang 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 tài liệu ngoài màn hình hỗ trợ, nên bạn phải xử lý việc gửi tin nhắn bằng cách sử dụng các thành phần của API đó.

Sau đây là những cách khác mà tài liệu ngoài màn hình hoạt động khác với các trang thông thường:

• URL của tài liệu hiển thị bên ngoài màn hình phải là một tệp HTML tĩnh đi kèm với tiện ích.
• Không thể lấy tiêu điểm cho các 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ính opener luôn là null.
• Mặc dù một gói tiện ích có thể chứa nhiều tài liệu ngoài màn hình, nhưng một tiện ích đã cài đặt chỉ có thể có một tài liệu đang mở tại một thời điểm. Nếu tiện ích đang chạy ở chế độ chia đôi với một hồ sơ ẩn danh đang hoạt động, thì mỗi hồ sơ bình thường và hồ sơ ẩn danh đều có thể có một tài liệu ngoài màn hình.

Dùng chrome.offscreen.createDocument() và chrome.offscreen.closeDocument() để tạo và đóng một 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 chính đáng:

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 phần Lý do. Lý do được đặt 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 đặt 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 đều không đặt giới hạn trọn đời.

Ví dụ

Duy trì vòng đời của một tài liệu ngoài màn hình

Ví dụ sau đây minh hoạ cách đảm bảo rằng một tài liệu ngoài màn hình tồn tại. Hàm setupOffscreenDocument() gọi runtime.getContexts() để tìm một tài liệu ngoài màn hình hiện có 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 một 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: '...'
  });
});

Để xem các 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 có tài liệu nào ở ngoài màn hình đang mở hay không

runtime.getContexts() đã được thêm vào Chrome 116. Trong các phiên bản Chrome cũ, hãy dùng clients.matchAll() để kiểm tra xem có tài liệu nào hiện không hiển thị trên màn hình hay không:

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>