إيماءات بيد واحدة باستخدام ميزة "الكتابة السحرية"

في الإصدار 7 من Wear OS (المستوى 37 لواجهة برمجة التطبيقات) والإصدارات الأحدث، يتيح إطار عمل الإيماءات بيد واحدة، بالإضافة إلى واجهة برمجة التطبيقات التي تشكّل جزءًا من Compose لنظام التشغيل Wear OS، للمستخدمين التفاعل مع تطبيقك بدون لمس الشاشة.

على الرغم من أنّ إطار العمل هذا متاح في البداية على أجهزة Pixel Watch (‏Pixel Watch 3 والإصدارات الأحدث)، فإنّه متاح لجميع المصنّعين الأصليين للأجهزة. من خلال استخدام واجهة برمجة التطبيقات هذه، يتم تلقائيًا توسيع نطاق توافق تطبيقك مع الإيماءات على مستوى المنظومة المتكاملة مع توسّع نطاق توافق الأجهزة.

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

الإيماءات والإجراءات المتوافقة

يتيح إطار عمل الإيماءات في Wear OS نوعَين من الإيماءات:

• الإجراء الأساسي (الضغط مرّتين): يتم ربطه بالإجراء الرئيسي على الشاشة، مثل الرد على مكالمة أو تبديل تشغيل الوسائط.
• إجراء الإغلاق (تدوير المعصم): يؤدي إلى الرجوع إلى الصفحة السابقة أو إغلاق مربّع حوار أو إلغاء طلب.

ضبط الإيماءات في Compose

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

كما هو الحال مع سلوكيات Compose العادية، يمكنك تفعيل الإيماءات بيد واحدة على عناصر واجهة المستخدم باستخدام المعدِّلات. يمكنك ضبط إيماءات تطبيقك وفقًا للإجراء المطلوب تنفيذه، سواء كان أساسيًا أو إغلاقًا، وgestureId للتنسيق مع الإعدادات المفضّلة للمستخدم على مستوى النظام، مثل معدّل عرض التلميحات وكتم الصوت بشكل متكرر. يمكنك التعبير عن هذه الإعدادات من خلال إنشاء عنصر OneHandedGestureConfiguration، وننصحك باستخدام دالة rememberOneHandedGestureConfiguration لإنشائه. تتيح لك السمة OneHandedGestureConfiguration أيضًا تحديد أولوية الإيماءة.

تتتبّع دالة rememberOneHandedGestureConfiguration سجلّ تفاعل المستخدمين في عمليات إعادة الإنشاء بدون الكشف عن حالة التطبيق. بعد أن ينشئ تطبيقك الإعدادات، يجب أن يمررها إلى Modifier.oneHandedGesture في الدالة المركّبة التفاعلية.

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

المكوّنات التفاعلية

لتفعيل الإيماءات على عنصر تحكّم تفاعلي مثل زر، أنشئ إعدادًا يحدّد OneHandedGestureAction.Primary وطبِّق المعدِّل oneHandedGesture. مرِّر MutableInteractionSource نفسه إلى كل من عنصر التحكّم والمعدِّل حتى تُصدر أحداث الإيماءات ملاحظات مرئية عن الضغط على عنصر التحكّم.

لتفعيل مؤشر الإيماءات، أنشِئ مثيلاً لـ OneHandedGestureClickIndicatorState وتذكَّره. بعد ذلك، لتشغيل الملاحظات المرئية، يمكنك استدعاء showIndicator ضمن دالة رد الاتصال onGestureAvailable التي يوفّرها المعدِّل oneHandedGesture، ما يشير إلى النظام بحدوث حدث إشارة. عند استدعاء المكوّن، يستبدل محتواه العادي لفترة وجيزة بصورة متحركة للإيماءة.

var isPlaying by remember { mutableStateOf(false) }
val onClick = { isPlaying = !isPlaying }

val gestureConfig = rememberOneHandedGestureConfiguration(
    action = OneHandedGestureAction.Primary
)
val indicatorState = remember { OneHandedGestureClickIndicatorState() }
val coroutineScope = rememberCoroutineScope()
val interactionSource = remember { MutableInteractionSource() }

