實作文字放大鏡

嘗試 Compose 方法

Jetpack Compose 是 Android 推薦的 UI 工具包。瞭解如何在 Compose 中使用文字。

Modifier.magnifier() →

放大鏡小工具適用於 Android 9 (API 級別 28) 以上版本，並透過代表鏡頭的重疊窗格顯示放大的 View 副本。這項功能可改善文字插入和選取功能的使用者體驗。將放大鏡套用至文字時，使用者可在跟隨手指移動的窗格中，查看放大的文字，以便精確定位遊標或選取控點。

圖 1 顯示放大鏡如何協助選取文字。放大鏡 API 並未綁定文字，您可以在各種用途中使用這個小工具，例如讀取小號文字，或是放大地圖上難以辨識的地名。

放大鏡已與平台小工具整合，例如 TextView、EditText 和 WebView。這個 API 可在各個應用程式間提供一致的文字操控體驗。這個小工具隨附簡易 API，可用來依據應用程式情境放大任何 View。

API 使用方式

您可以針對任意檢視畫面，以程式輔助方式使用放大鏡，如下所示：

val view: View = findViewById(R.id.view)
val magnifier = Magnifier.Builder(view).build()
magnifier.show(view.width / 2.0f, view.height / 2.0f)

View view = findViewById(R.id.view);
Magnifier magnifier = new Magnifier.Builder(view).build();
magnifier.show(view.getWidth() / 2, view.getHeight() / 2);

假設檢視區塊階層有第一個版面配置，螢幕上會顯示放大鏡，並包含一個以檢視區塊中指定座標為中心的區域。窗格會出現在複製內容的中心點上方。放大鏡會持續顯示，直到使用者關閉為止。

下列程式碼片段說明如何變更放大檢視畫面的背景：

view.setBackgroundColor(...)

view.setBackgroundColor(...);

假設放大鏡內看得見背景顏色，放大鏡顯示的內容已過時，因為系統仍顯示採用舊背景的檢視畫面區域。如要重新整理內容，請使用 update() 方法，如下所示：

view.post { magnifier.update() }

view.post(magnifier::update);

完成後，請呼叫 dismiss() 方法關閉放大鏡：

magnifier.dismiss()

magnifier.dismiss();

放大使用者互動功能

放大鏡的常見用途是讓使用者輕觸檢視區塊區域放大，如圖 2 所示。

您可以根據檢視畫面收到的觸控事件更新放大鏡，如下所示：

imageView.setOnTouchListener { v, event ->
  when (event.actionMasked) {
    MotionEvent.ACTION_DOWN, MotionEvent.ACTION_MOVE -> {
      val viewPosition = IntArray(2)
      v.getLocationOnScreen(viewPosition)
      magnifier.show(event.rawX - viewPosition[0], event.rawY - viewPosition[1])
    }
    MotionEvent.ACTION_CANCEL, MotionEvent.ACTION_UP -> {
      magnifier.dismiss()
    }
  }
  true
}

imageView.setOnTouchListener(new View.OnTouchListener() {
    @Override
    public boolean onTouch(View v, MotionEvent event) {
        switch (event.getActionMasked()) {
            case MotionEvent.ACTION_DOWN:
                // Fall through.
            case MotionEvent.ACTION_MOVE: {
                final int[] viewPosition = new int[2];
                v.getLocationOnScreen(viewPosition);
                magnifier.show(event.getRawX() - viewPosition[0],
                               event.getRawY() - viewPosition[1]);
                break;
            }
            case MotionEvent.ACTION_CANCEL:
                // Fall through.
            case MotionEvent.ACTION_UP: {
                magnifier.dismiss();
            }
        }
        return true;
    }
});

放大文字時的其他注意事項

對於平台文字小工具，請務必瞭解特定放大鏡行為，並在 Android 平台上為自訂文字檢視區塊啟用放大鏡。請考量下列幾項重點：

• 當使用者擷取插入或選取控點時，系統會立即觸發放大鏡。
• 放大鏡始終流暢地跟隨使用者的手指水平移動，同時垂直固定在目前文字行的中央。
• 水平移動時，放大鏡只會在目前線條的左右邊界之間移動。此外，如果使用者的觸控離開這些邊界，且輕觸與最近邊界之間的水平距離大於放大鏡內容原本寬度的一半，系統就會關閉放大鏡，因為放大鏡內再也看不見遊標。
• 文字字型過大時，系統絕不會觸發放大鏡。如果字型的低度與遞增之間的差距大於放大鏡中的內容高度，系統會將文字視為過大。在這種情況下，觸發放大鏡不會提高價值。