chrome.tabCapture

refresh date: 2026-09-25 robots: noindex

คำอธิบาย

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

สิทธิ์

tabCapture

ภาพรวม

API chrome.tabCapture ช่วยให้คุณเข้าถึง 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()

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

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

พารามิเตอร์

  • callback

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

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

    (result: CaptureInfo[]) => void

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

  • Promise<CaptureInfo[]>

    Chrome 116 ขึ้นไป

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

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

getMediaStreamId()

Promise 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 ที่สร้างขึ้นจะใช้ได้เพียงครั้งเดียวและจะหมดอายุหลังจากผ่านไปไม่กี่วินาทีหากไม่ได้ใช้

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

กิจกรรม

onStatusChanged

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (info: CaptureInfo) => void