chrome.tabCapture

refresh date: 2026-09-25 robots: noindex

คำอธิบาย

ใช้ 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 ที่เกี่ยวข้องเพื่อแก้ปัญหากรณีการใช้งานที่พบบ่อยหลายกรณี

ประเภท

CaptureInfo

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

  • เต็มหน้าจอ

    บูลีน

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

  • สถานะ

    TabCaptureState

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

  • tabId

    ตัวเลข

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

CaptureOptions

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

  • เสียง

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

  • audioConstraints

    MediaStreamConstraint ไม่บังคับ

  • วิดีโอ

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

  • videoConstraints

    MediaStreamConstraint ไม่บังคับ

GetMediaStreamOptions

Chrome 71 ขึ้นไป

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

  • consumerTabId

    number ไม่บังคับ

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

  • targetTabId

    number ไม่บังคับ

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

MediaStreamConstraint

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

  • จำเป็น

    ออบเจ็กต์

  • ไม่บังคับ

    object ไม่บังคับ

TabCaptureState

ค่าแจกแจง

"pending"

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

"หยุด"

"error"

เมธอด

capture()

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

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

พารามิเตอร์

  • ตัวเลือก

    CaptureOptions

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

  • callback

    ฟังก์ชัน

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

    (stream: LocalMediaStream) => void

    • สตรีม

      LocalMediaStream

getCapturedTabs()

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

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

พารามิเตอร์

  • callback

    function ไม่บังคับ

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

    (result: CaptureInfo[]) => void

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

  • Promise<CaptureInfo[]>

    Chrome 116 ขึ้นไป

    แสดงผล Promise ซึ่งจะได้รับการแก้ไขด้วย CaptureInfo[] สำหรับแท็บที่บันทึกไว้

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

getMediaStreamId()

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

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

พารามิเตอร์

  • ตัวเลือก

    GetMediaStreamOptions ไม่บังคับ

  • callback

    function ไม่บังคับ

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

    (streamId: string) => void

    • streamId

      สตริง

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

  • Promise<string>

    Chrome 116 ขึ้นไป

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

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

กิจกรรม

onStatusChanged

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (info: CaptureInfo) => void