שליטה מלאה עם Virtual Keyboard API

תמיכה בדפדפן

  • Chrome: 94.
  • קצה: 94.
  • Firefox: לא נתמך.
  • Safari: לא נתמך.

מקור

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

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

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

הגישה המסורתית

במצבים כאלה, ה-VirtualKeyboard API נכנס לתמונה. הוא מורכב משלושה חלקים:

  • ממשק VirtualKeyboard באובייקט navigator לגישה פרוגרמטית למקלדת הווירטואלית מ-JavaScript.
  • קבוצה של משתני סביבה ב-CSS שמספקים מידע על המראה של המקלדת הווירטואלית.
  • מדיניות של מקלדת וירטואלית שקובעת אם צריך להציג את המקלדת הווירטואלית.

הסטטוס הנוכחי

VirtualKeyboard API זמין מ-Chromium 94 במחשבים ובניידים.

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

כדי לבדוק אם יש תמיכה ב-VirtualKeyboard API בדפדפן הנוכחי, משתמשים בקטע הקוד הבא:

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

שימוש ב-VirtualKeyboard API

ה-API VirtualKeyboard מוסיף ממשק חדש VirtualKeyboard לאובייקט navigator.

איך מאשרים את ההתנהגות החדשה של המקלדת הווירטואלית

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

navigator.virtualKeyboard.overlaysContent = true;

הצגה והסתרה של המקלדת הווירטואלית

אפשר להציג את המקלדת הווירטואלית באופן פרוגרמטי על ידי קריאה ל-method‏ show() שלה. כדי שההגנה הזו תפעל, הרכיב שמתמקדים בו צריך להיות פקד טופס (כמו רכיב textarea) או להיות מארח עריכה (לדוגמה, באמצעות המאפיין contenteditable). השיטה תמיד מחזירה את הערך undefined, אבל היא מפעילה אירוע geometrychange אם המקלדת הווירטואלית לא הוצגה בעבר.

navigator.virtualKeyboard.show();

כדי להסתיר את המקלדת הווירטואלית, קוראים ל-method‏ hide(). השיטה תמיד מחזירה את הערך undefined, אבל היא מפעילה אירוע geometrychange אם המקלדת הווירטואלית הוצגה בעבר.

navigator.virtualKeyboard.hide();

אחזור הגיאומטריה הנוכחית

כדי לקבל את הגיאומטריה הנוכחית של המקלדת הווירטואלית, אפשר לעיין בנכס boundingRect. הוא חושף את המאפיינים הנוכחיים של המקלדת הווירטואלית כאובייקט DOMRect. החלק הפנימי תואם למאפיינים 'למעלה', 'ימין', 'למטה' ו/או 'שמאל'.

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, כלומר תואמים לנכסים top,‏ right,‏ bottom ו-/או left.

  • 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. כשמציינים את הפרמטר auto ברכיב שהוא מארח של contenteditable, הרכיב המתאים שניתן לעריכה מציג באופן אוטומטי את המקלדת הווירטואלית כשממקדים אותו או מקישים עליו. הפרמטר 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, אבל כדי לראות את ההתנהגות בפועל של המקלדת הווירטואלית צריך לפתוח את הדמו בכרטיסייה משלו בדפדפן.

תודות

Anupam Snigdha מ-Microsoft כתב את המפרט של VirtualKeyboard API, עם תרומות מהעורך לשעבר Grisha Lyukshin, גם הוא מ-Microsoft.