إمكانية تحكُّم كاملة باستخدام واجهة برمجة التطبيقات VirtualKeyboard API

توماس شتاينر

دعم المتصفح

  • 94
  • 94
  • x
  • x

تحتوي الأجهزة مثل الأجهزة اللوحية أو الهواتف المحمولة عادةً على لوحة مفاتيح افتراضية لكتابة النص. على عكس لوحة المفاتيح الخارجية التي تكون دائمًا كما هي، تظهر لوحة المفاتيح الافتراضية وتختفي بناءً على إجراءات المستخدم ويمكن أن تتكيّف معها أيضًا بشكل ديناميكي، بناءً على السمة inputmode مثلاً.

ويتم توفير هذه المرونة مقابل السعر الذي يجب أن يتم إعلامه محرك تخطيط المتصفّح بتوفّر لوحة المفاتيح الافتراضية وربما يكون بحاجة إلى ضبط تنسيق المستند لتعويض ذلك. على سبيل المثال، قد تحجب لوحة المفاتيح الافتراضية حقل الإدخال الذي يوشك المستخدم على الكتابة فيه، لذا على المتصفّح عرضه.

تقليديًا، تعاملت المتصفحات مع هذا التحدي من تلقاء نفسها، إلا أن التطبيقات الأكثر تعقيدًا قد تتطلب مزيدًا من التحكم في سلوك المتصفح. تشمل الأمثلة أجهزة الجوّال متعددة الشاشات التي سينتج عندها الأسلوب التقليدي قيمة شاشة "مُهدورة" إذا كانت لوحة المفاتيح الافتراضية معروضة في جزء واحد من الشاشة فقط، ولكن مع تقليص إطار العرض المتاح على كلتا الشاشتين على أي حال. توضّح الصورة أدناه كيف يمكن استخدام واجهة برمجة التطبيقات VirtualKeyboard API لتحسين تنسيق المستند ديناميكيًا لتعويض توفُّر لوحة المفاتيح الافتراضية.

ينتج عن النهج التقليدي

في مثل هذه الحالات، يأتي دور واجهة برمجة تطبيقات VirtualKeyboard. ويتألف من ثلاثة أجزاء:

  • واجهة VirtualKeyboard في الكائن navigator للوصول البرمجي إلى لوحة المفاتيح الافتراضية من JavaScript.
  • يشير ذلك المصطلح إلى مجموعة من متغيرات بيئة CSS التي توفّر معلومات حول شكل لوحة المفاتيح الافتراضية.
  • يشير ذلك المصطلح إلى سياسة لوحة المفاتيح الافتراضية التي تحدِّد ما إذا كان يجب عرض لوحة المفاتيح الافتراضية.

الوضع الحالي

تتوفّر واجهة برمجة التطبيقات VirtualKeyboard API في الإصدار 94 من Chromium على أجهزة الكمبيوتر المكتبي والأجهزة الجوّالة.

اكتشاف الميزات ودعم المتصفِّح

لاكتشاف ما إذا كانت واجهة برمجة تطبيقات VirtualKeyboard API متاحة في المتصفِّح الحالي، استخدِم المقتطف التالي:

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

استخدام واجهة برمجة تطبيقات VirtualKeyboard

تضيف واجهة برمجة التطبيقات 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. تتوافق القائمة الداخلية مع الخصائص في الجزء العلوي و/أو الأيمن و/أو السفلي و/أو الأيسر.

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 التي توفّر معلومات حول مظهر لوحة المفاتيح الافتراضية. ويتم تصميمها على غرار سمة inset في CSS، أي أنّها تتوافق مع السمات في الجزء العلوي أو الأيمن أو السفلي أو الأيسر.

  • 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 أثناء العمل من خلال عرض توضيحي على تطبيق Glitch. احرص على استكشاف رمز المصدر لمعرفة كيفية تنفيذه. على الرغم من إمكانية ملاحظة أحداث geometrychange في إطار iframe المضمّن، يتطلب سلوك لوحة المفاتيح الافتراضية فتح العرض التوضيحي في علامة تبويب المتصفّح الخاصة به.

شكر وتقدير

تم تحديد واجهة برمجة التطبيقات VirtualKeyboard API بواسطة "أنوبام سنيغدها" من Microsoft، بالإضافة إلى مساهمات من المحرِّرة السابقة "غريشا ليوكشين"، وكذلك من Microsoft. صورة رئيسية من @freestocks على Unsplash