chrome.tabCapture

refresh date: 2026-09-25 robots: noindex

Mô tả

Sử dụng API chrome.tabCapture để tương tác với luồng nội dung nghe nhìn của thẻ.

Quyền

tabCapture

Tổng quan

API chrome.tabCapture cho phép bạn truy cập vào MediaStream chứa video và âm thanh của thẻ hiện tại. Bạn chỉ có thể gọi API này sau khi người dùng gọi một tiện ích, chẳng hạn như bằng cách nhấp vào nút hành động của tiện ích. Điều này tương tự như hành vi của quyền activeTab.

Giữ nguyên âm thanh hệ thống

Khi nhận được MediaStream cho một thẻ, âm thanh trong thẻ đó sẽ không còn phát cho người dùng nữa. Điều này tương tự như hành vi của hàm getDisplayMedia() khi cờ suppressLocalAudioPlayback được đặt thành true.

Để tiếp tục phát âm thanh cho người dùng, hãy sử dụng các cách sau:

const output = new AudioContext();
const source = output.createMediaStreamSource(stream);
source.connect(output.destination);

Thao tác này sẽ tạo một AudioContext mới và kết nối âm thanh của MediaStream của thẻ với đích đến mặc định.

Mã luồng

Khi gọi chrome.tabCapture.getMediaStreamId, bạn sẽ nhận được một mã nhận dạng luồng. Để sau này truy cập vào MediaStream từ mã nhận dạng, hãy sử dụng đoạn mã sau:

navigator.mediaDevices.getUserMedia({
  audio: {
    mandatory: {
      chromeMediaSource: "tab",
      chromeMediaSourceId: id,
    },
  },
  video: {
    mandatory: {
      chromeMediaSource: "tab",
      chromeMediaSourceId: id,
    },
  },
});

Giới hạn mức sử dụng

Sau khi gọi getMediaStreamId(), sẽ có các quy định hạn chế về nơi có thể sử dụng mã nhận dạng luồng được trả về:

  • Nếu bạn chỉ định consumerTabId, thì lệnh gọi getUserMedia() có thể sử dụng mã nhận dạng này trong bất kỳ khung nào trong thẻ đã cho có cùng nguồn gốc bảo mật.
  • Khi bạn không chỉ định, kể từ Chrome 116, mã nhận dạng có thể được dùng trong bất kỳ khung nào có cùng nguồn gốc bảo mật trong cùng một quy trình kết xuất với phương thức gọi. Điều này có nghĩa là bạn có thể sử dụng mã nhận dạng luồng thu được trong một trình chạy dịch vụ trong tài liệu ngoài màn hình.

Trước phiên bản Chrome 116, khi không chỉ định consumerTabId, mã nhận dạng luồng sẽ bị hạn chế đối với cả nguồn gốc bảo mật, quy trình kết xuất và khung kết xuất của phương thức gọi.

Tìm hiểu thêm

Để tìm hiểu thêm về cách sử dụng API chrome.tabCapture, hãy xem bài viết Ghi âm và chụp ảnh màn hình. Phần này minh hoạ cách sử dụng tabCapture và các API liên quan để giải quyết một số trường hợp sử dụng phổ biến.

Loại

CaptureInfo

Thuộc tính

  • toàn màn hình

    boolean

    Liệu một phần tử trong thẻ đang được chụp có ở chế độ toàn màn hình hay không.

  • trạng thái

    TabCaptureState

    Trạng thái chụp mới của thẻ.

  • tabId

    số

    Mã của thẻ có trạng thái đã thay đổi.

CaptureOptions

Thuộc tính

GetMediaStreamOptions

Chrome 71 trở lên

Thuộc tính

  • consumerTabId

    number không bắt buộc

    Mã thẻ không bắt buộc của thẻ mà sau này sẽ gọi getUserMedia() để sử dụng luồng. Nếu không được chỉ định, thì luồng kết quả chỉ có thể được tiện ích gọi sử dụng. Chỉ những khung hình trong thẻ đã cho có nguồn gốc bảo mật khớp với nguồn gốc của thẻ người dùng mới có thể sử dụng luồng này. Nguồn gốc của thẻ phải là nguồn gốc an toàn, ví dụ: HTTPS.

  • targetTabId

    number không bắt buộc

    Mã thẻ không bắt buộc của thẻ sẽ được chụp. Nếu không được chỉ định, thì thẻ đang hoạt động sẽ được chọn. Chỉ những thẻ mà tiện ích đã được cấp quyền activeTab mới có thể được dùng làm thẻ mục tiêu.

MediaStreamConstraint

Thuộc tính

  • bắt buộc

    đối tượng

  • tùy chọn

    object không bắt buộc

TabCaptureState

Enum

"pending"

"đang hoạt động"

"stopped"

"error"

Phương thức

capture()

Chỉ nền trước 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

Chụp vùng hiển thị của thẻ đang hoạt động. Bạn chỉ có thể bắt đầu chụp trên thẻ đang hoạt động sau khi tiện ích được gọi, tương tự như cách hoạt động của activeTab. Quá trình ghi lại được duy trì trong suốt quá trình điều hướng trang trong thẻ và dừng khi thẻ bị đóng hoặc luồng nội dung nghe nhìn bị tiện ích đóng.

Thông số

  • tùy chọn

    CaptureOptions

    Định cấu hình luồng nội dung nghe nhìn được trả về.

  • callback

    hàm

    Tham số callback có dạng như sau: 

    (stream: LocalMediaStream) => void

    • luồng

      LocalMediaStream

getCapturedTabs()

Promise 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
): Promise<CaptureInfo[]>

Trả về danh sách các thẻ đã yêu cầu chụp hoặc đang được chụp, tức là trạng thái != đã dừng và trạng thái != lỗi. Điều này cho phép các tiện ích thông báo cho người dùng rằng có một bản chụp thẻ hiện có sẽ ngăn việc chụp thẻ mới thành công (hoặc để ngăn các yêu cầu thừa cho cùng một thẻ).

Thông số

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    (result: CaptureInfo[]) => void

Giá trị trả về

  • Promise<CaptureInfo[]>

    Chrome 116 trở lên

    Trả về một Lời hứa sẽ phân giải bằng CaptureInfo[] cho các thẻ đã chụp.

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

getMediaStreamId()

Promise Chrome 71 trở lên 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
): Promise<string>

Tạo mã luồng để ghi lại thẻ mục tiêu. Tương tự như phương thức chrome.tabCapture.capture(), nhưng trả về mã nhận dạng luồng nội dung nghe nhìn thay vì luồng nội dung nghe nhìn cho thẻ người dùng.

Thông số

  • tùy chọn

    GetMediaStreamOptions không bắt buộc

  • callback

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    (streamId: string) => void

    • streamId

      chuỗi

Giá trị trả về

  • <string> hứa hẹn

    Chrome 116 trở lên

    Trả về một Promise phân giải bằng kết quả. Nếu thành công, kết quả sẽ là một chuỗi mờ có thể được truyền đến API getUserMedia() để tạo luồng nội dung nghe nhìn tương ứng với thẻ mục tiêu. streamId đã tạo chỉ có thể được sử dụng một lần và sẽ hết hạn sau vài giây nếu không được sử dụng.

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

Sự kiện

onStatusChanged

chrome.tabCapture.onStatusChanged.addListener(
  callback: function,
)

Sự kiện được kích hoạt khi trạng thái chụp của một thẻ thay đổi. Điều này cho phép tác giả tiện ích theo dõi trạng thái chụp của các thẻ để đồng bộ hoá các phần tử trên giao diện người dùng như thao tác trên trang.

Thông số