با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
برخی از دستگاه‌های Wear OS حاوی یک دکمه فیزیکی چرخان کناری هستند. وقتی کاربر دکمه را می‌چرخاند، نمای فعلی برنامه شما را به سمت بالا یا پایین حرکت می‌دهد. به این نوع ورودی، ورودی چرخشی می گویند.
توجه: این راهنما در درجه اول به مدیریت ورودی چرخشی با استفاده از رابط های کاربری مبتنی بر View اشاره دارد. برای اطلاعات بیشتر در مورد مدیریت ورودی چرخشی با استفاده از Compose for Wear OS، ورودی چرخشی در نوشتن را ببینید.
بسیاری از کانتینرهای قابل پیمایش، مانند ScrollView ، ListView ، HorizontalScrollView ، و WearableRecyclerView ، اگر فوکوس داشته باشند بدون نیاز به کد مخصوص Wear OS، از ورودی چرخشی پشتیبانی می کنند. داشتن فوکوس یک پیش نیاز مهم است، زیرا در اندروید 9 (سطح API 28) و بالاتر، نماها به طور ضمنی فوکوس دریافت نمی کنند.
روی بهترین شیوه ها تمرکز کنید
برای پاسخ به رویدادهای ورودی چرخشی، یک ظرف قابل پیمایش باید فوکوس داشته باشد. رویدادهای ورودی چرخشی سلسله مراتب نمایش را حباب نمی کند. اگر نمای متمرکزی وجود نداشته باشد، یا اگر نمای متمرکز از View.onGenericMotionEvent()false برگرداند، رویداد به Activity.onGenericMotionEvent() ارسال می‌شود.
موارد زیر بهترین روش‌های پاسخگویی به رویدادهای ورودی چرخشی هستند:
به خاطر داشته باشید که به‌طور پیش‌فرض، راه‌اندازی یک فعالیت یا حتی ضربه زدن روی یک نما، به آن فوکوس نمی‌دهد، حتی اگر قابل فوکوس باشد. برای اینکه نمای خود را فوکوس کنید، نما باید از تگ <requestFocus /> استفاده کند یا به صورت دستی View.requestFocus() فراخوانی کند.
نماهای قابل پیمایش سفارشی را با استفاده از android:focusable="true" و android:focusableInTouchMode="true" به عنوان قابل فوکوس علامت گذاری کنید.
اگر نمای قابل پیمایش شما بعد از Activity.onCreate() ضمیمه شده است — به عنوان مثال، منتظر اتمام درخواست شبکه قبل از ساختن رابط کاربری خود هستید، پس از پیوست کردن آن requestFocus() فراخوانی کنید.
اگر نمای قابل پیمایش شما در ابتدا INVISIBLE یا GONE است، هنگامی که آن را روی VISIBLE تنظیم کردید requestFocus() را فراخوانی کنید.
اگر فعالیت شما حاوی چندین نمای قابل پیمایش است، یکی را برای تمرکز با استفاده از تگ <requestFocus /> انتخاب کنید. پیمایش تو در تو با دکمه کناری چرخان پشتیبانی نمی شود.
اگر رابط کاربری شما حاوی نمای دیگری است که هنگام تعامل کاربر با آن فوکوس می‌کند - به عنوان مثال، یک InputText ، به کاربر راهی برای بازگرداندن فوکوس به نمای قابل پیمایش در صورت از دست دادن فوکوس با گوش دادن به ضربه‌های روی نمای پیمایشی و فراخوانی requestFocus() بدهید. requestFocus() در پاسخ.
رفتار چرخشی سفارشی
اگر نمای قابل پیمایش شما به طور طبیعی از پیمایش ورودی چرخشی پشتیبانی نمی‌کند، یا اگر می‌خواهید از ورودی چرخشی خود برای چیزی غیر از پیمایش استفاده کنید - مانند بزرگ‌نمایی و کوچک‌نمایی یا چرخاندن شماره‌گیرها - می‌توانید رویدادهای اسکرول را خودتان مدیریت کنید. به یاد داشته باشید که مطمئن شوید که دیدگاه شما تمرکز می کند، در غیر این صورت رویدادها از بین نمی روند.
myView.setOnGenericMotionListener{v,ev->
if(ev.action==MotionEvent.ACTION_SCROLL&&
ev.isFromSource(InputDeviceCompat.SOURCE_ROTARY_ENCODER)){// Don't forget the negation herevaldelta=-ev.getAxisValue(MotionEventCompat.AXIS_SCROLL)*ViewConfigurationCompat.getScaledVerticalScrollFactor(ViewConfiguration.get(context),context)// Swap these axes to scroll horizontally insteadv.scrollBy(0,delta.roundToInt())true}else{false}}
جاوا
myView.setOnGenericMotionListener(newView.OnGenericMotionListener(){@OverridepublicbooleanonGenericMotion(Viewv,MotionEventev){if(ev.getAction()==MotionEvent.ACTION_SCROLL&&
ev.isFromSource(InputDeviceCompat.SOURCE_ROTARY_ENCODER)){// Don't forget the negation herefloatdelta=-ev.getAxisValue(MotionEventCompat.AXIS_SCROLL)*ViewConfigurationCompat.getScaledVerticalScrollFactor(ViewConfiguration.get(context),context);// Swap these axes to scroll horizontally insteadv.scrollBy(0,Math.round(delta));returntrue;}returnfalse;}});
با استفاده از شبیه ساز تست کنید
از شبیه ساز Android برای شبیه سازی اسکرول ورودی چرخشی در دستگاه Wear استفاده کنید. برنامه Wear خود را روی شبیه ساز اجرا کنید تا پروژه خود را اجرا کنید یا یک فایل APK را روی شبیه ساز بکشید تا آن را نصب کنید.
برای تست ورودی چرخشی در شبیه ساز:
از مدیر SDK ، از برگه ابزارهای SDK برای دریافت شبیه ساز اندروید 26.0.3 یا بالاتر استفاده کنید.
روی منوی سرریز سه نقطه در پایین نوار ابزار شبیه ساز کلیک کنید. روی زبانه ورودی چرخشی در پنجره جدید کلیک کنید تا رابط ورودی چرخشی باز شود و اسکرول ورودی چرخشی را امتحان کنید.
ویدئوی زیر ورودی چرخشی در شبیه ساز را نشان می دهد:
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Rotary input\n\nSome Wear OS devices contain a physical *rotating side button* . When the user turns the\nbutton, it scrolls your app's current view up or down. This type of input is called\n*rotary input*.\n\n**Note:** This guide refers primarily to handling rotary input using\nView-based UIs. For more information on handling rotary input using Compose for Wear OS, see\n[Rotary input on Compose](/training/wearables/compose/rotary-input).\n\nMany scrollable containers, like\n[ScrollView](/reference/android/widget/ScrollView),\n[ListView](/reference/android/widget/ListView),\n[HorizontalScrollView](/reference/android/widget/HorizontalScrollView),\nand [WearableRecyclerView](/reference/androidx/wear/widget/WearableRecyclerView),\nsupport rotary input if they have focus without requiring any Wear\nOS-specific code.\nHaving focus is an important prerequisite, because on Android 9 (API level\n28) and higher, views don't implicitly receive focus.\n\nFocus best practices\n--------------------\n\n\nTo respond to rotary input events, a scrollable container must have focus.\nRotary input events don't bubble up the view\nhierarchy. If there is no focused view, or if the focused view returns `false` from\n[View.onGenericMotionEvent()](/reference/android/view/View#onGenericMotionEvent(android.view.MotionEvent)),\nthen the event is sent to\n[Activity.onGenericMotionEvent()](/reference/android/app/Activity#onGenericMotionEvent(android.view.MotionEvent)).\n\n\nThe following are best practices around responding to rotary input events:\n\n- Bear in mind that, by default, launching an activity or even tapping on a view does not give it focus, even if it is focusable. To give your view focus, the view must use the [<requestFocus /\u003e](/guide/topics/resources/layout-resource) tag or manually call [View.requestFocus()](/reference/android/view/View#requestFocus()).\n- Mark custom scrollable views as focusable using both `android:focusable=\"true\"` and `android:focusableInTouchMode=\"true\"`.\n- If your scrollable view is attached after [Activity.onCreate()](/reference/android/app/Activity#onCreate(android.os.Bundle))---for example, waiting for a network request to finish before building your UI, call `requestFocus()` after attaching it.\n- If your scrollable view is initially [INVISIBLE](/reference/android/view/View#INVISIBLE) or [GONE](/reference/android/view/View#GONE), call `requestFocus()` when you set it to [VISIBLE](/reference/android/view/View#VISIBLE).\n- If your activity contains multiple scrollable views, choose one to focus using the [<requestFocus /\u003e](/guide/topics/resources/layout-resource) tag. Nested scrolling is not supported with the rotating side button.\n- If your UI contains some other view that takes focus when the user interacts with it---for example, an `InputText`, give the user a way to restore focus to the scrollable view if it loses focus by listening for taps on the scrollable view and calling `requestFocus()` in response.\n\nCustom rotating behavior\n------------------------\n\nIf your scrollable view doesn't natively support rotary input scrolling, or if you want to\nuse your rotary input for something other than scrolling---such as to\nzoom in and out or to turn dials---you can handle the scroll events\nyourself. Remember to make sure your view gains focus, otherwise\nthe events will not come through.\n\nThe following code snippet shows how to use [MotionEvent](/reference/android/view/MotionEvent),\n[InputDeviceCompat](/reference/kotlin/androidx/core/view/InputDeviceCompat),\nand [ViewConfigurationCompat](/reference/androidx/core/view/ViewConfigurationCompat)\nto add custom scrolling to your view: \n\n### Kotlin\n\n```kotlin\nmyView.setOnGenericMotionListener { v, ev -\u003e\n if (ev.action == MotionEvent.ACTION_SCROLL &&\n ev.isFromSource(InputDeviceCompat.SOURCE_ROTARY_ENCODER)\n ) {\n // Don't forget the negation here\n val delta = -ev.getAxisValue(MotionEventCompat.AXIS_SCROLL) *\n ViewConfigurationCompat.getScaledVerticalScrollFactor(\n ViewConfiguration.get(context), context\n )\n // Swap these axes to scroll horizontally instead\n v.scrollBy(0, delta.roundToInt())\n true\n } else {\n false\n }\n}\n```\n\n### Java\n\n```java\nmyView.setOnGenericMotionListener(new View.OnGenericMotionListener() {\n @Override\n public boolean onGenericMotion(View v, MotionEvent ev) {\n if (ev.getAction() == MotionEvent.ACTION_SCROLL &&\n ev.isFromSource(InputDeviceCompat.SOURCE_ROTARY_ENCODER)\n ) {\n // Don't forget the negation here\n float delta = -ev.getAxisValue(MotionEventCompat.AXIS_SCROLL) *\n ViewConfigurationCompat.getScaledVerticalScrollFactor(\n ViewConfiguration.get(context), context\n );\n\n // Swap these axes to scroll horizontally instead\n v.scrollBy(0, Math.round(delta));\n\n return true;\n }\n return false;\n }\n});\n```\n\nTest using an emulator\n----------------------\n\nUse the [Android Emulator](/studio/run/emulator#about) to simulate rotary input\nscrolling on a Wear device. Launch your Wear app on the emulator to run\nyour project or drag an\nAPK file onto the emulator to install it.\n\nTo test the rotary input on the emulator:\n\n1. From the [SDK manager](/tools/help/sdk-manager), use the **SDK tools** tab to get Android Emulator 26.0.3 or higher.\n2. In Android Studio, select **Tools \\\u003e\n Android \\\u003e AVD Manager** . [Create a new Wear device](/studio/run/managing-avds#createavd) with API 25 or higher.\n3. [Run the emulator from Android Studio](/studio/run/emulator#runningapp).\n4. Click the three-dot overflow menu at the bottom of the emulator toolbar. Click the **Rotary input** tab in the new window to open the rotary input interface and try rotary input scrolling.\n\nThe following video shows rotary input in the emulator:"]]
