این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

کنترل کامل با VirtualKeyboard API

Thomas Steiner

پشتیبانی مرورگر

دستگاه هایی مانند تبلت ها یا تلفن های همراه معمولا یک صفحه کلید مجازی برای تایپ متن دارند. بر خلاف یک صفحه کلید فیزیکی که همیشه وجود دارد و همیشه یکسان است، یک صفحه کلید مجازی ظاهر می شود و ناپدید می شود، وابسته به اقدامات کاربر، که همچنین می تواند به صورت پویا، به عنوان مثال، بر اساس ویژگی inputmode ، سازگار شود.

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

به طور سنتی، مرورگرها به تنهایی با این چالش مقابله می کردند، اما برنامه های پیچیده تر ممکن است نیاز به کنترل بیشتری بر رفتار مرورگر داشته باشند. مثال‌ها شامل دستگاه‌های تلفن همراه چند صفحه‌ای است که در آن‌ها اگر صفحه‌کلید مجازی فقط در یک بخش صفحه نمایش داده شود، رویکرد سنتی منجر به «هدر رفتن» املاک و مستغلات صفحه‌نمایش می‌شود، اما با این وجود، درگاه دید موجود در هر دو صفحه کوچک شده است. تصویر زیر نشان می‌دهد که چگونه می‌توان از VirtualKeyboard API برای بهینه‌سازی طرح‌بندی سند به صورت پویا برای جبران حضور صفحه‌کلید مجازی استفاده کرد.

رویکرد سنتی نتیجه می دهد

موقعیت‌هایی مانند این جایی است که VirtualKeyboard API وارد می‌شود. از سه بخش تشکیل شده است:

رابط VirtualKeyboard روی شی navigator برای دسترسی برنامه‌ای به صفحه کلید مجازی از جاوا اسکریپت.
مجموعه ای از متغیرهای محیط CSS که اطلاعاتی را در مورد ظاهر صفحه کلید مجازی ارائه می دهد.
خط مشی صفحه کلید مجازی که تعیین می کند آیا صفحه کلید مجازی باید نشان داده شود یا خیر.

وضعیت فعلی

VirtualKeyboard API از Chromium 94 روی دسک‌تاپ و موبایل در دسترس است.

تشخیص ویژگی و پشتیبانی مرورگر

برای تشخیص اینکه آیا VirtualKeyboard API در مرورگر فعلی پشتیبانی می‌شود، از قطعه زیر استفاده کنید:

if ('virtualKeyboard' in navigator) {
  // The VirtualKeyboard API is supported!
}

با استفاده از VirtualKeyboard API

VirtualKeyboard API یک رابط جدید VirtualKeyboard را به شی navigator اضافه می کند.

شرکت در رفتار جدید صفحه کلید مجازی

برای اینکه به مرورگر بگویید که خودتان از انسداد صفحه‌کلید مجازی مراقبت می‌کنید، ابتدا باید با تنظیم ویژگی بولین overlaysContent روی true رفتار جدید صفحه‌کلید مجازی را انتخاب کنید.

navigator.virtualKeyboard.overlaysContent = true;

نمایش و مخفی کردن صفحه کلید مجازی

با فراخوانی متد show() آن می توانید به صورت برنامه نویسی صفحه کلید مجازی را نشان دهید. برای این کار، عنصر متمرکز باید یک کنترل فرم (مانند یک عنصر textarea ) یا یک میزبان ویرایش باشد (مثلاً با استفاده از ویژگی contenteditable ). این روش همیشه undefined برمی‌گردد، اما اگر صفحه‌کلید مجازی قبلاً نشان داده نشده بود، یک رویداد geometrychange راه‌اندازی می‌کند.

navigator.virtualKeyboard.show();

برای مخفی کردن صفحه کلید مجازی، متد hide() را فراخوانی کنید. این روش همیشه undefined برمی‌گردد، اما اگر صفحه‌کلید مجازی قبلاً نشان داده شده بود، یک رویداد geometrychange راه‌اندازی می‌کند.

navigator.virtualKeyboard.hide();

دریافت هندسه فعلی

با نگاه کردن به ویژگی boundingRect می توانید هندسه فعلی صفحه کلید مجازی را بدست آورید. ابعاد فعلی صفحه کلید مجازی را به عنوان یک شی DOMRect نشان می دهد. Inset مربوط به ویژگی های بالا، راست، پایین و/یا چپ است.

