實作文字放大鏡

試用 Compose

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

Modifier.magnifier() →

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);

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

注意： show() 是 這是相對於放大後的檢視畫面左上角。

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

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;
    }
});

注意： 放大鏡不會顯示不屬於 即使檢視區塊包含在可捲動的容器中 遮罩。當傳遞至 show() 的座標暗示複製外部內容時，系統會將座標強制轉型至檢視畫面的可見區域內。

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

對平台文字小工具而言，瞭解特定的放大鏡非常重要 以及如何為自訂文字檢視區塊啟用放大鏡 能夠分享 Android 和 Android 平台上的重要資訊請把握以下幾項重點：

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