דף זה תורגם על ידי Cloud Translation API.

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

Thomas Steiner

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

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

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

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

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

navigator.virtualKeyboard.overlaysContent = true;

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

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

navigator.virtualKeyboard.show();

כדי להסתיר את המקלדת הווירטואלית, צריך להפעיל את השיטה hide(). ה-method תמיד מחזירה 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.