اشتراک‌گذاری برگه‌ها، پنجره‌ها و صفحه‌ها در حال حاضر در پلتفرم وب با Screen Capture API امکان‌پذیر است. هنگامی که یک برنامه وب با getDisplayMedia() تماس می‌گیرد، Chrome از کاربر می‌خواهد یک برگه، پنجره یا صفحه را با برنامه وب به‌عنوان ویدیوی MediaStreamTrack به اشتراک بگذارد.
بسیاری از برنامه‌های وب که از getDisplayMedia() استفاده می‌کنند، پیش‌نمایش ویدیویی از سطح ضبط‌شده را به کاربر نشان می‌دهند. برای مثال، برنامه‌های کنفرانس ویدیویی اغلب این ویدیو را برای کاربران راه دور پخش می‌کنند و در عین حال آن را به یک HTMLVideoElement محلی نیز رندر می‌کنند تا کاربر محلی دائماً پیش‌نمایش چیزی را که به اشتراک می‌گذارد ببیند.
این مستندات API جدید Captured Surface Control در کروم را معرفی می‌کند که به برنامه وب شما اجازه می‌دهد تا یک برگه ضبط‌شده را پیمایش کند، و همچنین سطح بزرگنمایی یک برگه ضبط‌شده را بخواند و بنویسد.
چرا از Captured Surface Control استفاده کنیم؟
همه برنامه های کنفرانس ویدیویی از همین اشکال رنج می برند. اگر کاربر بخواهد با یک برگه یا پنجره ضبط شده تعامل داشته باشد، کاربر باید به آن سطح سوئیچ کند و او را از برنامه کنفرانس ویدیویی دور کند. این چند چالش را به همراه دارد:
- کاربر نمی‌تواند همزمان برنامه ضبط‌شده و فیدهای ویدیویی کاربران راه دور را ببیند، مگر اینکه از تصویر در تصویر یا پنجره‌های کنار هم جداگانه برای برگه کنفرانس ویدیویی و برگه اشتراک‌گذاری شده استفاده کند. در یک صفحه نمایش کوچکتر، این ممکن است دشوار باشد.
- نیاز کاربر به پریدن بین برنامه کنفرانس ویدیویی و سطح ضبط شده سنگین است.
- وقتی کاربر از برنامه کنفرانس ویدیویی دور است، دسترسی به کنترل‌هایی را که در معرض آن قرار می‌گیرد، از دست می‌دهد. به عنوان مثال، یک برنامه چت تعبیه شده، واکنش های ایموجی، اعلان هایی در مورد درخواست کاربران برای پیوستن به تماس، کنترل های چند رسانه ای و طرح بندی، و سایر ویژگی های ویدئو کنفرانس مفید.
- ارائه دهنده نمی تواند کنترل را به شرکت کنندگان از راه دور واگذار کند. این منجر به سناریوی بسیار آشنا می شود که در آن کاربران از راه دور از ارائه کننده می خواهند اسلاید را تغییر دهد، کمی بالا و پایین حرکت کند یا سطح بزرگنمایی را تنظیم کند.
API Captured Surface Control این مشکلات را برطرف می کند.
چگونه از Captured Surface Control استفاده کنم؟
استفاده موفقیت آمیز از Captured Surface Control به چند مرحله نیاز دارد، مانند گرفتن صریح برگه مرورگر و گرفتن مجوز از کاربر قبل از اینکه بتوانید برگه ضبط شده را اسکرول و بزرگنمایی کنید.
یک برگه مرورگر را ضبط کنید
با درخواست از کاربر برای انتخاب سطحی برای اشتراک گذاری با استفاده از 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() فراخوانی های قبلی را لغو می کند.
وعده بازگردانده شده توسط forwardWheel() را می توان در موارد زیر رد کرد:
- اگر جلسه ضبط هنوز شروع نشده یا قبلاً متوقف شده است.
- در صورتی که کاربر مجوز مربوطه را اعطا نکرده باشد.
بزرگنمایی ضربه بزنید؛
تعامل با سطح زوم برگه ضبط شده از طریق سطوح API CaptureController زیر انجام می شود:
getSupportedZoomLevels()
این روش فهرستی از سطوح زوم پشتیبانی شده توسط مرورگر را برای نوع سطحی که گرفته می شود، برمی گرداند. مقادیر در این لیست به صورت درصدی نسبت به "سطح بزرگنمایی پیش‌فرض" نشان داده می‌شوند که به صورت 100% تعریف می‌شود. لیست به طور یکنواخت در حال افزایش است و حاوی مقدار 100 است.
این روش ممکن است فقط برای انواع سطح نمایش پشتیبانی شده فراخوانی شود، که در حال حاضر فقط برای زبانه ها معنی می شود.
controller.getSupportedZoomLevels() ممکن است در صورت وجود شرایط زیر فراخوانی شود:
-
controllerبا یک ضبط فعال مرتبط است. - ضبط یک زبانه است.
در غیر این صورت یک خطا مطرح می شود.
مجوز "captured-surface-control" برای فراخوانی این روش مورد نیاز نیست .
zoomLevel
این ویژگی فقط خواندنی سطح زوم فعلی برگه ضبط شده را نگه می دارد. این یک ویژگی nullable است و اگر نوع سطح گرفته شده تعریف معناداری از سطح زوم نداشته باشد، null می ماند. در این زمان، سطح زوم فقط برای برگه ها تعریف شده است، نه برای ویندوز یا صفحه نمایش.
پس از پایان گرفتن عکس، ویژگی آخرین مقدار سطح زوم را نگه می دارد.
مجوز "captured-surface-control" برای خواندن این ویژگی لازم نیست .
onzoomlevelchange
این کنترل کننده رویداد گوش دادن به تغییرات در سطح زوم برگه ضبط شده را تسهیل می کند. اینها یا اتفاق می افتد:
- هنگامی که کاربر با مرورگر تعامل می کند تا به صورت دستی سطح زوم برگه ضبط شده را تغییر دهد.
- در پاسخ به تماس‌های برنامه عکس‌برداری با روش‌های تنظیم بزرگنمایی (توضیح داده شده در زیر).
مجوز "captured-surface-control" برای خواندن این ویژگی لازم نیست .
increaseZoomLevel() ، decreaseZoomLevel() و resetZoomLevel()
این روش‌ها اجازه می‌دهند تا سطح بزرگنمایی برگه ضبط‌شده را دستکاری کنید.
increaseZoomLevel() )()()()( decreaseZoomLevel() )()()()(()()()()()()()()()()()()()()()()()()()()،سطح بزرگنمایی را بهسطح بزرگنمایی بعدی یا قبلی طبق ترتیبی که توسط getSupportedZoomLevels() برگردانده می‌شود، تغییر می‌دهند. resetZoomLevel() مقدار را 100 تنظیم می کند.
برای فراخوانی این متدها مجوز "captured-surface-control" مورد نیاز است . اگر برنامه عکس‌برداری این مجوز را نداشته باشد، از کاربر خواسته می‌شود آن را اعطا یا رد کند.
همه این روش ها یک وعده را برمی گرداند که در صورت موفقیت آمیز بودن تماس حل می شود و در غیر این صورت رد می شود. دلایل احتمالی رد عبارتند از:
- مجوز از دست رفته
- قبل از شروع ضبط تماس گرفته شد.
- پس از پایان دستگیری تماس گرفت.
- به یک
controllerمرتبط با تصویربرداری از نوع سطح صفحه نمایش پشتیبانی نشده فراخوانی می شود. (یعنی هر چیزی جز ضبط تب.) - تلاش برای افزایش یا کاهش به ترتیب از حداکثر یا حداقل مقدار.
به طور قابل‌توجه، توصیه می‌شود اگر controller.zoomLevel == controller.getSupportedZoomLevels().at(0) فراخوانی () decreaseZoomLevel() اجتناب کنید و از تماس‌های 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.
}
استفاده از سایر سطوح API Captured Surface Control، مانند increaseZoomLevel یا decreaseZoomLevel ، یا حتی بررسی همه آنها به همان اندازه امکان پذیر است.
پشتیبانی از مرورگر
Captured Surface Control از Chrome 136 فقط روی دسک‌تاپ در دسترس است.
امنیت و حریم خصوصی
خط‌مشی مجوز "captured-surface-control" به شما امکان می‌دهد نحوه دسترسی برنامه عکس‌برداری و iframeهای شخص ثالث تعبیه‌شده به Captured Surface Control را مدیریت کنید. برای درک معاوضه‌های امنیتی، بخش ملاحظات حریم خصوصی و امنیتی توضیح‌دهنده کنترل سطح ضبط شده را بررسی کنید.
نسخه ی نمایشی
با اجرای دمو در Glitch می توانید با Captured Surface Control بازی کنید. حتماً کد منبع را بررسی کنید .
بازخورد
تیم Chrome و انجمن استانداردهای وب می‌خواهند درباره تجربیات شما با Captured Surface Control بشنوند.
در مورد طراحی به ما بگویید
آیا چیزی در مورد Captured Surface Capture وجود دارد که آنطور که انتظار داشتید کار نمی کند؟ یا آیا روش ها یا ویژگی هایی وجود دارد که برای اجرای ایده خود به آنها نیاز دارید؟ سوال یا نظری در مورد مدل امنیتی دارید؟ یک مشکل مشخصات را در مخزن GitHub ثبت کنید یا افکار خود را به یک مشکل موجود اضافه کنید.
مشکل در اجرا؟
آیا اشکالی در پیاده سازی کروم پیدا کردید؟ یا اجرا با مشخصات متفاوت است؟ یک اشکال را در https://new.crbug.com ثبت کنید. حتماً تا جایی که می توانید جزئیات و همچنین دستورالعمل هایی را برای بازتولید درج کنید. Glitch برای به اشتراک گذاری باگ های قابل تکرار عالی عمل می کند.