Button(
    onClick = onClick,
    interactionSource = interactionSource,
    modifier = Modifier
        .fillMaxWidth()
        .oneHandedGesture(
            gestureConfiguration = gestureConfig,
            interactionSource = interactionSource,
            onGestureLabel = if (isPlaying) "pause" else "play",
            onGestureAvailable = { coroutineScope.launch { indicatorState.showIndicator() } },
            onGesture = onClick
        )
) {
    OneHandedGestureClickIndicator(
        gestureConfiguration = gestureConfig,
        state = indicatorState
    ) {
        Text(if (isPlaying) "Pause" else "Play", modifier = Modifier.fillMaxWidth())
    }
}
OneHandedGestures.kt

الحاويات القابلة للتمرير

بالنسبة إلى الشاشات أو القوائم القابلة للتمرير، أنشِئ إعدادًا يحدّد OneHandedGestureAction.Primary وطبِّق المُعدِّل oneHandedGesture على الحاوية، مع استدعاء مساعد تمرير مثل scrollDown.

لتقديم ملاحظات مرئية لإجراءات الانتقال، يمكنك استخدام OneHandedGestureScrollIndicator. يعمل هذا المكوّن كمؤشر تمرير عادي يعرض موضع التمرير، ولكن يمكنه أيضًا الإشارة إلى أنّ إيماءة التمرير متاحة للمستخدم. يتم عادةً تمرير هذا المؤشر إلى خانة scrollIndicator في ScreenScaffold، ويتم ربطه بحالة حاوية قابلة للتمرير، مثل TransformingLazyColumn. ويراقب أيضًا OneHandedGestureScrollIndicatorState لإدارة انتقالاته المرئية.

To trigger the visual feedback, call showIndicator on this state—typically inside the onGestureAvailable callback of the oneHandedGesture modifier. بمجرد تشغيله، يحل المؤشر مؤقتًا محل حالته المرئية القياسية بتسلسل رسوم متحركة للإيماءات لتنبيه المستخدم.

val scrollState = rememberTransformingLazyColumnState()
val gestureConfig = rememberOneHandedGestureConfiguration(
    action = OneHandedGestureAction.Primary,
    priority = OneHandedGesturePriority.Scrollable
)
val indicatorState = remember(gestureConfig) { OneHandedGestureScrollIndicatorState() }
val coroutineScope = rememberCoroutineScope()

ScreenScaffold(
    scrollState = scrollState,
    scrollIndicator = {
        OneHandedGestureScrollIndicator(
            gestureConfiguration = gestureConfig,
            indicatorState = indicatorState,
            scrollState = scrollState,
            modifier = Modifier.align(Alignment.CenterEnd)
        )
    }
) { contentPadding ->
    TransformingLazyColumn(
        state = scrollState,
        contentPadding = contentPadding,
        modifier = Modifier
            .fillMaxSize()
            .oneHandedGesture(
                gestureConfiguration = gestureConfig,
                onGestureLabel = "scroll",
                onGestureAvailable = {
                    coroutineScope.launch { indicatorState.showIndicator() }
                },
                onGesture = { OneHandedGestureDefaults.scrollDown(scrollState) }
            )
    ) {
        items(10) { index ->
            Text("Item $index", modifier = Modifier.padding(8.dp))
        }
    }
}
OneHandedGestures.kt

دمج إيماءات متعددة

يمكنك ضبط إيماءة التمرير وإيماءة النقر باستخدام الإجراء الأساسي نفسه من خلال إضافة gesturePriority إلى عنصر OneHandedGestureConfiguration:

• OneHandedGesturePriority.Clickable (الأعلى): يتم تخصيصها لعناصر التحكّم التفاعلية، مثل تلك التي تتضمّن النوع Button أو Card، لكي تلتقط الإيماءات عندما تكون ظاهرة على الشاشة.
• OneHandedGesturePriority.Scrollable (متوسط): يتم تخصيص هذا الإجراء للحاويات القابلة للتمرير أو التقسيم إلى صفحات، بحيث تتيح النقر على العناصر الثانوية، ولكن يتم التمرير عندما لا يظهر أي عنصر تحكّم قابل للنقر.
• OneHandedGesturePriority.Unspecified (الأدنى): أولوية غير محدّدة هذه هي القيمة التلقائية لإيماءة لا تحتوي على مجموعة priority.

من خلال ضبط السمة priority = OneHandedGesturePriority.Clickable بشكل صريح على زر داخلي والسمة priority = OneHandedGesturePriority.Scrollable على القائمة الرئيسية، يمكن للنظام عرض سلوك أولوية الإيماءات هذا. عندما يشغّل المستخدم الإجراء الأساسي من خلال الإيماءة بيد واحدة، يتم أولاً الانتقال إلى أسفل القائمة حتى يظهر الزر، ثم يتم تسجيل إجراء النقر على الزر.

