דף זה תורגם על ידי 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). השיטה תמיד מחזירה את הערך 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.