本頁面由 Cloud Translation API 翻譯而成。

實作文字放大鏡

Android 9 (API 級別 28) 以上版本均提供放大鏡小工具虛擬放大鏡，透過View 代表鏡頭的重疊窗格。這項功能可改善文字插入功能和選擇使用者體驗將放大鏡套用至文字時，使用者可以透過放大檢視功能，精確定位遊標或選取控點文字。

圖 1 顯示放大鏡如何協助您選取文字。放大鏡 API 不會與文字連結，這個小工具適用於各種用途，例如例如閱讀較小的文字或放大地圖上難以辨識的地名。

顯示放大鏡在擷取適當選取控點後的顯示方式 — **圖 1**：放大文字。使用者拖曳適當的選取項目時控點時，系統會彈出放大鏡圖示，協助你正確定位。

放大鏡已與平台小工具整合，例如 TextView、 EditText和WebView。可為不同應用程式提供一致的文字操作體驗。這個小工具隨附簡單的 API，可用來放大任何 View 根據應用程式的情境進行切換

API 使用方式

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

Kotlin

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

Java

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

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

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

Kotlin

view.setBackgroundColor(...)

Java

view.setBackgroundColor(...);

假設放大鏡內看得見背景顏色，放大鏡的過時內容視為舊背景螢幕。如要重新整理內容，請使用 update() 方法，如下所示：

Kotlin

view.post { magnifier.update() }

Java

view.post(magnifier::update);

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

Kotlin

magnifier.dismiss()

Java

magnifier.dismiss();

放大使用者互動功能

放大鏡的常見用途是讓使用者能夠透過下列方式將檢視畫面區域放大如圖 2 所示。

圖 2.放大鏡隨著使用者的輕觸移動。是已套用至左側包含 `ImageView` 的 ViewGroup 右側則是 TextView。

請根據收到的觸控事件更新放大鏡，如下所示：

Kotlin

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
}

Java

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 和 Android 平台上的重要資訊請把握以下幾項重點：

當使用者擷取插入或選取控點時，系統會立即觸發放大鏡。
放大鏡一律會流暢地隨著使用者的手指水平移動垂直固定在目前文字行的中心。
水平移動時，放大鏡只會在左側和目前線條的右側邊界。此外，當使用者輕觸離開時這些邊界和觸控與距離最近的水平距離邊界超過放大鏡內容原始寬度的一半系統已關閉放大鏡，因為遊標不會再出現在。
文字字型過大時，系統一律不會觸發放大鏡。文字為如果兩種字型的差不多，將視為太大高度大於放大鏡適用的內容高度。在這種情況下，觸發放大鏡並不會帶來任何附加價值。