APIهای Fullscreen و Geolocation

مقدمه

جاوااسکریپت APIهای قدرتمندی برای تعامل با محیط فیزیکی و نمایشی کاربر ارائه می‌دهد. در این درس با دو مورد از مهم‌ترین آنها آشنا می‌شویم: Fullscreen API که به ما امکان کنترل حالت نمایش صفحه را می‌دهد، و Geolocation API که به ما اجازه می‌دهد موقعیت جغرافیایی کاربر را به دست آوریم. هر دوی این APIها به دلیل دسترسی به منابع حساس، نیازمند مجوز صریح از سوی کاربر هستند و معمولاً در یک بستر امن (HTTPS) کار می‌کنند.

حالت تمام‌صفحه (Fullscreen)

Fullscreen API به ما اجازه می‌دهد تا یک عنصر خاص (مانند یک ویدئو، یک بازی، یا یک گالری تصاویر) یا کل صفحه را به حالت تمام‌صفحه ببریم. این کار یک تجربه کاربری فراگیر و بدون حواس‌پرتی ایجاد می‌کند. به دلایل امنیتی، ورود به حالت تمام‌صفحه باید همیشه توسط یک تعامل مستقیم از سوی کاربر (مانند یک کلیک) آغاز شود.

ورود و خروج از حالت تمام‌صفحه

برای مدیریت حالت تمام‌صفحه، از متدها و پراپرتی‌های زیر استفاده می‌کنیم:

• element.requestFullscreen(): به صورت ناهمزمان (asynchronous) درخواست می‌دهد تا عنصر مورد نظر به حالت تمام‌صفحه برود. این متد یک Promise برمی‌گرداند.
• document.exitFullscreen(): از حالت تمام‌صفحه خارج می‌شود. این متد نیز یک Promise برمی‌گرداند.
• document.fullscreenElement: اگر صفحه در حالت تمام‌صفحه باشد، این پراپرتی به عنصری که تمام‌صفحه شده است اشاره می‌کند؛ در غیر این صورت مقدار آن null است.

JAVASCRIPT

const elementToFullscreen = document.getElementById('video-player');
const toggleBtn = document.getElementById('fullscreen-btn');

toggleBtn.addEventListener('click', async () => {
    if (!document.fullscreenElement) {
        try {
            await elementToFullscreen.requestFullscreen();
        } catch (err) {
            console.error(`Error enabling full-screen mode: ${err.message}`);
        }
    } else {
        if (document.exitFullscreen) {
            await document.exitFullscreen();
        }
    }
});

در این کد، یک دکمه برای تغییر وضعیت تمام‌صفحه داریم. با هر کلیک، ابتدا با بررسی document.fullscreenElement چک می‌کنیم که آیا در حالت تمام‌صفحه هستیم یا خیر. اگر نباشیم، requestFullscreen() را روی عنصر ویدئو فراخوانی می‌کنیم و در غیر این صورت، با exitFullscreen() از این حالت خارج می‌شویم.

موقعیت‌یابی جغرافیایی (Geolocation)

Geolocation API که از طریق navigator.geolocation در دسترس است، به ما اجازه می‌دهد تا به موقعیت مکانی دستگاه کاربر دسترسی پیدا کنیم. این اطلاعات معمولاً از طریق GPS، نقاط دسترسی Wi-Fi، یا triangulation برج‌های مخابراتی به دست می‌آید. این API برای اپلیکیشن‌های مبتنی بر مکان، مانند نقشه‌ها یا سرویس‌های تحویل، حیاتی است.

دریافت موقعیت فعلی

برای دریافت یک‌باره موقعیت کاربر، از متد getCurrentPosition() استفاده می‌کنیم. این متد حداقل یک تابع callback برای موفقیت، و به صورت اختیاری یک تابع callback برای خطا و یک شیء options برای تنظیمات بیشتر (مانند دقت بالا) دریافت می‌کند.

JAVASCRIPT

document.getElementById('get-location-btn').addEventListener('click', () => {
    if ('geolocation' in navigator) {
        navigator.geolocation.getCurrentPosition(successCallback, errorCallback);
    } else {
        console.log('Geolocation is not available.');
    }
});

function successCallback(position) {
    const { latitude, longitude, accuracy } = position.coords;
    console.log(`Lat: ${latitude}, Lon: ${longitude}`);
    console.log(`Accuracy: ${accuracy} meters.`);
}

function errorCallback(error) {
    console.error(`Unable to retrieve location: ${error.message}`);
}

در این کد، پس از کلیک کاربر و دریافت مجوز، تابع successCallback با یک شیء position فراخوانی می‌شود. این شیء حاوی یک شیء coords است که شامل عرض جغرافیایی (latitude)، طول جغرافیایی (longitude) و دقت (accuracy) موقعیت می‌باشد.

رهگیری مداوم موقعیت

برای اپلیکیشن‌هایی که نیاز به به‌روزرسانی زنده موقعیت دارند (مانند یک اپلیکیشن مسیریابی)، متد watchPosition() استفاده می‌شود. این متد مشابه getCurrentPosition() عمل می‌کند، با این تفاوت که هر بار موقعیت کاربر تغییر کند، تابع callback موفقیت را دوباره فراخوانی می‌کند. این متد یک `ID` عددی برمی‌گرداند که می‌توان از آن برای پایان دادن به رهگیری با متد clearWatch() استفاده کرد.

JAVASCRIPT

let watchId;
function startWatching() {
    watchId = navigator.geolocation.watchPosition(
        position => console.log('New position:', position.coords)
    );
}
function stopWatching() {
    if (watchId) {
        navigator.geolocation.clearWatch(watchId);
        console.log('Position watching stopped.');
    }
}

این کد توابعی برای شروع و پایان رهگیری موقعیت تعریف می‌کند. فراخوانی clearWatch() برای جلوگیری از مصرف بیش از حد باتری دستگاه کاربر پس از اتمام نیاز به رهگیری، بسیار مهم است.

در این درس با دو API قدرتمند برای تعامل با نمایشگر و موقعیت فیزیکی کاربر آشنا شدیم. Fullscreen API برای ساخت تجربیات کاربری فراگیر و Geolocation API برای ارائه خدمات مبتنی بر مکان، ابزارهای مهمی هستند که هر دو نیازمند کسب اجازه از کاربر می‌باشند. در درس بعدی، با `APIهای Device` آشنا خواهیم شد که به ما اجازه می‌دهند به اطلاعات و رویدادهای مربوط به سخت‌افزار دستگاه، مانند حرکت و جهت‌گیری آن، دسترسی پیدا کنیم.