حرکات یک دستی با Compose

با شروع از Wear OS 7 (سطح API 37)، یک چارچوب حرکات یک دستی، به همراه یک API که بخشی از Compose for Wear OS است، به کاربران اجازه می‌دهد بدون لمس با برنامه شما تعامل داشته باشند.

اگرچه این چارچوب در ابتدا در دستگاه‌های پیکسل واچ (پیکسل واچ ۳ و بالاتر) پشتیبانی می‌شد، اما اکنون برای همه تولیدکنندگان اصلی تجهیزات (OEM) در دسترس است. با اتخاذ این API، پشتیبانی از ژست‌های حرکتی برنامه شما با گسترش پشتیبانی سخت‌افزاری، به طور خودکار در سراسر اکوسیستم مقیاس‌پذیر می‌شود.

برای کمک به کاربران در کشف حرکات موجود بدون شلوغ کردن رابط کاربری، چارچوب Wear OS نشانگرهای حرکتی متحرک را ارائه می‌دهد. این نکات بصری محل انجام یک حرکت را برجسته می‌کنند، در حالی که سیستم به طور خودکار آهنگ نمایش و فرکانس بی‌صدا کردن آنها را مطابق با ترجیحات کاربر مدیریت می‌کند.

حرکات و اقدامات پشتیبانی شده

چارچوب حرکات Wear OS از دو نوع حرکت پشتیبانی می‌کند:

• اقدام اصلی (دو بار نیشگون گرفتن): به اقدام اصلی روی صفحه نمایش، مانند پاسخ دادن به تماس یا تغییر وضعیت پخش رسانه، اشاره می‌کند.
• لغو اقدام (چرخاندن مچ): به پیمایش رو به عقب، رد کردن یک کادر محاوره‌ای یا لغو یک درخواست اشاره دارد.

پیکربندی حرکات در نوشتن

اگرچه API حرکات یک دستی می‌تواند رابط کاربری شما را بهبود بخشد، اما باید در نظر داشته باشید که برخی از سخت‌افزارها و تولیدکنندگان اصلی تجهیزات (OEM) از این حرکات پشتیبانی نمی‌کنند. اگر API تشخیص دهد که برنامه شما روی یکی از این دستگاه‌های پشتیبانی نشده اجرا می‌شود، کتابخانه به طور خودکار بدون تأثیر بر تعاملات لمسی استاندارد، عملیات را متوقف می‌کند.

همانند رفتارهای استاندارد نوشتن، شما با استفاده از اصلاح‌کننده‌ها ، حرکات تک‌دستی را روی عناصر رابط کاربری فعال می‌کنید. حرکات برنامه خود را بر اساس عملی که باید انجام شود - یا اصلی یا رد کردن - و یک gestureId برای هماهنگی با تنظیمات کاربر در سطح سیستم، مانند آهنگ نمایش اشاره و بی‌صدا کردن فرکانس، پیکربندی می‌کنید. شما این پیکربندی را با ایجاد یک شیء OneHandedGestureConfiguration بیان می‌کنید. توصیه می‌کنیم از تابع rememberOneHandedGestureConfiguration برای ایجاد آن استفاده کنید. OneHandedGestureConfiguration همچنین جایی است که می‌توانید اولویت حرکات را ارائه دهید.

تابع rememberOneHandedGestureConfiguration تاریخچه تعامل کاربر را در طول recompositionها بدون افشای وضعیت برنامه، ردیابی می‌کند. هنگامی که برنامه شما پیکربندی را ایجاد کرد، باید پیکربندی را به Modifier.oneHandedGesture در interactive composable شما منتقل کند.

برای کمک به کاربران در کشف حرکات موجود، این کتابخانه متد 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 (سطح API 37) و بالاتر استفاده می‌کند.
2. اگر روی یک دستگاه فیزیکی که روی مچ دست یا شارژر نیست آزمایش می‌کنید، حالت حسگر خارج از بدن را لغو کنید تا دستگاه فعال بماند:

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

فعال کردن رویدادهای حرکتی با استفاده از ADB

برای شبیه‌سازی ژست Double Pinch (عمل Primary )، دستور ADB shell زیر را اجرا کنید:

adb shell cmd IWearGestureService gesture 1

برای شبیه‌سازی ژست چرخش مچ (عمل Dismiss )، دستور ADB shell زیر را اجرا کنید:

adb shell cmd IWearGestureService gesture 2

تنظیم مجدد ردیابی اشاره حرکتی

سیستم تاریخچه تعامل کاربر را ردیابی می‌کند و بر اساس تنظیمات کلی (مانند Always یا Daily ) نکات حرکتی شناور را نمایش می‌دهد. هنگام اشکال‌زدایی نشانگرهای حرکتی برنامه خود، این تاریخچه ردیابی را مجدداً تنظیم کنید تا نکات برای بسته شما دوباره ظاهر شوند:

adb shell cmd IWearGestureService hint clear <your_package_name>

برای تنظیم مجدد وضعیت حسگر خارج از بدن پس از اتمام آزمایش:

adb shell cmd sensorservice reset-off-body-state

منابع اضافی

برای راهنمایی طراحی در مورد زمان و مکان استفاده از حرکات یک دستی، به حرکات یک دستی مراجعه کنید.