在 Android 中，捲動通常是透過
ScrollView
類別建立任何可能超出其邊界的標準版面配置
提供由 ScrollView 中管理的可捲動檢視畫面
這個原則只有在特殊情況下，您才需要導入自訂捲動器
情境本文件說明如何在回應中顯示捲動效果
利用捲動式手勢輕觸手勢。
應用程式可使用
捲動器—Scroller
或
OverScroller—至
收集所需的資料，以產生回應觸控動作所需的捲動動畫
活動。兩者相似，但 OverScroller 也包含
指示使用者在平移或快速滑過內容邊緣時，通知內容邊緣
手勢。
- 從 Android 12 (API 級別 31) 開始，視覺元素延展並彈跳 返回拖曳事件，然後在快速滑過事件上彈回。
- 在 Android 11 (API 級別 30) 以下版本中，邊界會顯示「光暈」 。
本文件中的 InteractiveChart 範例使用
EdgeEffect
類別來顯示這些過度捲動效果。
您可以使用捲動器，以動畫形式顯示捲動期間的動畫， 平台標準捲動物理行為，例如摩擦、速度和其他 或稱謂捲動器本身不會繪製任何項目。捲動式追蹤捲動 隨著時間的推移，系統不會自動將這些位置 檢視畫面。您必須取得並套用新的座標，讓 捲動動畫則呈現流暢的視覺效果。
瞭解捲動相關術語
捲動是指在 Android 系統中可能具有不同涵義的字詞 相關資訊
捲動是移動可視區域的一般程序，也就是說
「窗戶」指定相關內容如果捲動畫面同時位於
x 和 y 軸，則稱為 panning。
本文件中的 InteractiveChart 範例應用程式說明瞭兩個
不同類型的捲動、拖曳和快速滑過功能：
- 拖曳：這是使用者捲動時發生的捲動類型
將手指放在觸控螢幕上如要實作拖曳功能
覆寫
onScroll()英吋GestureDetector.OnGestureListener。 如要進一步瞭解拖曳功能，請參閱 拖曳與縮放。 - 滑動：這是使用者捲動時發生的捲動類型
快速拖曳及放開手指在使用者上起手指後
一般而言，我們會希望持續移動可視區域，但請拖慢到
會停止移動您可以透過覆寫的方式實作快速滑過動作
onFling()在GestureDetector.OnGestureListener中使用捲動器 物件。 - 平移：同時沿著 x 和 y 軸稱為「平移」。
捲動器物件和快速滑過手勢是很常見的情況，
在您希望 UI 顯示捲動畫面的任何情境
回應觸控事件。舉例來說，您可以覆寫
onTouchEvent()
直接處理觸控事件並產生捲動效果
「貼齊頁面」回應這些觸控事件
包含內建捲動實作的元件
下列 Android 元件包含捲動及捲動的內建支援 過度捲動行為：
GridViewHorizontalScrollViewListViewNestedScrollViewRecyclerViewScrollViewViewPagerViewPager2
如果您的應用程式需要支援在 元件，請完成下列步驟：
- 建立自訂以觸控方式捲動畫面 。
- 如要支援搭載 Android 12 以上版本的裝置： 實作延展過度捲動 「效果」。
建立自訂的觸控式捲動實作
本節說明，如果您的應用程式使用的是 內建支援 以及捲動和過度捲動
下列程式碼片段來自
InteractiveChart
範例。該公式採用
GestureDetector
並覆寫
GestureDetector.SimpleOnGestureListener
onFling() 方法。它會使用 OverScroller 來追蹤
快速滑過手勢如果使用者在執行應用程式後到達內容邊緣
快速滑過手勢，表示使用者抵達終點
內容。這項指標會因裝置的 Android 版本而異
執行作業：
- 在 Android 12 以上版本中，視覺元素延展並 。
- 在 Android 11 以下版本中，視覺元素會顯示光暈 效果。
下列程式碼片段的第一部分會顯示
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);
}
onFling()打電話時
postInvalidateOnAnimation(),
觸發的
computeScroll()
更新 x 和 y 的值。這通常是在
檢視區塊子項會使用捲動器物件為捲動製作動畫效果，如上例所示
範例。
大部分的檢視畫面會直接傳遞捲動器物件的 x 和 y 位置
到
scrollTo()。
下列 computeScroll() 實作
稱為
computeScrollOffset()
取得「x」和「y」的目前位置。當
顯示過度捲動的「光暈」也就是螢幕
已放大，x 或 y 超出邊界，且應用程式尚未
顯示過度捲動畫面，程式碼會設定過度捲動光暈效果，
呼叫 postInvalidateOnAnimation() 來在
檢視畫面。
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;
}
...
}
下方是執行實際縮放的程式碼區段：
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);
}
這是在 computeScrollSurfaceSize() 中呼叫的方法
上方程式碼片段計算目前可捲動的介面大小
像素。舉例來說，如果系統可顯示整個圖表區域，這裡就會顯示目前的
mContentRect 的大小。如果圖表同時放大 200%
方向就會是水平和垂直方向的兩倍。
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()));
}
如需其他捲動器使用方式的範例，請參閱
原始碼
(適用於 ViewPager 類別)。可隨著快速滑過執行捲動
捲動畫面，實作「snap-to-page」
實作延展過度捲動效果
自 Android 12 起，EdgeEffect 會新增
以下 API 可用於實作延展過度捲動效果：
getDistance()onPullDistance()
為了提供最佳使用者體驗，延展過度捲動： 包括：
- 使用者觸碰時，延展動畫生效時 將觸控內容註冊為「貓」。使用者停止動畫 會再次開始操縱伸展
- 當使用者用手指向外伸展方向移動時， 再放開。
- 使用者在伸展運動時快速滑過
EdgeEffect增強延展效果
擷取動畫
當使用者捕捉到活動中的延展動畫時，
EdgeEffect.getDistance() 會傳回 0。這個條件
表示延展效果必須受到觸控動作操縱。大多數
容器則在 onInterceptTouchEvent() 中偵測到擷取，
如以下程式碼片段所示：
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;
...
}
}
在上述範例中，onInterceptTouchEvent() 會傳回
在 mIsBeingDragged 為 true 時為 true，因此
就足以在子發布商有機會
也可以使用
放開過度捲動效果
請務必在捲動前釋放延展效果，以防止 以及從套用於捲動內容的延伸以下程式碼 此範例將會套用這個最佳做法：
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);
}
...
在使用者拖曳時耗用 EdgeEffect 提取距離
再將觸控事件傳遞至巢狀捲動容器，或者將
請捲動頁面在上述程式碼範例中，getDistance() 會傳回
顯示邊緣效果時為正值
動作當觸控事件釋放伸展動作時，會先使用
EdgeEffect，使其在發布其他效果前完全發布。
例如巢狀捲動您可以使用「getDistance()」
，瞭解需要多少拉距離才能釋放目前的效果。
與 onPull() 不同，onPullDistance() 會傳回
傳遞的延遲時間自 Android 12 起，
onPull() 或 onPullDistance() 為負數
getDistance() 是 deltaDistance 的值
0，延展效果不會變更。Android 11
onPull() 可讓總距離為負值
顯示光暈效果。
停用過度捲動
您可以在版面配置檔案中停用過度捲動功能，或透過程式輔助方式停用。
如要選擇不採用版面配置檔案，請將 android:overScrollMode 設為
如以下範例所示：
<MyCustomView android:overScrollMode="never">
...
</MyCustomView>
如要透過程式輔助方式停用，請使用以下程式碼：
Kotlin
customView.overScrollMode = View.OVER_SCROLL_NEVER
Java
customView.setOverScrollMode(View.OVER_SCROLL_NEVER);
其他資源
請參閱下列相關資源：