با Screen Wake Lock API بیدار بمانید

Screen Wake Lock API راهی برای جلوگیری از تیره شدن یا قفل شدن صفحه نمایش دستگاه ها در زمانی که برنامه نیاز به ادامه کار دارد، فراهم می کند.

Pete LePage

Thomas Steiner

Screen Wake Lock API چیست؟

برای جلوگیری از تخلیه باتری، اکثر دستگاه‌ها به سرعت در حالت بیکار رها می‌شوند. در حالی که در بیشتر مواقع این کار خوب است، برخی از برنامه ها برای تکمیل کار خود باید صفحه نمایش را بیدار نگه دارند. به عنوان مثال می‌توان به برنامه‌های آشپزی اشاره کرد که مراحل یک دستور غذا را نشان می‌دهند یا یک بازی مانند Ball Puzzle که از APIهای حرکتی دستگاه برای ورودی استفاده می‌کند.

Screen Wake Lock API راهی برای جلوگیری از کم نور شدن دستگاه و قفل شدن صفحه نمایش فراهم می کند. این قابلیت تجربه‌های جدیدی را امکان‌پذیر می‌سازد که تا به حال به یک اپلیکیشن مخصوص پلتفرم نیاز داشتند.

Screen Wake Lock API نیاز به راه‌حل‌های هک و بالقوه پرقدرت را کاهش می‌دهد. این کاستی‌های یک API قدیمی‌تر را که محدود به روشن نگه داشتن صفحه‌نمایش بود و دارای تعدادی مشکلات امنیتی و حریم خصوصی بود، برطرف می‌کند.

موارد استفاده پیشنهادی برای Screen Wake Lock API

RioRun ، یک برنامه وب توسعه یافته توسط The Guardian ، یک مورد استفاده عالی بود (اگرچه دیگر در دسترس نیست). این برنامه شما را به یک تور صوتی مجازی در ریو می برد و مسیر ماراتن المپیک 2016 را دنبال می کند. بدون wake lock، صفحه نمایش کاربران در حین بازی اغلب خاموش می شود و استفاده از آن را سخت می کند.

البته موارد استفاده دیگری نیز وجود دارد:

• یک برنامه دستور پخت که هنگام پختن کیک یا پختن شام، صفحه نمایش را روشن نگه می دارد
• کارت پرواز یا برنامه بلیط که صفحه را تا زمانی که بارکد اسکن نشده است روشن نگه می دارد
• برنامه ای به سبک کیوسک که صفحه را به طور مداوم روشن نگه می دارد
• یک برنامه ارائه مبتنی بر وب که صفحه نمایش را در طول ارائه روشن نگه می دارد

وضعیت فعلی

با استفاده از Screen Wake Lock API

انواع ویک لاک

Screen Wake Lock API در حال حاضر فقط یک نوع wake lock را ارائه می دهد: screen .

قفل بیدار شدن screen

قفل بیدار شدن screen از خاموش شدن صفحه نمایش دستگاه جلوگیری می کند تا کاربر بتواند اطلاعاتی را که روی صفحه نمایش داده می شود ببیند.

دریافت قفل بیدار شدن صفحه نمایش

برای درخواست wake lock صفحه، باید متد navigator.wakeLock.request() را فراخوانی کنید که یک شی WakeLockSentinel را برمی گرداند. شما به این روش نوع wake lock مورد نظر را به عنوان پارامتر ارسال می کنید، که در حال حاضر فقط به 'screen' محدود شده است و بنابراین اختیاری است. مرورگر می‌تواند درخواست را به دلایل مختلف رد کند (مثلاً به دلیل پایین بودن سطح شارژ باتری)، بنابراین تمرین خوبی است که تماس را در یک عبارت try…catch قرار دهید. در صورت خرابی، پیام استثنا حاوی جزئیات بیشتری خواهد بود.

آزاد کردن قفل بیدار شدن صفحه

شما همچنین به راهی برای آزاد کردن قفل صفحه نمایش نیاز دارید که با فراخوانی متد release() شی WakeLockSentinel به دست می آید. اگر مرجعی به WakeLockSentinel ذخیره نکنید، راهی برای آزاد کردن قفل به صورت دستی وجود ندارد، اما زمانی که برگه فعلی نامرئی شود، آزاد می شود.

