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

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

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

ملاحظة: يحتفظ Wear OS 3.0 بزرين لنظام التشغيل، في حين يحتفظ Wear OS 2.0 بزر واحد فقط. يقلل هذا من عدد الأزرار التي يمكنك تعيين إجراءات لها.

للتعرّف على حالات الاستخدام المناسبة واعتبارات التصميم، يمكنك مراجعة مبادئ تصميم نظام التشغيل Wear OS.

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

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

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

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

عدد الأزرار

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

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

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

زرّ الحدث الرئيسي
زر متعدد الوظائف 1 KEYCODE_STEM_1
زر متعدد الوظائف 2 KEYCODE_STEM_2
زر متعدد الوظائف 3 KEYCODE_STEM_3

يعرض الرمز في المثال التالي طريقة معرفة عدد الأزرار المتاحة:

Kotlin

val count = WearableButtons.getButtonCount(context)

if (count > 1) {
    // There are multifunction buttons available
}

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

if (buttonInfo == null) {
    // KEYCODE_STEM_1 is unavailable
} else {
    // KEYCODE_STEM_1 is present on the device
}

Java

int count = WearableButtons.getButtonCount(context);

if (count > 1) {
  // There are multifunction buttons available
}

WearableButtons.ButtonInfo buttonInfo =
  WearableButtons.getButtonInfo(activity, KeyEvent.KEYCODE_STEM_1);

if (buttonInfo == null) {
  // KEYCODE_STEM_1 is unavailable
} else {
  // KEYCODE_STEM_1 is present on the device
}

الضغط على أزرار المقبض

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

  • KEYCODE_STEM_1
  • KEYCODE_STEM_2
  • KEYCODE_STEM_3

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

للتعامل مع الضغط على الزر، استخدِم طريقة onKeyDown().

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

Kotlin

// Activity
override fun onKeyDown(keyCode: Int, event: KeyEvent): Boolean {
    return if (event.repeatCount == 0) {
        when (keyCode) {
            KeyEvent.KEYCODE_STEM_1 -> {
                // Do stuff
                true
            }
            KeyEvent.KEYCODE_STEM_2 -> {
                // Do stuff
                true
            }
            KeyEvent.KEYCODE_STEM_3 -> {
                // Do stuff
                true
            }
            else -> {
                super.onKeyDown(keyCode, event)
            }
        }
    } else {
        super.onKeyDown(keyCode, event)
    }
}

Java

@Override
// Activity
public boolean onKeyDown(int keyCode, KeyEvent event){
  if (event.getRepeatCount() == 0) {
    if (keyCode == KeyEvent.KEYCODE_STEM_1) {
      // Do stuff
      return true;
    } else if (keyCode == KeyEvent.KEYCODE_STEM_2) {
      // Do stuff
      return true;
    } else if (keyCode == KeyEvent.KEYCODE_STEM_3) {
      // Do stuff
      return true;
    }
  }
  return super.onKeyDown(keyCode, event);
}

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

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

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

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