const { x, y, width, height } = navigator.virtualKeyboard.boundingRect;
console.log('Virtual keyboard geometry:', x, y, width, height);

مطلع شدن از تغییرات هندسه

هر زمان که صفحه کلید مجازی ظاهر یا ناپدید می شود، رویداد geometrychange ارسال می شود. ویژگی target رویداد شامل شی virtualKeyboard است که (همانطور که در بالا توضیح داده شد) شامل هندسه جدید صفحه کلید مجازی به عنوان یک DOMRect است.

navigator.virtualKeyboard.addEventListener('geometrychange', (event) => {
  const { x, y, width, height } = event.target.boundingRect;
  console.log('Virtual keyboard geometry changed:', x, y, width, height);
});

متغیرهای محیط CSS

VirtualKeyboard API مجموعه‌ای از متغیرهای محیطی CSS را نشان می‌دهد که اطلاعاتی در مورد ظاهر صفحه‌کلید مجازی ارائه می‌دهند. آنها شبیه به ویژگی CSS inset ، یعنی مربوط به ویژگی های بالا، راست، پایین و/یا چپ مدل شده اند.

keyboard-inset-top
keyboard-inset-right
keyboard-inset-bottom
keyboard-inset-left
keyboard-inset-width
keyboard-inset-height

ورودی‌های صفحه‌کلید مجازی شش متغیر محیطی هستند که یک مستطیل را با ورودی‌های بالا، راست، پایین و چپ آن از لبه درگاه دید تعریف می‌کنند. ورودی های عرض و ارتفاع برای ارگونومی توسعه دهندگان از سایر پایه ها محاسبه می شوند. اگر مقدار بازگشتی ارائه نشده باشد، مقدار پیش‌فرض هر صفحه کلید داخلی 0px است.

شما معمولاً از متغیرهای محیطی مانند مثال زیر استفاده می کنید:

.some-class {
  /**
   * Use a margin that corresponds to the virtual keyboard's height
   * if the virtual keyboard is shown, else use the fallback value of `50px`.
   */
  margin-block-end: env(keyboard-inset-height, 50px);
}

.some-other-class {
  /**
   * Use a margin that corresponds to the virtual keyboard's height
   * if the virtual keyboard is shown, else use the default fallback value of `0px`.
   */
  margin-block-end: env(keyboard-inset-height);
}

خط مشی صفحه کلید مجازی

گاهی اوقات وقتی یک عنصر قابل ویرایش فوکوس شده است، صفحه کلید مجازی نباید ظاهر شود. یک مثال یک برنامه صفحه گسترده است که در آن کاربر می تواند روی یک سلول ضربه بزند تا مقدار آن در فرمول سلول دیگر گنجانده شود. virtualkeyboardpolicy یک ویژگی است که کلمات کلیدی آن رشته های auto و manual هستند. وقتی روی عنصری مشخص می‌شود که یک میزبان contenteditable است، auto باعث می‌شود که عنصر قابل ویرایش مربوطه به‌طور خودکار صفحه‌کلید مجازی را هنگام فوکوس یا ضربه زدن به آن نشان دهد، و به‌دلیل تغییرات در وضعیت فعلی صفحه‌کلید مجازی، عنصر قابل ویرایش را manual فوکوس کرده و روی آن ضربه می‌زند.

<!-- Do nothing on regular focus, but show the virtual keyboard on double-click. -->
<div
  contenteditable
  virtualkeyboardpolicy="manual"
  inputmode="text"
  ondblclick="navigator.virtualKeyboard.show();"
>
  Double-click to edit.
</div>

نسخه ی نمایشی

می‌توانید VirtualKeyboard API را در یک نسخه آزمایشی در Glitch مشاهده کنید. حتماً کد منبع را بررسی کنید تا نحوه پیاده سازی آن را ببینید. در حالی که رویدادهای geometrychange را می توان در iframe embed مشاهده کرد، رفتار واقعی صفحه کلید مجازی مستلزم باز کردن نسخه نمایشی در برگه مرورگر خود است.

لینک های مفید

قدردانی

VirtualKeyboard API توسط Anupam Snigdha از مایکروسافت، با مشارکت سردبیر سابق Grisha Lyukshin و همچنین از مایکروسافت مشخص شده است.