اگر می‌خواهید پس از گذشت مدت زمان مشخصی، قفل بیدار شدن صفحه را به طور خودکار آزاد کنید، می‌توانید از window.setTimeout() برای فراخوانی release() استفاده کنید، همانطور که در مثال زیر نشان داده شده است.

// The wake lock sentinel.
let wakeLock = null;

// Function that attempts to request a screen wake lock.
const requestWakeLock = async () => {
  try {
    wakeLock = await navigator.wakeLock.request();
    wakeLock.addEventListener('release', () => {
      console.log('Screen Wake Lock released:', wakeLock.released);
    });
    console.log('Screen Wake Lock released:', wakeLock.released);
  } catch (err) {
    console.error(`${err.name}, ${err.message}`);
  }
};

// Request a screen wake lock…
await requestWakeLock();
// …and release it again after 5s.
window.setTimeout(() => {
  wakeLock.release();
  wakeLock = null;
}, 5000);

شی WakeLockSentinel دارای ویژگی به نام released است که نشان می دهد که آیا یک نگهبان قبلاً آزاد شده است یا خیر. مقدار آن در ابتدا false است و پس از ارسال یک رویداد "release" به true تغییر می کند. این ویژگی به توسعه دهندگان وب کمک می کند تا بدانند چه زمانی یک قفل آزاد شده است تا نیازی به پیگیری آن به صورت دستی نداشته باشند. از Chrome 87 در دسترس است.

چرخه عمر قفل بیدار شدن صفحه نمایش

هنگامی که با نمایش نمایشی wake lock صفحه نمایش بازی می کنید، متوجه خواهید شد که قفل های بیدار صفحه نمایش به دید صفحه حساس هستند. این بدان معنی است که وقتی یک برگه یا پنجره را کوچک کنید، یا از برگه یا پنجره ای که در آن قفل بیدار صفحه فعال است، فاصله بگیرید، قفل بیدار شدن صفحه به طور خودکار آزاد می شود.

برای به دست آوردن مجدد قفل بیدار شدن صفحه، به رویداد visibilitychange گوش دهید و در صورت وقوع یک قفل بیدار شدن صفحه جدید درخواست کنید:

const handleVisibilityChange = async () => {
  if (wakeLock !== null && document.visibilityState === 'visible') {
    await requestWakeLock();
  }
};

document.addEventListener('visibilitychange', handleVisibilityChange);

تاثیر خود را بر منابع سیستم به حداقل برسانید

آیا باید از قفل صفحه نمایش در برنامه خود استفاده کنید؟ رویکرد شما بستگی به نیازهای برنامه شما دارد. صرف نظر از این، شما باید از سبک ترین رویکرد ممکن برای برنامه خود استفاده کنید تا تأثیر آن بر منابع سیستم را به حداقل برسانید.

قبل از افزودن قفل بیدار شدن صفحه به برنامه خود، در نظر بگیرید که آیا موارد استفاده شما با یکی از راه حل های جایگزین زیر قابل حل است یا خیر:

• اگر برنامه شما بارگیری طولانی مدت انجام می دهد، از واکشی پس زمینه استفاده کنید.
• اگر برنامه شما داده‌ها را از یک سرور خارجی همگام‌سازی می‌کند، از همگام‌سازی پس‌زمینه استفاده کنید.

نسخه ی نمایشی

نسخه نمایشی و منبع نمایشی Screen Wake Lock را بررسی کنید. توجه داشته باشید که چگونه هنگام تعویض برگه ها یا برنامه ها، قفل بیدار شدن صفحه به طور خودکار آزاد می شود.

Screen Wake Locks در مدیر وظیفه سیستم عامل

می توانید از مدیر وظیفه سیستم عامل خود استفاده کنید تا ببینید آیا برنامه ای از خوابیدن رایانه شما جلوگیری می کند یا خیر. ویدیوی زیر نمایشگر فعالیت macOS را نشان می‌دهد که نشان می‌دهد کروم دارای قفل فعال صفحه نمایش است که سیستم را بیدار نگه می‌دارد.

بازخورد

گروه انجمن انکوباتور پلتفرم وب (WICG) و تیم Chrome می‌خواهند درباره افکار و تجربیات شما در مورد Screen Wake Lock API بشنوند.

