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

اعتبارًا من Wear OS 7 (مستوى واجهة برمجة التطبيقات 37)، يتيح إطار عمل الإيماءات بيد واحدة، بالإضافة إلى واجهة برمجة تطبيقات جزء من Compose for 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 لإدارة انتقالاته المرئية.

لتشغيل الملاحظات المرئية، استدعِ showIndicator في هذه الحالة، عادةً ضِمن معاودة الاتصال onGestureAvailable للمعدِّل oneHandedGesture. بعد تشغيل المؤشر، يستبدل حالته المرئية العادية مؤقتًا بتسلسل حركة إيماءة لتنبيه المستخدم.

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.

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

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

adb shell cmd sensorservice set-off-body-state 0

تشغيل أحداث الإيماءات باستخدام ADB

لمحاكاة إيماءة الضغط بإصبعَين مرّتين (وهي إجراء Primary على ساعات Pixel)، شغِّل أمر ADB shell التالي:

adb shell cmd IWearGestureService gesture 1

لمحاكاة إيماءة تدوير المعصم (وهي إجراء Dismiss على ساعات Pixel)، شغِّل أمر ADB shell التالي:

adb shell cmd IWearGestureService gesture 2

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

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

adb shell cmd IWearGestureService hint clear <your_package_name>

لإعادة ضبط حالة المستشعر خارج الجسم عند الانتهاء من الاختبار:

adb shell cmd sensorservice reset-off-body-state

مراجع إضافية

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