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

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

Thomas Steiner

توافق المتصفّح

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

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

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

يؤدّي النهج التقليدي إلى

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

واجهة VirtualKeyboard على عنصر navigator للوصول الآلي إلى ال keyboard الافتراضية من 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

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

روابط مفيدة

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

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