גלילה בכרטיסייה מוקלטת ושינוי מרחק התצוגה שלה

François Beaufort
François Beaufort
GitHub
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.   // ... }

ה-method‏ forwardWheel() מקבל קלט יחיד שיכול להיות אחד מהבאים:

  • רכיב HTML שממנו אירועי גלגלת יועברו לכרטיסייה שנלכדה.
  • ‫null, שמציין שההעברה צריכה להיפסק.

שיחה מוצלחת אל forwardWheel() מבטלת שיחות קודמות.

ההבטחה שמוחזרת על ידי forwardWheel() יכולה להידחות במקרים הבאים:

  • אם הפעלת צילום המסך עדיין לא התחילה או שכבר הופסקה.
  • אם המשתמש לא העניק את ההרשאה הרלוונטית.

שינוי מרחק התצוגה

האינטראקציה עם רמת הזום של הכרטיסייה שצולמה מתבצעת באמצעות ממשקי ה-API הבאים של CaptureController:

getSupportedZoomLevels()

השיטה הזו מחזירה רשימה של רמות זום שהדפדפן תומך בהן עבור סוג השטח שמתבצעת לו לכידה. הערכים ברשימה הזו מיוצגים כאחוזים ביחס ל'רמת הזום שמוגדרת כברירת מחדל', שהיא 100%. הרשימה היא מונוטונית עולה ומכילה את הערך 100.

אפשר לקרוא לשיטה הזו רק עבור סוגים נתמכים של פלטפורמות להצגת מודעות, שכרגע כוללים רק כרטיסיות.

יכול להיות שהפונקציה controller.getSupportedZoomLevels() תיקרא אם התנאים הבאים מתקיימים:

  • controller משויך ללכידה פעילה.
  • הצילום הוא של כרטיסייה.

אחרת, תופיע שגיאה.

לא נדרשת ההרשאה "captured-surface-control" כדי לקרוא לשיטה הזו.

zoomLevel

במאפיין הזה לקריאה בלבד מופיעה רמת הזום הנוכחית של הכרטיסייה שצולמה. זהו מאפיין שניתן להגדיר בו ערך null, והוא מחזיק את הערך null אם לסוג המשטח שצולם אין הגדרה משמעותית של רמת הזום. בשלב הזה, רמת הזום מוגדרת רק לכרטיסיות, ולא לחלונות או למסכים.

אחרי שהצילום מסתיים, ערך המאפיין יהיה הערך האחרון של רמת הזום.

לא נדרשת הרשאה מסוג "captured-surface-control" כדי לקרוא את המאפיין הזה.

onzoomlevelchange

ה-event handler הזה מאפשר להאזין לשינויים ברמת הזום של הכרטיסייה שצולמה. הם קורים באחת מהדרכים הבאות:

  • כשהמשתמש יוצר אינטראקציה עם הדפדפן כדי לשנות באופן ידני את רמת הזום של הכרטיסייה שצולמה.
  • בתגובה לקריאות של האפליקציה לשיטות הגדרת הזום (שמתוארות בהמשך).

לא נדרשת הרשאה מסוג "captured-surface-control" כדי לקרוא את המאפיין הזה.

increaseZoomLevel(),‏ decreaseZoomLevel() וגם resetZoomLevel()

השיטות האלה מאפשרות לשנות את רמת הזום של הכרטיסייה שצולמה.

‫increaseZoomLevel() ו-decreaseZoomLevel() משנים את רמת הזום לרמה הבאה או הקודמת, בהתאמה, לפי הסדר שמוחזר על ידי getSupportedZoomLevels(). ‫resetZoomLevel() מגדיר את הערך ל-100.

נדרשת "captured-surface-control"הרשאה כדי לקרוא ל-methods האלה. אם לאפליקציה שמבצעת את הצילום אין את ההרשאה הזו, המשתמש יתבקש להעניק אותה או לדחות אותה.

כל השיטות האלה מחזירות הבטחה שנפתרת אם הקריאה מצליחה, ונכשלת אחרת. סיבות אפשריות לדחייה:

  • חסרה הרשאה.
  • התקשרתם לפני שהתחלתם את הצילום.
  • התקשרתם אחרי שהצילום הסתיים.
  • הפונקציה נקראה ב-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}%`; });

זיהוי תכונות

כדי לבדוק אם ממשקי API של Captured Surface Control נתמכים, משתמשים בפקודה:

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

אפשר גם להשתמש בכל אחד מהממשקים האחרים של Captured Surface Control API, כמו increaseZoomLevel או decreaseZoomLevel, או אפילו לבדוק את כולם.

תמיכה בדפדפנים

התכונה 'הצגת כלי הבקרה של המשטח' זמינה מגרסה Chrome 136 ואילך במחשב בלבד.

אבטחה ופרטיות

"captured-surface-control" מדיניות ההרשאות מאפשרת לכם לנהל את הגישה של אפליקציית הצילום ושל מסגרות iframe מוטמעות של צד שלישי לשליטה באזור שצולם. כדי להבין את הפשרות בנושא אבטחה, כדאי לעיין בסעיף שיקולים בנושא פרטיות ואבטחה במאמר שמסביר על אמצעי הבקרה של משטח הלכידה.

הדגמה (דמו)

כדי להתנסות ב-Captured Surface Control, אפשר להריץ את ההדגמה.

משוב

צוות Chrome וקהילת תקני האינטרנט רוצים לשמוע על החוויות שלכם עם התכונה 'שליטה במשטח שצולם'.

מתארים את העיצוב

האם יש משהו ב'לכידת משטח' שלא פועל כמו שציפית? או שחסרות שיטות או מאפיינים שצריך להטמיע כדי לממש את הרעיון? יש לך שאלה או הערה לגבי מודל האבטחה? אפשר להגיש בקשה לבעיה במפרט במאגר GitHub, או להוסיף את המחשבות שלכם לבעיה קיימת.

בעיה בהטמעה?

מצאתם באג בהטמעה של Chrome? או שההטמעה שונה מהמפרט? מדווחים על באג בכתובת https://new.crbug.com. חשוב לכלול כמה שיותר פרטים, וגם הוראות לשחזור הבאג.