实现文本放大镜

试试 Compose 方式
Jetpack Compose 是 Android 推荐的 UI 工具包。了解如何在 Compose 中使用文本。
Modifier.magnifier() →

放大镜微件适用于 Android 9（API 级别 28）及更高版本，它是一个虚拟放大镜，通过表示透镜的叠加窗格显示 View 的放大副本。此功能改善了文本插入和选择的用户体验。将放大镜应用于文本时，用户可以通过在跟随手指的窗格中查看放大后的文本，精确地定位光标或选择手柄。

图 1 展示了放大镜如何便于选择文本。放大镜 API 不局限于文本，您可以在各种用例中使用此微件，例如阅读小字体文本或放大地图上难以看清的地名。

An image showing how the magnifier appears after grabbing the right selection handle
图 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. 放大镜跟随用户的触摸。它应用于一个 ViewGroup，该 Group 在左侧包含一个 `ImageView`，在右侧包含一个 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 平台上一致地为自定义文本视图启用放大镜非常重要。请考虑以下几点：

  • 当用户抓取插入或选择手柄时，放大镜会立即触发。
  • 放大镜始终水平平滑地跟随用户手指移动，而垂直方向则固定在当前文本行的中心。
  • 水平移动时，放大镜仅在当前行的左右边界之间移动。此外，当用户的触摸离开这些边界且触摸与最近边界之间的水平距离大于放大镜内容原始宽度的一半时，放大镜将被关闭，因为光标在放大镜内不再可见。
  • 当文本字体过大时，放大镜永远不会触发。当字体的下沉线和上浮线之间的差异大于适合放大镜内容的高度时，文本被认为过大。在这种情况下触发放大镜没有附加价值。