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

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

Thomas Steiner

دعم المتصفح

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

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

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

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

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

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

الوضع الحالي

تتوفّر واجهة برمجة تطبيقات Virtualلوحة المفاتيح على Chromium 94 على أجهزة الكمبيوتر المكتبي والأجهزة الجوّالة.

رصد الميزات والتوافق مع المتصفحات

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

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

استخدام واجهة برمجة تطبيقات Virtualلوحة المفاتيح

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

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

عرض توضيحي

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

روابط مفيدة

شكر وتقدير

وقد حدد "أنوبام سنيجدها" من Microsoft واجهة برمجة تطبيقات Virtualلوحة المفاتيح، مع مساهمات من والمحرِّر السابق "غريشا ليوكشين" ومن فريق Microsoft صورة رئيسية بواسطة @freestocks إزالة البداية