chrome.offscreen

Mô tả

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

Chrome 109 trở lên Video nhạc 3 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 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 DOM API 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ửa sổ mới hoặc . API runtime là API tiện ích duy nhất được hỗ trợ bởi tài liệu ngoài màn hình.

Các trang được tải dưới dạng tài liệu ngoài màn hình được xử lý theo cách khác với các loại trang tiện ích khác. Các quyền của tiện ích chuyển sang tài liệu ngoài màn hình, nhưng có giới hạn về API tiện ích truy cập. Ví dụ: vì API chrome.runtime là API duy nhất API tiện ích được tài liệu ngoài màn hình hỗ trợ, phải xử lý tin nhắn 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 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 vào 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ù gói tiện ích có thể chứa nhiều tài liệu ngoài màn hình, tiện ích đã cài đặt chỉ có thể mỗi lần mở một báo cáo. Nếu tiện ích đang chạy ở chế độ chia tách có hồ sơ ẩn danh đang hoạt động, thì hồ sơ thông thường và hồ sơ ẩn danh đều 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 một màn hình ngoài màn hình tài liệu. createDocument() cần có url của tài liệu, một lý do và một 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 phần Lý do. Đặt lý do trong khoảng thời gian việc 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 lại sau 30 giây mà không phát âm thanh. Tất cả các lý do khác không đặt giới hạn vòng đời.

Ví dụ

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

Ví dụ sau đây minh hoạ cách đảm bảo có một tài liệu ngoài màn hình. Chiến lược phát hành đĩa đơn 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 tin nhắn đế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ư được 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ảng thông tin ngoài màn hình và Các bản minh hoạ 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 trước đây của Chrome, sử dụng clients.matchAll() để kiểm tra 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

  • lý do

    string

    Chuỗi do nhà phát triển cung cấp, giải thích chi tiết hơn về sự cần thiết của bối cảnh liên quan. Tác nhân người dùng _may_ sử dụng giá trị này để hiển thị 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) cần tải trong tài liệu.

Reason

Enum

"KIỂM TRA"
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 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 iframe và quét DOM của nó để 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 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 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 quyền truy cập vào localStorage.

" NHÂN VIÊN"
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()

Lời hứa 
chrome.offscreen.closeDocument(
  callback?: function,
)

Đóng tài liệu ngoài màn hình hiện đang mở 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ề

  • Lời hứa<vô hiệu>

    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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

createDocument()

Lời hứa 
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ố

  • thông số

    CreateParameters

    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ề

  • Lời hứa<vô hiệu>

    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 cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.