در مورد طراحی API به ما بگویید

آیا چیزی در مورد API وجود دارد که مطابق انتظار کار نمی کند؟ یا آیا روش ها یا ویژگی هایی وجود دارد که برای اجرای ایده خود به آنها نیاز دارید؟

• یک مشکل مشخصات را در مخزن Screen Wake Lock API GitHub ثبت کنید یا افکار خود را به یک مشکل موجود اضافه کنید.

گزارش مشکل در اجرا

آیا اشکالی در پیاده سازی کروم پیدا کردید؟ یا اجرا با مشخصات متفاوت است؟

• یک اشکال را در https://new.crbug.com ثبت کنید. اطمینان حاصل کنید که تا جایی که می توانید جزئیات را درج کنید، دستورالعمل های ساده ای را برای بازتولید اشکال ارائه دهید و Components را روی Blink>WakeLock تنظیم کنید. Glitch برای به اشتراک گذاری سریع و آسان تکرارها عالی عمل می کند.

پشتیبانی از API را نشان دهید

آیا قصد دارید از Screen Wake Lock API استفاده کنید؟ پشتیبانی عمومی شما به تیم Chrome کمک می‌کند ویژگی‌ها را اولویت‌بندی کند و به سایر فروشندگان مرورگر نشان می‌دهد که چقدر حمایت از آنها ضروری است.

• نحوه استفاده از API را در موضوع WICG Discourse به اشتراک بگذارید.
• با استفاده از هشتگ #WakeLock یک توییت به ChromiumDev@ ارسال کنید و به ما اطلاع دهید کجا و چگونه از آن استفاده می‌کنید.

لینک های مفید

• مشخصات پیشنهادی کاندید | پیش نویس سردبیر
• نمایشگر Wake Lock | منبع نمایشی Wake Lock صفحه نمایش
• اشکال ردیابی
• ورودی ChromeStatus.com
• در حال آزمایش با Wake Lock API
• Blink Component: Blink>WakeLock

قدردانی ها

تصویر قهرمان توسط کیت استون متسون در Unsplash. ویدئوی Task Manager توسط هنری لیم .

Screen Wake Lock API راهی برای جلوگیری از تیره شدن یا قفل شدن صفحه نمایش دستگاه ها در زمانی که برنامه نیاز به ادامه کار دارد، فراهم می کند.

Pete LePage

Thomas Steiner

Screen Wake Lock API چیست؟

برای جلوگیری از تخلیه باتری، اکثر دستگاه‌ها به سرعت در حالت بیکار رها می‌شوند. در حالی که در بیشتر مواقع این کار خوب است، برخی از برنامه ها برای تکمیل کار خود باید صفحه نمایش را بیدار نگه دارند. به عنوان مثال می‌توان به برنامه‌های آشپزی اشاره کرد که مراحل یک دستور غذا را نشان می‌دهند یا یک بازی مانند Ball Puzzle که از APIهای حرکتی دستگاه برای ورودی استفاده می‌کند.

Screen Wake Lock API راهی برای جلوگیری از کم نور شدن دستگاه و قفل شدن صفحه نمایش فراهم می کند. این قابلیت تجربه‌های جدیدی را امکان‌پذیر می‌سازد که تا به حال به یک اپلیکیشن مخصوص پلتفرم نیاز داشتند.

Screen Wake Lock API نیاز به راه‌حل‌های هک و بالقوه پرقدرت را کاهش می‌دهد. این کاستی‌های یک API قدیمی‌تر را که محدود به روشن نگه داشتن صفحه‌نمایش بود و دارای تعدادی مشکلات امنیتی و حریم خصوصی بود، برطرف می‌کند.

موارد استفاده پیشنهادی برای Screen Wake Lock API

RioRun ، یک برنامه وب توسعه یافته توسط The Guardian ، یک مورد استفاده عالی بود (اگرچه دیگر در دسترس نیست). این برنامه شما را به یک تور صوتی مجازی در ریو می برد و مسیر ماراتن المپیک 2016 را دنبال می کند. بدون wake lock، صفحه نمایش کاربران در حین بازی اغلب خاموش می شود و استفاده از آن را سخت می کند.

البته موارد استفاده دیگری نیز وجود دارد:

