เลื่อนและซูมแท็บที่จับภาพ

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

François Beaufort

Elad Alon

การแชร์แท็บ หน้าต่าง และหน้าจอบนแพลตฟอร์มเว็บทำได้แล้วด้วย Screen Capture API เมื่อเว็บแอปเรียก getDisplayMedia() ทาง Chrome จะแจ้งให้ผู้ใช้แชร์แท็บ หน้าต่าง หรือหน้าจอกับเว็บแอปเป็นวิดีโอ MediaStreamTrack

เว็บแอปหลายแอปที่ใช้ getDisplayMedia() จะแสดงตัวอย่างวิดีโอของพื้นผิวที่จับภาพให้ผู้ใช้ดู ตัวอย่างเช่น แอปการประชุมทางวิดีโอมักจะสตรีมวิดีโอนี้ไปยังผู้ใช้ระยะไกลไปพร้อมกับแสดงผลไปยัง HTMLVideoElement ในพื้นที่ด้วย เพื่อให้ผู้ใช้ในพื้นที่เห็นตัวอย่างของสิ่งที่กำลังแชร์อยู่ตลอดเวลา

เอกสารประกอบนี้จะแนะนำ Captured Surface Control API ใหม่ใน Chrome ซึ่งช่วยให้เว็บแอปเลื่อนแท็บที่บันทึกไว้ รวมถึงอ่านและเขียนระดับการซูมของแท็บที่บันทึกไว้ได้

เหตุผลที่ควรใช้การควบคุมพื้นผิวที่จับภาพ

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

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

Captured Surface Control API ช่วยแก้ปัญหาเหล่านี้

ฉันจะใช้การควบคุมพื้นผิวที่บันทึกไว้ได้อย่างไร

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

จับภาพแท็บเบราว์เซอร์

เริ่มต้นด้วยการแจ้งให้ผู้ใช้เลือกพื้นผิวที่จะแชร์โดยใช้ getDisplayMedia() และในระหว่างนี้ ให้เชื่อมโยงออบเจ็กต์ CaptureController กับเซสชันการจับภาพ เราจะใช้วัตถุดังกล่าวเพื่อควบคุมพื้นผิวที่จับภาพในเร็วๆ นี้

const controller = new CaptureController();
const stream = await navigator.mediaDevices.getDisplayMedia({ controller });

ต่อไป ให้สร้างตัวอย่างในเครื่องของพื้นผิวที่จับภาพในรูปแบบองค์ประกอบ <video> ดังนี้

const previewTile = document.querySelector('video');
previewTile.srcObject = stream;

หากผู้ใช้เลือกแชร์หน้าต่างหรือหน้าจอ การดำเนินการดังกล่าวจะยังไม่อยู่ในขอบเขตในตอนนี้ แต่หากเลือกแชร์แท็บ เราอาจดำเนินการต่อ

const [track] = stream.getVideoTracks();

if (track.getSettings().displaySurface !== 'browser') {
  // Bail out early if the user didn't pick a tab.
  return;
}

ข้อความแจ้งสิทธิ์

การเรียกใช้ forwardWheel(), increaseZoomLevel(), decreaseZoomLevel() หรือ resetZoomLevel() ครั้งแรกบนออบเจ็กต์ CaptureController หนึ่งๆ จะแสดงข้อความแจ้งสิทธิ์ หากผู้ใช้ให้สิทธิ์ ระบบจะอนุญาตให้เรียกใช้เมธอดเหล่านี้ต่อไป

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

เลื่อน

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

สมมติว่าแอปการจับภาพใช้องค์ประกอบ <video> ชื่อ "previewTile" โค้ดต่อไปนี้แสดงวิธีส่งต่อเหตุการณ์ล้อเลื่อนไปยังแท็บที่บันทึกไว้

const previewTile = document.querySelector('video');
try {
  // Relay the user's action to the captured tab.
  await controller.forwardWheel(previewTile);
} catch (error) {
  // Inspect the error.
  // ...
}

เมธอด forwardWheel() จะรับอินพุตรายการเดียวซึ่งอาจเป็นอย่างใดอย่างหนึ่งต่อไปนี้

• องค์ประกอบ HTML ที่ระบบจะส่งต่อเหตุการณ์การเลื่อนล้อไปยังแท็บที่บันทึกไว้
• null ซึ่งหมายความว่าให้หยุดการส่งต่อ

การเรียกใช้ forwardWheel() ที่ประสบความสําเร็จจะลบล้างการเรียกใช้ก่อนหน้านี้

Promise ที่ forwardWheel() แสดงผลจะปฏิเสธได้ในกรณีต่อไปนี้

• หากเซสชันการบันทึกยังไม่เริ่มหรือหยุดไปแล้ว
• หากผู้ใช้ไม่ได้ให้สิทธิ์ที่เกี่ยวข้อง

ซูม

การโต้ตอบกับระดับการซูมของแท็บที่บันทึกไว้ทำได้ผ่านแพลตฟอร์ม CaptureController API ต่อไปนี้

getSupportedZoomLevels()

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

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

controller.getSupportedZoomLevels() อาจเรียกใช้หากเป็นไปตามเงื่อนไขต่อไปนี้

• controller เชื่อมโยงกับการบันทึกที่ใช้งานอยู่
• การจับภาพเป็นแท็บ

ไม่เช่นนั้นระบบจะแสดงข้อผิดพลาด

ไม่จําเป็นต้องขอสิทธิ์ "captured-surface-control" เพื่อเรียกใช้เมธอดนี้

zoomLevel

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

หลังจากการจับภาพสิ้นสุดลง แอตทริบิวต์จะเก็บค่าระดับการซูมล่าสุดไว้

คุณไม่ต้องมีสิทธิ์ "captured-surface-control" เพื่ออ่านแอตทริบิวต์นี้

