browser.offscreen

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 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

Chrome 109 trở lên browser.* kể từ Chrome 148 MV3 trở lên

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 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. API Offscreen 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ửa sổ hoặc thẻ mới. runtime API 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 API tiện ích. Ví dụ: vì API browser.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ý thông báo bằng các thành viên của API đó.

Sau đây là những điểm khác biệt khác giữa tài liệu ngoài màn hình và 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 tiện ích.
  • Không thể lấy tiêu điểm cho 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ể mở một tài liệu tại một thời điểm. Nếu tiện ích đang chạy ở chế độ phân tách với một 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 browser.offscreen.createDocument() và browser.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 chính đáng:

browser.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 về thời gian sử dụng.

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 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 = browser.runtime.getURL(path);
  const existingContexts = await browser.runtime.getContexts({
    contextTypes: ['OFFSCREEN_DOCUMENT'],
    documentUrls: [offscreenUrl]
  });

  if (existingContexts.length > 0) {
    return;
  }

  // create offscreen document
  if (creating) {
    await creating;
  } else {
    creating = browser.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.

browser.action.onClicked.addListener(async () => {
  await setupOffscreenDocument('off_screen.html');

  // Send message to offscreen document
  browser.runtime.sendMessage({
    type: '...',
    target: 'offscreen',
    data: '...'
  });
});

Để xem ví dụ hoàn chỉnh, 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ãy dùng clients.matchAll() để kiểm tra tài liệu ngoài màn hình hiện có:

async function hasOffscreenDocument() {
  if ('getContexts' in browser.runtime) {
    const contexts = await browser.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(browser.runtime.id);
    });
  }
}

Loại

CreateParameters

Thuộc tính

  • lý do

    chuỗi

    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 đối với bối cảnh nền. Tác nhân người dùng _có thể_ sử dụng thông tin này để hiển thị cho người dùng.

  • lý do khác

    Lý do[]

    (Các) lý do tiện ích tạo tài liệu ngoài màn hình.

  • url

    chuỗi

    URL (tương đối) để tải trong tài liệu.

Reason

Enum

"TESTING"
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_SCRAPING"
Chỉ định rằng tài liệu ngoài màn hình cần nhúng một iframe và trích xuất DOM của iframe đó để 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 các đố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 DOMParser API.

"USER_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 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 có 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()

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

Đóng tài liệu ngoài màn hình hiện đang mở cho tiện ích.

Giá trị trả về

  • Promise<void>

    Lời hứa sẽ giải quyết khi tài liệu ngoài màn hình đã được đóng.

createDocument()

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

Tạo một tài liệu ngoài màn hình mới cho tiện ích.

Thông số

  • tham số

    CreateParameters

    Các tham số mô tả tài liệu ngoài màn hình cần tạo.

Giá trị trả về

  • Promise<void>

    Lời hứa sẽ được thực hiện khi tài liệu ngoài màn hình được tạo và đã hoàn tất quá trình tải trang ban đầu.

hasDocument()

Chrome 150 trở lên 
browser.offscreen.hasDocument(): Promise<boolean>

Xác định xem tiện ích có tài liệu đang hoạt động hay không.

Giá trị trả về

  • Promise<boolean>

    Lời hứa sẽ giải quyết bằng kết quả cho biết tiện ích có tài liệu ngoài màn hình đang hoạt động hay không.