chrome.tabCapture

คำอธิบาย

ใช้ chrome.tabCapture API เพื่อโต้ตอบกับสตรีมสื่อของแท็บ

สิทธิ์

tabCapture

ภาพรวม

chrome.tabCapture API ช่วยให้คุณเข้าถึง MediaStream ที่มีวิดีโอและเสียงของแท็บปัจจุบันได้ โดยจะเรียกได้ก็ต่อเมื่อผู้ใช้เรียกใช้ส่วนขยาย เช่น โดยการคลิกปุ่มดำเนินการของส่วนขยาย ซึ่งคล้ายกับลักษณะการทำงานของสิทธิ์ activeTab

การเก็บรักษาเสียงของระบบ

เมื่อได้รับ MediaStream สำหรับแท็บแล้ว ระบบจะไม่เล่นเสียงในแท็บนั้นให้ผู้ใช้ อีกต่อไป ซึ่งคล้ายกับลักษณะการทำงานของฟังก์ชัน getDisplayMedia() เมื่อ ตั้งค่าแฟล็ก suppressLocalAudioPlayback เป็น "จริง"

หากต้องการเล่นเสียงให้ผู้ใช้ต่อไป ให้ใช้โค้ดต่อไปนี้

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

ซึ่งจะสร้าง AudioContext ใหม่และเชื่อมต่อเสียงของ MediaStream ของแท็บกับปลายทางเริ่มต้น

รหัสสตรีม

การเรียก chrome.tabCapture.getMediaStreamId จะแสดงผลรหัสสตรีม หากต้องการเข้าถึง MediaStream จากรหัสในภายหลัง ให้ใช้โค้ดต่อไปนี้

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

ข้อจำกัดการใช้งาน

หลังจากเรียก getMediaStreamId() แล้ว จะมีข้อจำกัดเกี่ยวกับตำแหน่งที่ใช้ รหัสสตรีมที่แสดงผลได้ ดังนี้

  • หากระบุ consumerTabId ไว้ การเรียก getUserMedia() ในเฟรมใดก็ได้ในแท็บที่ระบุซึ่งมีต้นทางที่ปลอดภัยเดียวกันจะใช้รหัสได้
  • หากไม่ได้ระบุไว้ ตั้งแต่ Chrome 116 เป็นต้นไป รหัสจะใช้ได้ในเฟรมใดก็ได้ที่มีต้นทางที่ปลอดภัยเดียวกันในกระบวนการแสดงผลเดียวกันกับผู้เรียก ซึ่งหมายความว่ารหัสสตรีมที่ได้รับ ใน Service Worker จะใช้ในเอกสารนอกหน้าจอได้

ก่อน Chrome 116 เมื่อไม่ได้ระบุ consumerTabId รหัสสตรีมจะจำกัดไว้ที่ต้นทางที่ปลอดภัย กระบวนการแสดงผล และเฟรมการแสดงผลของผู้เรียก

ดูข้อมูลเพิ่มเติม

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีใช้ chrome.tabCapture API ได้ที่ เสียงที่บันทึกไว้และการจับภาพหน้าจอ ซึ่งแสดงวิธีใช้ tabCapture และ API ที่เกี่ยวข้องเพื่อแก้ปัญหา Use Case ทั่วไปจำนวนหนึ่ง

ประเภท

CaptureInfo

พร็อพเพอร์ตี้

  • เต็มหน้าจอ

    บูลีน

    ระบุว่าองค์ประกอบในแท็บที่กำลังจับภาพอยู่ในโหมดเต็มหน้าจอหรือไม่

  • สถานะ

    TabCaptureState

    สถานะการจับภาพใหม่ของแท็บ

  • tabId

    ตัวเลข

    รหัสของแท็บที่มีการเปลี่ยนแปลงสถานะ

CaptureOptions

พร็อพเพอร์ตี้

  • เสียง

    บูลีน ไม่บังคับ

  • audioConstraints

    MediaStreamConstraint ไม่บังคับ

  • วิดีโอ

    บูลีน ไม่บังคับ

  • videoConstraints

    MediaStreamConstraint ไม่บังคับ

GetMediaStreamOptions

Chrome 71 ขึ้นไป

พร็อพเพอร์ตี้

  • consumerTabId

    ตัวเลข ไม่บังคับ

    รหัสแท็บที่ไม่บังคับของแท็บที่จะเรียก getUserMedia() ในภายหลังเพื่อใช้สตรีม หากไม่ได้ระบุไว้ ส่วนขยายที่เรียกเท่านั้นที่จะใช้สตรีมที่ได้ เฟรมในแท็บที่ระบุซึ่งมีต้นทางที่ปลอดภัยตรงกับต้นทางของแท็บผู้ใช้เท่านั้นที่จะใช้สตรีมได้ ต้นทางของแท็บต้องเป็นต้นทางที่ปลอดภัย เช่น HTTPS

  • targetTabId

    ตัวเลข ไม่บังคับ

    รหัสแท็บที่ไม่บังคับของแท็บที่จะจับภาพ หากไม่ได้ระบุไว้ ระบบจะเลือกแท็บที่ใช้งานอยู่ปัจจุบัน เฉพาะแท็บที่ส่วนขยายได้รับสิทธิ์ activeTab เท่านั้นที่จะใช้เป็นแท็บเป้าหมายได้