onzoomlevelchange

ตัวแฮนเดิลเหตุการณ์นี้ช่วยให้รอฟังการเปลี่ยนแปลงระดับการซูมของแท็บที่บันทึกไว้ได้ ซึ่งอาจเกิดขึ้นในกรณีใดกรณีหนึ่งต่อไปนี้

• เมื่อผู้ใช้โต้ตอบกับเบราว์เซอร์เพื่อเปลี่ยนระดับการซูมของแท็บที่บันทึกไว้ด้วยตนเอง
• ตอบสนองต่อการเรียกใช้เมธอดการตั้งค่าการซูมของแอปจับภาพ (อธิบายไว้ด้านล่าง)

คุณไม่ต้องมีสิทธิ์ "captured-surface-control" เพื่ออ่านแอตทริบิวต์นี้

increaseZoomLevel(), decreaseZoomLevel() และ resetZoomLevel()

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

increaseZoomLevel() และ decreaseZoomLevel() จะเปลี่ยนระดับการซูมเป็นระดับถัดไปหรือก่อนหน้าตามลําดับตามการจัดเรียงที่ getSupportedZoomLevels() แสดง resetZoomLevel() จะตั้งค่าเป็น 100

ต้องมี"captured-surface-control"สิทธิ์ในการเรียกใช้เมธอดเหล่านี้ หากแอปจับภาพไม่มีสิทธิ์นี้ ระบบจะแจ้งให้ผู้ใช้ให้สิทธิ์หรือปฏิเสธ

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

• สิทธิ์ที่ขาดหายไป
• โทรก่อนการจับภาพเริ่มต้น
• เรียกใช้หลังจากการจับภาพสิ้นสุดลง
• เรียกใช้บน controller ที่เชื่อมโยงกับการจับภาพประเภทพื้นผิวการแสดงผลที่ไม่รองรับ (นั่นคือ ยกเว้นการจับภาพแท็บ)
• พยายามเพิ่มหรือลดค่าให้เกินค่าสูงสุดหรือค่าต่ำสุดตามลำดับ

โปรดทราบว่าเราขอแนะนำให้หลีกเลี่ยงการโทรหา decreaseZoomLevel() หาก controller.zoomLevel == controller.getSupportedZoomLevels().at(0) และป้องกันไม่ให้โทรหา increaseZoomLevel() ในลักษณะเดียวกับ .at(-1)

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

const zoomIncreaseButton = document.getElementById('zoomInButton');
zoomIncreaseButton.addEventListener('click', async (event) => {
  if (controller.zoomLevel >= controller.getSupportedZoomLevels().at(-1)) {
    return;
  }
  try {
    await controller.increaseZoomLevel();
  } catch (error) {
    // Inspect the error.
    // ...
  }
});

ตัวอย่างต่อไปนี้แสดงวิธีตอบสนองต่อการเปลี่ยนแปลงระดับการซูมของแท็บที่บันทึกไว้

controller.addEventListener('zoomlevelchange', (event) => {
  const zoomLevelLabel = document.querySelector('#zoomLevelLabel');
  zoomLevelLabel.textContent = `${controller.zoomLevel}%`;
});

การตรวจหาองค์ประกอบ

หากต้องการตรวจสอบว่าระบบรองรับ Captured Surface Control API หรือไม่ ให้ใช้

if (!!window.CaptureController?.prototype.forwardWheel) {
  // CaptureController forwardWheel() is supported.
}

คุณใช้แพลตฟอร์มอื่นๆ ของ Captured Surface Control API อื่นๆ ก็ได้ เช่น increaseZoomLevel หรือ decreaseZoomLevel หรือจะตรวจสอบทั้งหมดก็ได้

การสนับสนุนเบราว์เซอร์

การควบคุมพื้นผิวที่บันทึกไว้พร้อมใช้งานใน Chrome 136 บนเดสก์ท็อปเท่านั้น

ความปลอดภัยและความเป็นส่วนตัว

"captured-surface-control" นโยบายสิทธิ์ช่วยให้คุณจัดการวิธีที่แอปจับภาพและ iframe ของบุคคลที่สามที่ฝังไว้เข้าถึงการควบคุมพื้นผิวที่จับภาพได้ หากต้องการทำความเข้าใจข้อเสียด้านความปลอดภัย โปรดดูส่วนข้อควรพิจารณาด้านความเป็นส่วนตัวและความปลอดภัยของคำอธิบายเกี่ยวกับการควบคุมพื้นผิวที่จับภาพ

สาธิต

คุณเล่นกับการควบคุมพื้นผิวที่บันทึกไว้ได้โดยเรียกใช้เดโมใน Glitch อย่าลืมตรวจสอบซอร์สโค้ด

ความคิดเห็น

ทีม Chrome และชุมชนมาตรฐานเว็บอยากทราบความคิดเห็นของคุณเกี่ยวกับการควบคุมพื้นผิวที่บันทึกไว้

บอกเราเกี่ยวกับการออกแบบ

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

พบปัญหาในการติดตั้งใช้งานใช่ไหม

หากพบข้อบกพร่องในการใช้งาน Chrome หรือการใช้งานแตกต่างจากข้อมูลจำเพาะหรือไม่ รายงานข้อบกพร่องที่ https://new.crbug.com โปรดระบุรายละเอียดให้มากที่สุด รวมถึงวิธีการจำลองข้อบกพร่อง ข้อบกพร่องเหมาะอย่างยิ่งสำหรับการแชร์ข้อบกพร่องที่ทำให้เกิดซ้ำได้

ลิงก์ที่มีประโยชน์

• คำอธิบาย
• ความตั้งใจที่จะทดสอบ
• รายการ ChromeStatus.com