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

Thomas Steiner

תמיכה בדפדפן

  • 94
  • 94
  • x
  • x

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

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

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

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

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

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

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

אפשר להשתמש ב-VirtualKeyboard API מ-Chromium 94 במחשב ובנייד.

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

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

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();

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

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

אישורים

ממשק ה-API של VirtualKeyboard צוין על ידי Anupam Snigdha מ-Microsoft, עם תרומות של העורכת לשעבר גרישה ליוקשין (Girisha Lyukshin), בדומה ל-Microsoft, תמונה ראשית (Hero) מאת @freestocks מופעל ביטול הפתיחה.