اختبار الإيماءات وتصحيح أخطائها باستخدام ADB

يمكنك اختبار الإيماءات بيد واحدة على جهاز فعلي أو محاكي بدون إجراء حركات معصم فعلية باستخدام Android Debug Bridge (adb) وخدمة نظام IWearGestureService.

تفعيل محاكاة الإيماءات

قبل محاكاة الإيماءات باستخدام ADB، اضبط إعدادات جهازك وتجاوز القيود:

1. تأكَّد من أنّ جهاز Wear OS يعمل بالإصدار Wear OS 7 (المستوى 37 من واجهة برمجة التطبيقات) أو إصدار أحدث:

   adb shell getprop ro.build.version.sdk
   

2. إذا كنت تختبر على جهاز فعلي غير موضوع على معصمك أو موضوع على شاحن، يمكنك إلغاء قيد عدم الارتداء لكي يظل إطار عمل الإيماءات نشطًا:

   adb shell cmd IWearGestureService override-constraints offbody-state
   

تفعيل أحداث الإيماءات باستخدام ADB

لمحاكاة إيماءة ضمّ إصبعَين مرّتين (وهو الإجراء Primary على ساعات Pixel Watch)، نفِّذ أمر واجهة Adb التالي:

adb shell cmd IWearGestureService gesture DoublePinch

لمحاكاة إيماءة تدوير المعصم (وهي الإجراء Dismiss على ساعات Pixel Watch)، نفِّذ أمر واجهة Adb التالي:

adb shell cmd IWearGestureService gesture WristTurn

إعادة ضبط تتبُّع تلميحات الإيماءات

يتتبّع النظام سجلّ تفاعل المستخدم ويعرض تلميحات عائمة حول الإيماءات استنادًا إلى إعدادات معدّل التكرار العام (مثل دائمًا أو يوميًا). When debugging your app's gesture indicators, reset this tracking history so hints appear again for your package:

• على إصدارات أو محاكيات userdebug:

  adb shell cmd IWearGestureService hint clear <your_package_name>
  

• في إصدارات البيع بالتجزئة (user):

  على الأجهزة التجارية التي لا تتيح الوصول إلى الجذر، يتم حظر hint clear من خلال أذونات النظام. محو البيانات المحلية للتطبيق لإعادة ضبط ميزة "اكتشاف التلميحات":

  adb shell pm clear <your_package_name>
  

استعادة القيود التلقائية

لإعادة ضبط جميع عمليات تجاوز قيود تصحيح الأخطاء عند الانتهاء من الاختبار:

adb shell cmd IWearGestureService override-constraints reset

تحديد المشاكل وحلّها في حقن الإيماءات

إذا لم يتلقَّ تطبيقك إيماءات محاكاة:

1. تأكَّد من أنّ شاشة الساعة نشطة ومفعَّلة. لا يرسل إطار عمل الإيماءات الإيماءات إلى التطبيقات عندما تكون الشاشة مطفأة أو في وضع عدم النشاط. لتنشيط الشاشة باستخدام ADB، نفِّذ الأمر التالي:

   adb shell input keyevent KEYCODE_WAKEUP
   

2. تحقَّق مما إذا كان تطبيقك مسجَّلاً كمشترك نشط في الإيماءات ويحتفظ حاليًا بتركيز النافذة:

   adb shell cmd IWearGestureService get-active-gestures -readable
   

   عندما تكون شاشة الإيماءات في تطبيقك في المقدّمة وتكون الشاشة في الوضع النشط، يعرض هذا الأمر [DoublePinch] أو [DoublePinch, WristTurn]. إذا تم عرض قائمة فارغة ([])، تحقَّق مما إذا كانت نافذتك في المقدّمة أو إذا كانت القيود المفروضة على عدم ارتداء الجهاز تحظر التفعيل.

3. افحص حالة خدمة الإيماءات الداخلية ورموز المشتركين النشطين:

   adb shell dumpsys IWearGestureService
   

مراجع إضافية

للحصول على إرشادات التصميم حول حالات وأماكن استخدام الإيماءات بيد واحدة، يُرجى الاطّلاع على الإيماءات بيد واحدة.