الأزرار الخارجية

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

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

ساعة مزوّدة بأزرار جانبية متعددة يحدّد النظام أحد الأزرار كزر متعدد الوظائف.
الشكل 1. تطبيق لياقة بدنية على Wear OS يعرض أزرارًا متعددة الوظائف

للاطّلاع على حالات الاستخدام المناسبة واعتبارات التصميم، يُرجى الرجوع إلى مبادئ تصميم Wear OS.

يوضّح هذا المستند كيفية استرداد معلومات حول الأزرار المتعدّدة الوظائف المتاحة على الجهاز وكيفية معالجة ضغطات الأزرار.

البيانات الوصفية للأزرار

للحصول على معلومات إضافية حول الأزرار على أحد الأجهزة، استخدِم واجهة برمجة التطبيقات المحدّدة في مكتبة Wear Input AndroidX. أضِف التبعية التالية في ملف build.gradle الخاص بوحدة تطبيقك:

dependencies {
implementation "androidx.wear:wear-input:1.2.0"
}

عدد الأزرار

لتحديد عدد الأزرار المتاحة على الجهاز، استخدِم طريقة WearableButtons.getButtonCount(). تتضمّن هذه الطريقة زر التشغيل، لذا إذا كانت الطريقة تعرض قيمة أكبر من واحد، يعني ذلك أنّ هناك أزرارًا متعدّدة الوظائف متاحة للاستخدام. للحصول على عدد دقيق لأزرار الوظائف المتعددة القابلة للتخصيص، اطرح واحدًا من العدد، لأنّ الزر الأول هو دائمًا زر التشغيل.

رموز المفاتيح للضغطات على الأزرار

يتم ربط كل زر بثابت int من الفئة KeyEvent، كما هو موضّح في الجدول التالي:

زرّ KeyEvent
الزر متعدد الوظائف 1 KEYCODE_STEM_1
زر الوظائف المتعددة 2 KEYCODE_STEM_2
الزرّ المتعدّد الوظائف 3 KEYCODE_STEM_3

يوضّح نموذج الرمز البرمجي التالي كيفية الحصول على عدد الأزرار المتاحة:

val count = WearableButtons.getButtonCount(context)

if (count > 1) {
    Log.d(TAG, "More than one button available")
}

val buttonInfo = WearableButtons.getButtonInfo(
    activity,
    KeyEvent.KEYCODE_STEM_1
)

if (buttonInfo == null) {
    // KEYCODE_STEM_1 is unavailable
    Log.d(TAG, "KEYCODE_STEM_1 not available")
} else {
    // KEYCODE_STEM_1 is present on the device
    Log.d(TAG, "KEYCODE_STEM_1 is present on the device")
}
HardwareButtonsActivity.kt

التعامل مع الضغطات على الأزرار

هناك عدد من رموز مفاتيح الأزرار المحتملة التي يمكن لتطبيقك التعامل معها:

  • KEYCODE_STEM_1.
  • KEYCODE_STEM_2.

يمكن لتطبيقك تلقّي رموز المفاتيح هذه وتحويلها إلى إجراءات محدّدة داخل التطبيق.

للتعامل مع ضغطة زر، نفِّذ الطريقة onKeyDown() ‎.

على سبيل المثال، يستجيب هذا التنفيذ لضغطة زر للتحكّم في الإجراءات داخل تطبيق:

override fun onKeyDown(keyCode: Int, event: KeyEvent?): Boolean {
    return if (event?.repeatCount == 0) {
        when (keyCode) {
            KeyEvent.KEYCODE_STEM_1 -> {
                Log.d(TAG, "KEYCODE_STEM_1 pressed")
                true
            }
            KeyEvent.KEYCODE_STEM_2 -> {
                Log.d(TAG, "KEYCODE_STEM_2 pressed")
                true
            }
            else -> {
                super.onKeyDown(keyCode, event)
            }
        }
    } else {
        super.onKeyDown(keyCode, event)
    }
}
HardwareButtonsActivity.kt

تحديد مواضع الأزرار

توفّر مكتبة AndroidX طريقتَين تصفان موضع الزر:

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