موجود در Android 9 (سطح API 28) و بالاتر، ویجت ذره بین یک ذره بین مجازی است که یک کپی بزرگ شده از یک View را از طریق یک صفحه روکش نمایش می دهد که نشان دهنده لنز است. این ویژگی تجربه کاربر درج و انتخاب متن را بهبود می بخشد. هنگام اعمال ذره بین بر روی متن، کاربر می تواند مکان نما یا دستگیره های انتخاب را با مشاهده متن بزرگ شده در پنجره ای که به دنبال انگشت او می آید، به طور دقیق قرار دهد.
شکل 1 نشان می دهد که چگونه ذره بین انتخاب متن را تسهیل می کند. APIهای ذره‌بین به متن متصل نیستند و می‌توانید از این ویجت در موارد مختلف استفاده کنید، مانند خواندن متن‌های کوچک یا بزرگنمایی نام مکان‌هایی که به سختی قابل مشاهده هستند روی نقشه‌ها.
شکل 1. بزرگنمایی متن. هنگامی که کاربر دستگیره انتخاب سمت راست را می کشد، ذره بین برای کمک به قرار دادن دقیق ظاهر می شود.
ذره بین از قبل با ویجت های پلتفرم مانند TextView ، EditText و WebView یکپارچه شده است. دستکاری متن ثابت در بین برنامه ها را فراهم می کند. ویجت دارای یک API ساده است و می تواند برای بزرگنمایی هر View بسته به زمینه برنامه شما استفاده شود.
استفاده از API
می توانید از ذره بین به صورت برنامه ریزی شده در یک نمای دلخواه به صورت زیر استفاده کنید:
با فرض اینکه سلسله مراتب view اولین طرح را داشته باشد، ذره بین روی صفحه نمایش داده می شود و شامل یک ناحیه متمرکز بر مختصات داده شده در نمای است. صفحه در بالای نقطه مرکزی محتوای در حال کپی ظاهر می شود. ذره بین به طور نامحدود باقی می ماند تا زمانی که کاربر آن را رد کند.
قطعه کد زیر نحوه تغییر پس زمینه نمای بزرگنمایی شده را نشان می دهد:
کاتلین
view.setBackgroundColor(...)
جاوا
view.setBackgroundColor(...);
با فرض اینکه رنگ پس‌زمینه در ذره‌بین قابل مشاهده است، محتوای ذره‌بین کهنه است، زیرا همچنان ناحیه‌ای از نمای با پس‌زمینه قدیمی نمایش داده می‌شود. برای تازه کردن محتوا، از متد update() به صورت زیر استفاده کنید:
کاتلین
view.post{magnifier.update()}
جاوا
view.post(magnifier::update);
پس از اتمام، ذره بین را با فراخوانی متد dismiss() ببندید:
کاتلین
magnifier.dismiss()
جاوا
magnifier.dismiss();
در تعامل با کاربر بزرگنمایی کنید
یک مورد معمول استفاده از ذره بین این است که به کاربر اجازه می دهد یک ناحیه دید را با لمس آن بزرگ کند، همانطور که در شکل 2 نشان داده شده است.
شکل 2. ذره بین لمس کاربر را دنبال می کند. روی یک ViewGroup اعمال می شود که شامل «ImageView» در سمت چپ و TextView در سمت راست است.
می توانید این کار را با به روز رسانی ذره بین با توجه به رویدادهای لمسی دریافت شده توسط view انجام دهید، به شرح زیر:
imageView.setOnTouchListener(newView.OnTouchListener(){@OverridepublicbooleanonTouch(Viewv,MotionEventevent){switch(event.getActionMasked()){caseMotionEvent.ACTION_DOWN:// Fall through.caseMotionEvent.ACTION_MOVE:{finalint[]viewPosition=newint[2];v.getLocationOnScreen(viewPosition);magnifier.show(event.getRawX()-viewPosition[0],event.getRawY()-viewPosition[1]);break;}caseMotionEvent.ACTION_CANCEL:// Fall through.caseMotionEvent.ACTION_UP:{magnifier.dismiss();}}returntrue;}});
ملاحظات اضافی هنگام بزرگنمایی متن
برای ویجت‌های متنی پلتفرم، درک رفتارهای خاص ذره‌بین و فعال کردن ذره‌بین برای مشاهده متن سفارشی خود به طور مداوم در سراسر پلتفرم Android مهم است. موارد زیر را در نظر بگیرید:
هنگامی که کاربر یک دسته درج یا انتخاب را می گیرد، ذره بین بلافاصله فعال می شود.
ذره بین همیشه به آرامی انگشت کاربر را به صورت افقی دنبال می کند، در حالی که به صورت عمودی در مرکز خط متن فعلی ثابت می شود.
هنگام حرکت افقی، ذره بین فقط بین مرزهای چپ و راست خط فعلی حرکت می کند. علاوه بر این، هنگامی که لمس کاربر از این محدوده ها خارج می شود و فاصله افقی بین لمس و نزدیکترین کران بزرگتر از نصف عرض اصلی محتوای ذره بین است، ذره بین حذف می شود، زیرا مکان نما دیگر در داخل ذره بین قابل مشاهده نیست.
وقتی فونت متن خیلی بزرگ باشد، هرگز ذره بین فعال نمی شود. زمانی که تفاوت بین نزول و صعود فونت بزرگتر از ارتفاع محتوایی باشد که در ذره بین قرار می گیرد، متن خیلی بزرگ در نظر گرفته می شود. فعال کردن ذره بین در این مورد ارزش اضافه نمی کند.
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Implement a text magnifier\n\nTry the Compose way \nJetpack Compose is the recommended UI toolkit for Android. Learn how to use text in Compose. \n[Modifier.magnifier() →](/reference/kotlin/androidx/compose/foundation/package-summary#(androidx.compose.ui.Modifier).magnifier(kotlin.Function1,kotlin.Function1,kotlin.Float,androidx.compose.foundation.MagnifierStyle,kotlin.Function1)) \n\n\u003cbr /\u003e\n\nAvailable in Android 9 (API level 28) and later, the magnifier widget is a\nvirtual magnifying glass that displays an enlarged copy of a `View` through an\noverlay pane that represents the lens. The feature improves the text insertion\nand selection user experience. When applying the magnifier to text, a user can\nprecisely position the cursor or the selection handles by viewing the magnified\ntext in a pane that follows their finger.\n\nFigure 1 shows how the magnifier facilitates selecting text. The magnifier APIs\naren't tied to text, and you can use this widget in a variety of use cases, such\nas reading small text or enlarging hard-to-see place names on maps.\n**Figure 1.** Magnifying text. When the user drags the right selection handle, the magnifier pops up to help with accurate placement.\n\nThe magnifier is already integrated with platform widgets such as `TextView`,\n`EditText`, and `WebView`. It provides consistent text manipulation across apps.\nThe widget comes with a simple API and can be used to magnify any `View`\ndepending on your app's context.\n\nAPI usage\n---------\n\nYou can use the magnifier programmatically on an arbitrary view as follows: \n\n### Kotlin\n\n```kotlin\nval view: View = findViewById(R.id.view)\nval magnifier = Magnifier.Builder(view).build()\nmagnifier.show(view.width / 2.0f, view.height / 2.0f)\n```\n\n### Java\n\n```java\nView view = findViewById(R.id.view);\nMagnifier magnifier = new Magnifier.Builder(view).build();\nmagnifier.show(view.getWidth() / 2, view.getHeight() / 2);\n```\n\nAssuming the view hierarchy has the first layout, the magnifier displays on the\nscreen and contains a region centered on the given coordinates within the view.\nThe pane appears above the center point of the content being copied. The\nmagnifier persists indefinitely until the user dismisses it.\n| **Note:** The arguments of [`show()`](/reference/android/widget/Magnifier#show(float,%20float)) are relative to the top-left corner of the view being magnified.\n\nThe following code snippet shows how to change the background of the magnified\nview: \n\n### Kotlin\n\n```kotlin\nview.setBackgroundColor(...)\n```\n\n### Java\n\n```java\nview.setBackgroundColor(...);\n```\n\nAssuming the background color is visible within the magnifier, the magnifier's\ncontent is stale, as a region of the view with the old background still\ndisplays. To refresh the content, use the\n[`update()`](/reference/android/widget/Magnifier#update()) method, as follows: \n\n### Kotlin\n\n```kotlin\nview.post { magnifier.update() }\n```\n\n### Java\n\n```java\nview.post(magnifier::update);\n```\n| **Note:** Post the update operation to make sure that by the time this executes, the view with the new background color is already drawn. This is because the magnifier content always stays a frame behind the magnified view.\n\nWhen finished, close the magnifier by calling the\n[`dismiss()`](/reference/android/widget/Magnifier#dismiss()) method: \n\n### Kotlin\n\n```kotlin\nmagnifier.dismiss()\n```\n\n### Java\n\n```java\nmagnifier.dismiss();\n```\n\nMagnify on user interaction\n---------------------------\n\nA common use case for the magnifier is to let the user enlarge a view region by\ntouching it, as shown in figure 2.\n**Figure 2.** The magnifier follows the user's touch. It is applied to a `ViewGroup` that contains an \\`ImageView\\` to the left and a `TextView` to the right.\n\nYou can do this by updating the magnifier according to the touch events received\nby the view, as follows: \n\n### Kotlin\n\n```kotlin\nimageView.setOnTouchListener { v, event -\u003e\n when (event.actionMasked) {\n MotionEvent.ACTION_DOWN, MotionEvent.ACTION_MOVE -\u003e {\n val viewPosition = IntArray(2)\n v.getLocationOnScreen(viewPosition)\n magnifier.show(event.rawX - viewPosition[0], event.rawY - viewPosition[1])\n }\n MotionEvent.ACTION_CANCEL, MotionEvent.ACTION_UP -\u003e {\n magnifier.dismiss()\n }\n }\n true\n}\n```\n\n### Java\n\n```java\nimageView.setOnTouchListener(new View.OnTouchListener() {\n @Override\n public boolean onTouch(View v, MotionEvent event) {\n switch (event.getActionMasked()) {\n case MotionEvent.ACTION_DOWN:\n // Fall through.\n case MotionEvent.ACTION_MOVE: {\n final int[] viewPosition = new int[2];\n v.getLocationOnScreen(viewPosition);\n magnifier.show(event.getRawX() - viewPosition[0],\n event.getRawY() - viewPosition[1]);\n break;\n }\n case MotionEvent.ACTION_CANCEL:\n // Fall through.\n case MotionEvent.ACTION_UP: {\n magnifier.dismiss();\n }\n }\n return true;\n }\n});\n```\n| **Note:** The magnifier never displays magnified content that doesn't belong to the view, even when the view is included in scrollable containers and partially masked. When the coordinates passed to `show()` imply copying outside content, they are coerced inside the visible region of the view.\n\nAdditional considerations when magnifying text\n----------------------------------------------\n\nFor the platform text widgets, it's important to understand specific magnifier\nbehaviors and to enable the magnifier for your custom text view consistently\nacross the Android platform. Consider the following:\n\n- The magnifier is triggered immediately when the user grabs an insertion or selection handle.\n- The magnifier always smoothly follows the user's finger horizontally, while vertically it is fixed to the center of the current text line.\n- When moving horizontally, the magnifier moves only between the left and right bounds of the current line. Moreover, when the user's touch leaves these bounds and the horizontal distance between the touch and the closest bound is larger than half of the original width of the magnifier content, the magnifier is dismissed, as the cursor is no longer visible inside the magnifier.\n- The magnifier is never triggered when the text font is too large. Text is considered too large when the difference between the font's descent and ascent is larger than the height of the content that fits in the magnifier. Triggering the magnifier in this case doesn't add value."]]