• یک برنامه دستور پخت که هنگام پختن کیک یا پختن شام، صفحه نمایش را روشن نگه می دارد
• کارت پرواز یا برنامه بلیط که صفحه را تا زمانی که بارکد اسکن نشده است روشن نگه می دارد
• برنامه ای به سبک کیوسک که صفحه را به طور مداوم روشن نگه می دارد
• یک برنامه ارائه مبتنی بر وب که صفحه نمایش را در طول ارائه روشن نگه می دارد

وضعیت فعلی

با استفاده از Screen Wake Lock API

انواع ویک لاک

Screen Wake Lock API در حال حاضر فقط یک نوع wake lock را ارائه می دهد: screen .

قفل بیدار شدن screen

قفل بیدار شدن screen از خاموش شدن صفحه نمایش دستگاه جلوگیری می کند تا کاربر بتواند اطلاعاتی را که روی صفحه نمایش داده می شود ببیند.

دریافت قفل بیدار شدن صفحه نمایش

برای درخواست wake lock صفحه، باید متد navigator.wakeLock.request() را فراخوانی کنید که یک شی WakeLockSentinel را برمی گرداند. شما به این روش نوع wake lock مورد نظر را به عنوان پارامتر ارسال می کنید، که در حال حاضر فقط به 'screen' محدود شده است و بنابراین اختیاری است. مرورگر می‌تواند درخواست را به دلایل مختلف رد کند (مثلاً به دلیل پایین بودن سطح شارژ باتری)، بنابراین تمرین خوبی است که تماس را در یک عبارت try…catch قرار دهید. در صورت خرابی، پیام استثنا حاوی جزئیات بیشتری خواهد بود.

آزاد کردن قفل بیدار شدن صفحه

شما همچنین به راهی برای آزاد کردن قفل صفحه نمایش نیاز دارید که با فراخوانی متد release() شی WakeLockSentinel به دست می آید. اگر مرجعی به WakeLockSentinel ذخیره نکنید، راهی برای آزاد کردن قفل به صورت دستی وجود ندارد، اما زمانی که برگه فعلی نامرئی شود، آزاد می شود.

اگر می‌خواهید پس از گذشت مدت زمان مشخصی، قفل بیدار شدن صفحه را به طور خودکار آزاد کنید، می‌توانید از window.setTimeout() برای فراخوانی release() استفاده کنید، همانطور که در مثال زیر نشان داده شده است.

// The wake lock sentinel.
let wakeLock = null;

// Function that attempts to request a screen wake lock.
const requestWakeLock = async () => {
  try {
    wakeLock = await navigator.wakeLock.request();
    wakeLock.addEventListener('release', () => {
      console.log('Screen Wake Lock released:', wakeLock.released);
    });
    console.log('Screen Wake Lock released:', wakeLock.released);
  } catch (err) {
    console.error(`${err.name}, ${err.message}`);
  }
};

// Request a screen wake lock…
await requestWakeLock();
// …and release it again after 5s.
window.setTimeout(() => {
  wakeLock.release();
  wakeLock = null;
}, 5000);

شی WakeLockSentinel دارای ویژگی به نام released است که نشان می دهد که آیا یک نگهبان قبلاً آزاد شده است یا خیر. مقدار آن در ابتدا false است و پس از ارسال یک رویداد "release" به true تغییر می کند. این ویژگی به توسعه دهندگان وب کمک می کند تا بدانند چه زمانی یک قفل آزاد شده است تا نیازی به پیگیری آن به صورت دستی نداشته باشند. از Chrome 87 در دسترس است.

چرخه عمر قفل بیدار شدن صفحه نمایش

هنگامی که با نمایش نمایشی wake lock صفحه نمایش بازی می کنید، متوجه خواهید شد که قفل های بیدار صفحه نمایش به دید صفحه حساس هستند. این بدان معنی است که وقتی یک برگه یا پنجره را کوچک کنید، یا از برگه یا پنجره ای که در آن قفل بیدار صفحه فعال است، فاصله بگیرید، قفل بیدار شدن صفحه به طور خودکار آزاد می شود.

برای به دست آوردن مجدد قفل بیدار شدن صفحه، به رویداد visibilitychange گوش دهید و در صورت وقوع یک قفل بیدار شدن صفحه جدید درخواست کنید:

const handleVisibilityChange = async () => {
  if (wakeLock !== null && document.visibilityState === 'visible') {
    await requestWakeLock();
  }
};

document.addEventListener('visibilitychange', handleVisibilityChange);

تاثیر خود را بر منابع سیستم به حداقل برسانید

آیا باید از قفل صفحه نمایش در برنامه خود استفاده کنید؟ رویکرد شما بستگی به نیازهای برنامه شما دارد. صرف نظر از این، شما باید از سبک ترین رویکرد ممکن برای برنامه خود استفاده کنید تا تأثیر آن بر منابع سیستم را به حداقل برسانید.

قبل از افزودن قفل بیدار شدن صفحه به برنامه خود، در نظر بگیرید که آیا موارد استفاده شما با یکی از راه حل های جایگزین زیر قابل حل است یا خیر:

• اگر برنامه شما بارگیری طولانی مدت انجام می دهد، از واکشی پس زمینه استفاده کنید.
• اگر برنامه شما داده‌ها را از یک سرور خارجی همگام‌سازی می‌کند، از همگام‌سازی پس‌زمینه استفاده کنید.

نسخه ی نمایشی

نسخه نمایشی و منبع نمایشی Screen Wake Lock را بررسی کنید. توجه داشته باشید که چگونه هنگام تعویض برگه ها یا برنامه ها، قفل بیدار شدن صفحه به طور خودکار آزاد می شود.

Screen Wake Locks در مدیر وظیفه سیستم عامل

می توانید از مدیر وظیفه سیستم عامل خود استفاده کنید تا ببینید آیا برنامه ای از خوابیدن رایانه شما جلوگیری می کند یا خیر. ویدیوی زیر نمایشگر فعالیت macOS را نشان می‌دهد که نشان می‌دهد کروم دارای قفل فعال صفحه نمایش است که سیستم را بیدار نگه می‌دارد.

بازخورد

گروه انجمن انکوباتور پلتفرم وب (WICG) و تیم Chrome می‌خواهند درباره افکار و تجربیات شما در مورد Screen Wake Lock API بشنوند.

در مورد طراحی API به ما بگویید

آیا چیزی در مورد API وجود دارد که مطابق انتظار کار نمی کند؟ یا آیا روش ها یا ویژگی هایی وجود دارد که برای اجرای ایده خود به آنها نیاز دارید؟

• یک مشکل مشخصات را در مخزن Screen Wake Lock API GitHub ثبت کنید یا افکار خود را به یک مشکل موجود اضافه کنید.

گزارش مشکل در اجرا

آیا اشکالی در پیاده سازی کروم پیدا کردید؟ یا اجرا با مشخصات متفاوت است؟

• یک اشکال را در https://new.crbug.com ثبت کنید. اطمینان حاصل کنید که تا جایی که می توانید جزئیات را درج کنید، دستورالعمل های ساده ای را برای بازتولید اشکال ارائه دهید و Components را روی Blink>WakeLock تنظیم کنید. Glitch برای به اشتراک گذاری سریع و آسان تکرارها عالی عمل می کند.

پشتیبانی از API را نشان دهید

آیا قصد دارید از Screen Wake Lock API استفاده کنید؟ پشتیبانی عمومی شما به تیم Chrome کمک می‌کند ویژگی‌ها را اولویت‌بندی کند و به سایر فروشندگان مرورگر نشان می‌دهد که چقدر حمایت از آنها ضروری است.

• نحوه استفاده از API را در موضوع WICG Discourse به اشتراک بگذارید.
• با استفاده از هشتگ #WakeLock یک توییت به ChromiumDev@ ارسال کنید و به ما اطلاع دهید کجا و چگونه از آن استفاده می‌کنید.

لینک های مفید

• مشخصات پیشنهادی کاندید | پیش نویس سردبیر
• نمایشگر Wake Lock | منبع نمایشی Wake Lock صفحه نمایش
• اشکال ردیابی
• ورودی ChromeStatus.com
• در حال آزمایش با Wake Lock API
• Blink Component: Blink>WakeLock

قدردانی ها

تصویر قهرمان توسط کیت استون متسون در Unsplash. ویدئوی Task Manager توسط هنری لیم .