Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Alguns dispositivos Wear OS têm um botão lateral giratório. Quando o usuário gira o
botão, a visualização atual do app rola para cima ou para baixo. Esse tipo de ação é chamada de
entrada por seletor giratório.
Observação: este guia se refere principalmente ao processamento da entrada por seletor giratório usando
interfaces baseadas em visualização. Para mais informações sobre como processar entradas por seletor giratório usando o Compose para Wear OS, consulte
Entrada por seletor giratório no Compose.
Vários contêineres roláveis, como
ScrollView,
ListView,
HorizontalScrollView
e WearableRecyclerView,
oferecem suporte à entrada por seletor giratório desde que o foco seja definido sem exigir nenhum código
específico do Wear OS.
Estar em foco é um pré-requisito importante porque, no Android 9 (nível 28
da API) e versões mais recentes, as visualizações não recebem foco de maneira implícita.
Práticas recomendadas de foco
Para responder a eventos de entrada por seletor giratório, um contêiner rolável precisa estar em foco.
Os eventos de entrada por seletor giratório não aparecem na hierarquia
de visualização. Se não houver uma visualização em foco ou se ela retornar false de
View.onGenericMotionEvent(),
o evento é enviado para
Activity.onGenericMotionEvent().
Confira abaixo as práticas recomendadas para responder a eventos de entrada por seletor giratório:
Não esqueça que, por padrão, iniciar uma atividade ou até mesmo tocar em uma
visualização não a coloca em foco, mesmo que ela seja
focalizável. Para que a visualização entre em foco, ela precisa usar a tag
<requestFocus />
ou chamar View.requestFocus() manualmente.
Marque as visualizações roláveis personalizadas como focalizáveis usando android:focusable="true"
e android:focusableInTouchMode="true".
Se a visualização rolável for anexada depois de Activity.onCreate(), por
exemplo, se você esperar que uma solicitação de rede seja concluída antes de criar a interface, chame
requestFocus() depois de anexá-la.
Se a visualização rolável inicialmente for INVISIBLE
ou GONE,
você precisará chamar requestFocus() quando a definir como
VISIBLE.
Caso a atividade contenha várias visualizações roláveis, escolha uma para focalizar usando a
tag
<requestFocus />. O botão lateral giratório não oferece suporte à rolagem aninhada.
Se a interface tiver outra visualização que roube o foco quando o usuário
interagir com ela, por exemplo,
um InputText, ofereça uma maneira de restaurar o foco para a visualização rolável,
se necessário. Detecte os toques na visualização rolável e chame
requestFocus() em resposta.
Comportamento de rolagem personalizado
Caso a visualização rolável não ofereça suporte nativo à rolagem de entrada por seletor giratório ou caso você queira
usar essa entrada para fazer algo que não seja uma rolagem (como aumentar/diminuir o zoom ou interagir com seletores),
você pode processar os eventos de
rolagem por conta própria. É importante garantir que a visualização receba foco, caso contrário,
os eventos não serão transmitidos.
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}}
Java
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;}});
Testar usando um emulador
Use o Android Emulator para simular a rolagem de entrada por seletor giratório
em um dispositivo Wear. Inicie o app para Wear no emulador ao executar
seu projeto ou arraste um
arquivo APK para o emulador para instalá-lo.
Para testar a entrada por seletor giratório no emulador:
No SDK Manager, use a guia SDK Tools para instalar
o Android Emulator 26.0.3 ou versões mais recentes.
No Android Studio, selecione Tools >
Android > AVD Manager.
Crie um novo dispositivo Wear com o nível 25 da API ou
mais recente.
Clique no menu flutuante de três pontos na parte de baixo da barra de ferramentas do emulador. Clique na guia
Rotary input na nova janela para abrir a interface de entrada por seletor giratório e tente
rolar o seletor.
O vídeo a seguir mostra a entrada por seletor giratório no emulador:
O conteúdo e os exemplos de código nesta página estão sujeitos às licenças descritas na Licença de conteúdo. Java e OpenJDK são marcas registradas da Oracle e/ou suas afiliadas.
Última atualização 2025-07-26 UTC.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Não contém as informações de que eu preciso","missingTheInformationINeed","thumb-down"],["Muito complicado / etapas demais","tooComplicatedTooManySteps","thumb-down"],["Desatualizado","outOfDate","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Problema com as amostras / o código","samplesCodeIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-07-26 UTC."],[],[],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:"]]