No Android, a rolagem é normalmente realizada usando a
classe
ScrollView
. Aninhe qualquer layout padrão que possa se estender além dos limites do
contêiner em um ScrollView
para fornecer uma visualização rolável gerenciada pelo
framework. A implementação de um botão de rolagem personalizado só é necessária em cenários
especiais. Este documento descreve como exibir um efeito de rolagem em resposta
a gestos de toque usando rolagens.
Seu app pode usar
roladores (Scroller
ou
OverScroller
) para
coletar os dados necessários para produzir uma animação de rolagem em resposta a um evento
de toque. Eles são semelhantes, mas OverScroller
também inclui métodos para
indicar aos usuários quando eles alcançam as bordas do conteúdo depois de um gesto de
movimentação ou deslize rápido.
- No Android 12 (nível 31 da API) e versões mais recentes, os elementos visuais se esticam e saltam de volta em um evento de arrastar e deslizam e voltam em um evento desse tipo.
- No Android 11 (API de nível 30) e versões anteriores, os limites exibem um efeito de "brilho" após um gesto de arrastar ou deslizar rapidamente até a borda.
O exemplo InteractiveChart
neste documento usa a
classe EdgeEffect
para mostrar esses efeitos de rolagem.
Você pode usar um botão para animar a rolagem ao longo do tempo, usando a física de rolagem padrão da plataforma, como atrito, velocidade e outras qualidades. O botão de rolagem em si não desenha nada. Os controles de rolagem rastreiam os deslocamentos de rolagem ao longo do tempo, mas não aplicam essas posições automaticamente à visualização. É necessário gerar e aplicar novas coordenadas a uma taxa que faça a animação de rolagem parecer suave.
Compreender a terminologia de rolagem
Rolagem é uma palavra que pode ter significados diferentes no Android, dependendo do contexto.
A rolagem é o processo geral de mover a janela de visualização, ou seja,
a "janela" de conteúdo. Quando a rolagem ocorre nos eixos
x e y, isso é chamado de movimentação. O
app de exemplo InteractiveChart
neste documento ilustra dois
tipos diferentes de rolagem: arrastar e deslizar rapidamente:
- Arrastar:esse é o tipo de rolagem que ocorre quando o usuário
arrasta o dedo pela tela touchscreen. Você pode implementar a ação de arrastar
substituindo
onScroll()
emGestureDetector.OnGestureListener
. Para saber mais sobre como arrastar, consulte Arrastar e dimensionar. - Rolagem rápida:é o tipo de rolagem que ocorre quando o usuário
arrasta e levanta o dedo rapidamente. Depois que o usuário levanta o dedo, geralmente é recomendável continuar movendo a janela de visualização, mas desacelerar até que ela pare de se mover. Você pode implementar a rolagem rápida substituindo
onFling()
emGestureDetector.OnGestureListener
e usando um objeto de rolagem. - Movimentação:a rolagem simultânea nos eixos x e y é chamada de movimentação.
É comum usar objetos de rolagem com um gesto de rolagem rápida, mas
é possível usá-los em qualquer contexto em que você queira que a interface mostre rolagem em
resposta a um evento de toque. Por exemplo, você pode substituir
onTouchEvent()
para processar eventos de toque diretamente e produzir um efeito de rolagem ou uma
animação de alinhamento à página em resposta a esses eventos.
Componentes que contêm implementações de rolagem integradas
Os componentes do Android abaixo oferecem suporte integrado ao comportamento de rolagem e rolagem:
GridView
HorizontalScrollView
ListView
NestedScrollView
RecyclerView
ScrollView
ViewPager
ViewPager2
Se o app precisar oferecer suporte à rolagem e à rolagem em um componente diferente, siga estas etapas:
- Criar uma implementação personalizada de rolagem baseada em toque.
- Para oferecer suporte a dispositivos com o Android 12 e versões mais recentes, implemente o efeito de rolagem esticada.
Criar uma implementação personalizada de rolagem baseada em toque
Esta seção descreve como criar seu próprio botão de rolagem caso o app use um componente que não tenha suporte integrado para rolagem e rolagem.
O snippet abaixo vem do
exemplo
InteractiveChart
. Ele usa um
GestureDetector
e substitui o
método GestureDetector.SimpleOnGestureListener
onFling()
. Ele usa OverScroller
para rastrear o
gesto de rolagem rápida. Se o usuário alcançar as bordas do conteúdo depois de executar o
gesto de deslizar, o contêiner vai indicar quando ele chegar ao fim do
conteúdo. A indicação depende da versão do Android que o dispositivo
executa:
- No Android 12 e em versões mais recentes, os elementos visuais ficam mais esticados e pulamados.
- No Android 11 e versões anteriores, os elementos visuais exibem um efeito de brilho.
A primeira parte do snippet abaixo mostra a implementação de
onFling()
:
Kotlin
// Viewport extremes. See currentViewport for a discussion of the viewport. private val AXIS_X_MIN = -1f private val AXIS_X_MAX = 1f private val AXIS_Y_MIN = -1f private val AXIS_Y_MAX = 1f // The current viewport. This rectangle represents the visible chart // domain and range. The viewport is the part of the app that the // user manipulates via touch gestures. private val currentViewport = RectF(AXIS_X_MIN, AXIS_Y_MIN, AXIS_X_MAX, AXIS_Y_MAX) // The current destination rectangle—in pixel coordinates—into which // the chart data must be drawn. private lateinit var contentRect: Rect private lateinit var scroller: OverScroller private lateinit var scrollerStartViewport: RectF ... private val gestureListener = object : GestureDetector.SimpleOnGestureListener() { override fun onDown(e: MotionEvent): Boolean { // Initiates the decay phase of any active edge effects. if (Build.VERSION.SDK_INT < Build.VERSION_CODES.S) { releaseEdgeEffects() } scrollerStartViewport.set(currentViewport) // Aborts any active scroll animations and invalidates. scroller.forceFinished(true) ViewCompat.postInvalidateOnAnimation(this@InteractiveLineGraphView) return true } ... override fun onFling( e1: MotionEvent, e2: MotionEvent, velocityX: Float, velocityY: Float ): Boolean { fling((-velocityX).toInt(), (-velocityY).toInt()) return true } } private fun fling(velocityX: Int, velocityY: Int) { // Initiates the decay phase of any active edge effects. // On Android 12 and later, the edge effect (stretch) must // continue. if (Build.VERSION.SDK_INT < Build.VERSION_CODES.S) { releaseEdgeEffects() } // Flings use math in pixels, as opposed to math based on the viewport. val surfaceSize: Point = computeScrollSurfaceSize() val (startX: Int, startY: Int) = scrollerStartViewport.run { set(currentViewport) (surfaceSize.x * (left - AXIS_X_MIN) / (AXIS_X_MAX - AXIS_X_MIN)).toInt() to (surfaceSize.y * (AXIS_Y_MAX - bottom) / (AXIS_Y_MAX - AXIS_Y_MIN)).toInt() } // Before flinging, stops the current animation. scroller.forceFinished(true) // Begins the animation. scroller.fling( // Current scroll position. startX, startY, velocityX, velocityY, /* * Minimum and maximum scroll positions. The minimum scroll * position is generally 0 and the maximum scroll position * is generally the content size less the screen size. So if the * content width is 1000 pixels and the screen width is 200 * pixels, the maximum scroll offset is 800 pixels. */ 0, surfaceSize.x - contentRect.width(), 0, surfaceSize.y - contentRect.height(), // The edges of the content. This comes into play when using // the EdgeEffect class to draw "glow" overlays. contentRect.width() / 2, contentRect.height() / 2 ) // Invalidates to trigger computeScroll(). ViewCompat.postInvalidateOnAnimation(this) }
Java
// Viewport extremes. See currentViewport for a discussion of the viewport. private static final float AXIS_X_MIN = -1f; private static final float AXIS_X_MAX = 1f; private static final float AXIS_Y_MIN = -1f; private static final float AXIS_Y_MAX = 1f; // The current viewport. This rectangle represents the visible chart // domain and range. The viewport is the part of the app that the // user manipulates via touch gestures. private RectF currentViewport = new RectF(AXIS_X_MIN, AXIS_Y_MIN, AXIS_X_MAX, AXIS_Y_MAX); // The current destination rectangle—in pixel coordinates—into which // the chart data must be drawn. private final Rect contentRect = new Rect(); private final OverScroller scroller; private final RectF scrollerStartViewport = new RectF(); // Used only for zooms and flings. ... private final GestureDetector.SimpleOnGestureListener gestureListener = new GestureDetector.SimpleOnGestureListener() { @Override public boolean onDown(MotionEvent e) { if (Build.VERSION.SDK_INT < Build.VERSION_CODES.S) { releaseEdgeEffects(); } scrollerStartViewport.set(currentViewport); scroller.forceFinished(true); ViewCompat.postInvalidateOnAnimation(InteractiveLineGraphView.this); return true; } ... @Override public boolean onFling(MotionEvent e1, MotionEvent e2, float velocityX, float velocityY) { fling((int) -velocityX, (int) -velocityY); return true; } }; private void fling(int velocityX, int velocityY) { // Initiates the decay phase of any active edge effects. // On Android 12 and later, the edge effect (stretch) must // continue. if (Build.VERSION.SDK_INT < Build.VERSION_CODES.S) { releaseEdgeEffects(); } // Flings use math in pixels, as opposed to math based on the viewport. Point surfaceSize = computeScrollSurfaceSize(); scrollerStartViewport.set(currentViewport); int startX = (int) (surfaceSize.x * (scrollerStartViewport.left - AXIS_X_MIN) / ( AXIS_X_MAX - AXIS_X_MIN)); int startY = (int) (surfaceSize.y * (AXIS_Y_MAX - scrollerStartViewport.bottom) / ( AXIS_Y_MAX - AXIS_Y_MIN)); // Before flinging, stops the current animation. scroller.forceFinished(true); // Begins the animation. scroller.fling( // Current scroll position. startX, startY, velocityX, velocityY, /* * Minimum and maximum scroll positions. The minimum scroll * position is generally 0 and the maximum scroll position * is generally the content size less the screen size. So if the * content width is 1000 pixels and the screen width is 200 * pixels, the maximum scroll offset is 800 pixels. */ 0, surfaceSize.x - contentRect.width(), 0, surfaceSize.y - contentRect.height(), // The edges of the content. This comes into play when using // the EdgeEffect class to draw "glow" overlays. contentRect.width() / 2, contentRect.height() / 2); // Invalidates to trigger computeScroll(). ViewCompat.postInvalidateOnAnimation(this); }
Quando onFling()
chama
postInvalidateOnAnimation()
,
ele aciona
computeScroll()
para atualizar os valores de x e y. Normalmente, isso é feito quando uma
visualização filha está animando uma rolagem usando um objeto de rolagem, conforme mostrado no exemplo
anterior.
A maioria das visualizações passa a posição x e y do objeto de rolagem diretamente
para
scrollTo()
.
A implementação de computeScroll()
abaixo tem uma abordagem
diferente: ela chama
computeScrollOffset()
para descobrir a localização atual de x e y. Quando os critérios para
exibir um efeito de borda de "brilho" de rolagem são atendidos, ou seja, a tela
aumenta o zoom, x ou y fica fora dos limites e o app ainda não está
mostrando uma rolagem. O código configura o efeito de brilho de rolagem e
chama postInvalidateOnAnimation()
para acionar uma invalidação na
visualização.
Kotlin
// Edge effect/overscroll tracking objects. private lateinit var edgeEffectTop: EdgeEffect private lateinit var edgeEffectBottom: EdgeEffect private lateinit var edgeEffectLeft: EdgeEffect private lateinit var edgeEffectRight: EdgeEffect private var edgeEffectTopActive: Boolean = false private var edgeEffectBottomActive: Boolean = false private var edgeEffectLeftActive: Boolean = false private var edgeEffectRightActive: Boolean = false override fun computeScroll() { super.computeScroll() var needsInvalidate = false // The scroller isn't finished, meaning a fling or // programmatic pan operation is active. if (scroller.computeScrollOffset()) { val surfaceSize: Point = computeScrollSurfaceSize() val currX: Int = scroller.currX val currY: Int = scroller.currY val (canScrollX: Boolean, canScrollY: Boolean) = currentViewport.run { (left > AXIS_X_MIN || right < AXIS_X_MAX) to (top > AXIS_Y_MIN || bottom < AXIS_Y_MAX) } /* * If you are zoomed in, currX or currY is * outside of bounds, and you aren't already * showing overscroll, then render the overscroll * glow edge effect. */ if (canScrollX && currX < 0 && edgeEffectLeft.isFinished && !edgeEffectLeftActive) { edgeEffectLeft.onAbsorb(scroller.currVelocity.toInt()) edgeEffectLeftActive = true needsInvalidate = true } else if (canScrollX && currX > surfaceSize.x - contentRect.width() && edgeEffectRight.isFinished && !edgeEffectRightActive) { edgeEffectRight.onAbsorb(scroller.currVelocity.toInt()) edgeEffectRightActive = true needsInvalidate = true } if (canScrollY && currY < 0 && edgeEffectTop.isFinished && !edgeEffectTopActive) { edgeEffectTop.onAbsorb(scroller.currVelocity.toInt()) edgeEffectTopActive = true needsInvalidate = true } else if (canScrollY && currY > surfaceSize.y - contentRect.height() && edgeEffectBottom.isFinished && !edgeEffectBottomActive) { edgeEffectBottom.onAbsorb(scroller.currVelocity.toInt()) edgeEffectBottomActive = true needsInvalidate = true } ... } }
Java
// Edge effect/overscroll tracking objects. private EdgeEffectCompat edgeEffectTop; private EdgeEffectCompat edgeEffectBottom; private EdgeEffectCompat edgeEffectLeft; private EdgeEffectCompat edgeEffectRight; private boolean edgeEffectTopActive; private boolean edgeEffectBottomActive; private boolean edgeEffectLeftActive; private boolean edgeEffectRightActive; @Override public void computeScroll() { super.computeScroll(); boolean needsInvalidate = false; // The scroller isn't finished, meaning a fling or // programmatic pan operation is active. if (scroller.computeScrollOffset()) { Point surfaceSize = computeScrollSurfaceSize(); int currX = scroller.getCurrX(); int currY = scroller.getCurrY(); boolean canScrollX = (currentViewport.left > AXIS_X_MIN || currentViewport.right < AXIS_X_MAX); boolean canScrollY = (currentViewport.top > AXIS_Y_MIN || currentViewport.bottom < AXIS_Y_MAX); /* * If you are zoomed in, currX or currY is * outside of bounds, and you aren't already * showing overscroll, then render the overscroll * glow edge effect. */ if (canScrollX && currX < 0 && edgeEffectLeft.isFinished() && !edgeEffectLeftActive) { edgeEffectLeft.onAbsorb((int)mScroller.getCurrVelocity()); edgeEffectLeftActive = true; needsInvalidate = true; } else if (canScrollX && currX > (surfaceSize.x - contentRect.width()) && edgeEffectRight.isFinished() && !edgeEffectRightActive) { edgeEffectRight.onAbsorb((int)mScroller.getCurrVelocity()); edgeEffectRightActive = true; needsInvalidate = true; } if (canScrollY && currY < 0 && edgeEffectTop.isFinished() && !edgeEffectTopActive) { edgeEffectRight.onAbsorb((int)mScroller.getCurrVelocity()); edgeEffectTopActive = true; needsInvalidate = true; } else if (canScrollY && currY > (surfaceSize.y - contentRect.height()) && edgeEffectBottom.isFinished() && !edgeEffectBottomActive) { edgeEffectRight.onAbsorb((int)mScroller.getCurrVelocity()); edgeEffectBottomActive = true; needsInvalidate = true; } ... }
Esta é a seção do código que executa o zoom real:
Kotlin
lateinit var zoomer: Zoomer val zoomFocalPoint = PointF() ... // If a zoom is in progress—either programmatically // or through double touch—this performs the zoom. if (zoomer.computeZoom()) { val newWidth: Float = (1f - zoomer.currZoom) * scrollerStartViewport.width() val newHeight: Float = (1f - zoomer.currZoom) * scrollerStartViewport.height() val pointWithinViewportX: Float = (zoomFocalPoint.x - scrollerStartViewport.left) / scrollerStartViewport.width() val pointWithinViewportY: Float = (zoomFocalPoint.y - scrollerStartViewport.top) / scrollerStartViewport.height() currentViewport.set( zoomFocalPoint.x - newWidth * pointWithinViewportX, zoomFocalPoint.y - newHeight * pointWithinViewportY, zoomFocalPoint.x + newWidth * (1 - pointWithinViewportX), zoomFocalPoint.y + newHeight * (1 - pointWithinViewportY) ) constrainViewport() needsInvalidate = true } if (needsInvalidate) { ViewCompat.postInvalidateOnAnimation(this) }
Java
// Custom object that is functionally similar to Scroller. Zoomer zoomer; private PointF zoomFocalPoint = new PointF(); ... // If a zoom is in progress—either programmatically // or through double touch—this performs the zoom. if (zoomer.computeZoom()) { float newWidth = (1f - zoomer.getCurrZoom()) * scrollerStartViewport.width(); float newHeight = (1f - zoomer.getCurrZoom()) * scrollerStartViewport.height(); float pointWithinViewportX = (zoomFocalPoint.x - scrollerStartViewport.left) / scrollerStartViewport.width(); float pointWithinViewportY = (zoomFocalPoint.y - scrollerStartViewport.top) / scrollerStartViewport.height(); currentViewport.set( zoomFocalPoint.x - newWidth * pointWithinViewportX, zoomFocalPoint.y - newHeight * pointWithinViewportY, zoomFocalPoint.x + newWidth * (1 - pointWithinViewportX), zoomFocalPoint.y + newHeight * (1 - pointWithinViewportY)); constrainViewport(); needsInvalidate = true; } if (needsInvalidate) { ViewCompat.postInvalidateOnAnimation(this); }
Esse é o método computeScrollSurfaceSize()
chamado no snippet anterior. Ela calcula o tamanho atual da superfície rolável em
pixels. Por exemplo, se toda a área do gráfico estiver visível, esse será o tamanho atual de mContentRect
. Se o gráfico for ampliado em 200% nas duas direções, o tamanho retornado será duas vezes maior horizontal e verticalmente.
Kotlin
private fun computeScrollSurfaceSize(): Point { return Point( (contentRect.width() * (AXIS_X_MAX - AXIS_X_MIN) / currentViewport.width()).toInt(), (contentRect.height() * (AXIS_Y_MAX - AXIS_Y_MIN) / currentViewport.height()).toInt() ) }
Java
private Point computeScrollSurfaceSize() { return new Point( (int) (contentRect.width() * (AXIS_X_MAX - AXIS_X_MIN) / currentViewport.width()), (int) (contentRect.height() * (AXIS_Y_MAX - AXIS_Y_MIN) / currentViewport.height())); }
Para ver outros exemplos de uso de controles de rolagem, consulte o
código-fonte
da classe ViewPager
. Ela rola em resposta a deslizes e usa
a rolagem para implementar a animação de alinhamento à página.
Implementar o efeito de rolagem esticada
No Android 12 e versões mais recentes, a EdgeEffect
adiciona as
APIs abaixo para implementar o efeito de rolagem esticada:
getDistance()
onPullDistance()
Para oferecer a melhor experiência do usuário com a rolagem esticada, faça o seguinte:
- Quando a animação de alongamento estiver em vigor quando o usuário tocar no conteúdo, registre o toque como uma "captura". O usuário interrompe a animação e começa a manipular o esticamento novamente.
- Quando o usuário mover o dedo na direção oposta do alongamento, solte-o até que ele desapareça totalmente e, em seguida, comece a rolar.
- Quando o usuário deslize rapidamente durante um alongamento, deslize rapidamente o
EdgeEffect
para melhorar o efeito de esticamento.
Capturar a animação
Quando um usuário capturar uma animação de alongamento ativa,
EdgeEffect.getDistance()
retorna 0
. Essa condição
indica que o alongamento precisa ser manipulado pelo movimento de toque. Na maioria dos contêineres, a captura é detectada em onInterceptTouchEvent()
, conforme mostrado no snippet de código a seguir:
Kotlin
override fun onInterceptTouchEvent(ev: MotionEvent): Boolean { ... when (action and MotionEvent.ACTION_MASK) { MotionEvent.ACTION_DOWN -> ... isBeingDragged = EdgeEffectCompat.getDistance(edgeEffectBottom) > 0f || EdgeEffectCompat.getDistance(edgeEffectTop) > 0f ... } return isBeingDragged }
Java
@Override public boolean onInterceptTouchEvent(MotionEvent ev) { ... switch (action & MotionEvent.ACTION_MASK) { case MotionEvent.ACTION_DOWN: ... isBeingDragged = EdgeEffectCompat.getDistance(edgeEffectBottom) > 0 || EdgeEffectCompat.getDistance(edgeEffectTop) > 0; ... } }
No exemplo anterior, onInterceptTouchEvent()
retorna
true
quando mIsBeingDragged
é true
. Portanto, é suficiente para consumir o evento antes que o filho tenha a oportunidade
de consumi-lo.
Soltar o efeito de rolagem
É importante soltar o efeito de esticamento antes de rolar para evitar que ele seja aplicado ao conteúdo de rolagem. O exemplo de código abaixo aplica essa prática recomendada:
Kotlin
override fun onTouchEvent(ev: MotionEvent): Boolean { val activePointerIndex = ev.actionIndex when (ev.getActionMasked()) { MotionEvent.ACTION_MOVE -> val x = ev.getX(activePointerIndex) val y = ev.getY(activePointerIndex) var deltaY = y - lastMotionY val pullDistance = deltaY / height val displacement = x / width if (deltaY < 0f && EdgeEffectCompat.getDistance(edgeEffectTop) > 0f) { deltaY -= height * EdgeEffectCompat.onPullDistance(edgeEffectTop, pullDistance, displacement); } if (deltaY > 0f && EdgeEffectCompat.getDistance(edgeEffectBottom) > 0f) { deltaY += height * EdgeEffectCompat.onPullDistance(edgeEffectBottom, -pullDistance, 1 - displacement); } ... }
Java
@Override public boolean onTouchEvent(MotionEvent ev) { final int actionMasked = ev.getActionMasked(); switch (actionMasked) { case MotionEvent.ACTION_MOVE: final float x = ev.getX(activePointerIndex); final float y = ev.getY(activePointerIndex); float deltaY = y - lastMotionY; float pullDistance = deltaY / getHeight(); float displacement = x / getWidth(); if (deltaY < 0 && EdgeEffectCompat.getDistance(edgeEffectTop) > 0) { deltaY -= getHeight() * EdgeEffectCompat.onPullDistance(edgeEffectTop, pullDistance, displacement); } if (deltaY > 0 && EdgeEffectCompat.getDistance(edgeEffectBottom) > 0) { deltaY += getHeight() * EdgeEffectCompat.onPullDistance(edgeEffectBottom, -pullDistance, 1 - displacement); } ...
Quando o usuário estiver arrastando, consuma a distância de extração de EdgeEffect
antes de transmitir o evento de toque para um contêiner de rolagem aninhado ou arrastar a
rolagem. No exemplo de código anterior, getDistance()
retorna um
valor positivo quando um efeito de borda está sendo mostrado e pode ser liberado com
movimento. Quando o evento de toque libera o alongamento, ele é consumido primeiro pelo
EdgeEffect
para que seja liberado completamente antes que outros efeitos,
como a rolagem aninhada, sejam exibidos. Você pode usar getDistance()
para saber qual é a distância necessária para soltar o efeito atual.
Ao contrário de onPull()
, onPullDistance()
retorna a
quantidade consumida do delta transmitido. A partir do Android 12, se
onPull()
ou onPullDistance()
receberem valores negativos
deltaDistance
quando getDistance()
for
0
, o efeito de esticamento não vai mudar. No Android 11
e versões anteriores, onPull()
permite que valores negativos para a distância total
mostrem efeitos de brilho.
Desativar a rolagem
Você pode desativar a rolagem no arquivo de layout ou de forma programática.
Para desativar no arquivo de layout, defina android:overScrollMode
como
mostrado no exemplo a seguir:
<MyCustomView android:overScrollMode="never"> ... </MyCustomView>
Para desativar isso programaticamente, use o código a seguir:
Kotlin
customView.overScrollMode = View.OVER_SCROLL_NEVER
Java
customView.setOverScrollMode(View.OVER_SCROLL_NEVER);
Outros recursos
Confira estes recursos relacionados:
- Visão geral dos eventos de entrada
- Visão geral dos sensores
- Tornar uma visualização personalizada interativa