MediaStreamConstraint

พร็อพเพอร์ตี้

  • บังคับ

    ออบเจ็กต์

  • ไม่บังคับ

    ออบเจ็กต์ ไม่บังคับ

TabCaptureState

ค่าแจกแจง

"รอดำเนินการ"

"ใช้งานอยู่"

"หยุดแล้ว"

"ข้อผิดพลาด"

เมธอด

capture()

เบื้องหน้าเท่านั้น 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

จับภาพพื้นที่ที่มองเห็นได้ของแท็บที่ใช้งานอยู่ปัจจุบัน การจับภาพจะเริ่มได้เฉพาะในแท็บที่ใช้งานอยู่ปัจจุบันหลังจากที่ เรียกใช้ ส่วนขยายแล้ว ซึ่งคล้ายกับวิธีที่ activeTab ทำงาน ระบบจะคงการจับภาพไว้เมื่อมีการนำทางในหน้าเว็บภายในแท็บ และจะหยุดเมื่อปิดแท็บหรือส่วนขยายปิดสตรีมสื่อ

พารามิเตอร์

  • ตัวเลือก

    CaptureOptions

    กำหนดค่าสตรีมสื่อที่แสดงผล

  • callback

    ฟังก์ชัน

    พารามิเตอร์ callback มีลักษณะดังนี้: 

    (stream: LocalMediaStream) => void

    • สตรีม

      LocalMediaStream

getCapturedTabs()

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

แสดงผลรายการแท็บที่ขอการจับภาพหรือกำลังจับภาพอยู่ นั่นคือ สถานะ != หยุดแล้วและสถานะ != ข้อผิดพลาด ซึ่งช่วยให้ส่วนขยายแจ้งให้ผู้ใช้ทราบว่ามีการจับภาพแท็บอยู่แล้วซึ่งอาจทำให้การจับภาพแท็บใหม่ไม่สำเร็จ (หรือเพื่อป้องกันไม่ให้มีการส่งคำขอซ้ำสำหรับแท็บเดียวกัน)

พารามิเตอร์

  • callback

    ฟังก์ชัน ไม่บังคับ

    พารามิเตอร์ callback มีลักษณะดังนี้: 

    (result: CaptureInfo[]) => void

การคืนสินค้า

  • Promise<CaptureInfo[]>

    Chrome 116 ขึ้นไป

    แสดงผล Promise ซึ่งจะแสดงผล CaptureInfo[] สำหรับแท็บที่จับภาพ

    ระบบรองรับสัญญาสำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

getMediaStreamId()

สัญญา Chrome 71 ขึ้นไป 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
): Promise<string>

สร้างรหัสสตรีมเพื่อจับภาพแท็บเป้าหมาย คล้ายกับเมธอด chrome.tabCapture.capture() แต่แสดงผลรหัสสตรีมสื่อแทนสตรีมสื่อไปยังแท็บผู้ใช้

พารามิเตอร์

  • ตัวเลือก

    GetMediaStreamOptions ไม่บังคับ

  • callback

    ฟังก์ชัน ไม่บังคับ

    พารามิเตอร์ callback มีลักษณะดังนี้: 

    (streamId: string) => void

    • streamId

      สตริง

การคืนสินค้า

  • Promise<string>

    Chrome 116 ขึ้นไป

    แสดงผล Promise ซึ่งจะแสดงผลลัพธ์ หากสำเร็จ ลัพธ์จะเป็นสตริงทึบแสงที่ส่งไปยัง getUserMedia() API เพื่อสร้างสตรีมสื่อที่สอดคล้องกับแท็บเป้าหมายได้ streamId ที่สร้างขึ้นจะใช้ได้เพียงครั้งเดียวและจะหมดอายุหลังจากผ่านไป 2-3 วินาทีหากไม่ได้ใช้

    ระบบรองรับสัญญาสำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

กิจกรรม

onStatusChanged

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

กิจกรรมที่เริ่มทำงานเมื่อสถานะการจับภาพของแท็บมีการเปลี่ยนแปลง ซึ่งช่วยให้ผู้เขียนส่วนขยายติดตามสถานะการจับภาพของแท็บเพื่อให้องค์ประกอบ UI เช่น การทำงานของหน้าเว็บซิงค์กัน

พารามิเตอร์

  • callback

    ฟังก์ชัน

    พารามิเตอร์ callback มีลักษณะดังนี้: 

    (info: CaptureInfo) => void