تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إمكانية تحكُّم كاملة باستخدام واجهة برمجة التطبيقات VirtualKeyboard 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;

إظهار لوحة المفاتيح الافتراضية وإخفاؤها

يمكنك عرض لوحة المفاتيح الافتراضية آليًا من خلال طلب إجراء show() الخاص بها. لكي يعمل هذا الإجراء، يجب أن يكون العنصر الذي تم التركيز عليه عنصر تحكّم في النموذج (مثل عنصر textarea) أو مضيف تعديل (على سبيل المثال، باستخدام سمة contenteditable ). دائمًا ما تعرض الطريقة القيمة undefined ولكنها تؤدّي إلى حدث geometrychange إذا لم تظهر لوحة المفاتيح الافتراضية في السابق.

navigator.virtualKeyboard.show();

لإخفاء لوحة المفاتيح الافتراضية، يمكنك طلب الطريقة hide(). دائمًا ما تعرض الطريقة القيمة undefined ولكنها تؤدّي إلى حدث geometrychange إذا تم عرض لوحة المفاتيح الافتراضية سابقًا.

navigator.virtualKeyboard.hide();

الحصول على الشكل الهندسي الحالي

يمكنك الحصول على الشكل الهندسي الحالي للوحة المفاتيح الافتراضية من خلال الاطّلاع على السمة boundingRect. ويعرض الأبعاد الحالية للوحة المفاتيح الافتراضية على شكل كائن DOMRect. تتطابق العناصر المضمّنة مع السمات top وright وbottom و/أو left.

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

تعرض واجهة برمجة تطبيقات Virtualلوحة المفاتيح مجموعة من متغيرات بيئة 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>

عرض توضيحي

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

روابط مفيدة

الشكر والتقدير

حدّد Anupam Snigdha من Microsoft واجهة برمجة التطبيقات VirtualKeyboard API، بمساهمة من المحرِّر السابق Grisha Lyukshin، من Microsoft أيضًا.