پیاده‌سازی ذره‌بین نوشتار

امتحان کردن روش Compose
Jetpack Compose جعبه‌ابزار واسط کاربر توصیه‌شده برای Android است. با نحوه استفاده از نوشتار در Compose آشنا شوید.
Modifier.magnifier() →

ابزاره بزرگ‌نمایی که در Android نسخه ۹ (سطح API‏ ۲۸) و نسخه‌های جدیدتر دردسترس است، ذره‌بین مجازی‌ای است که نسخه بزرگ‌شده View را ازطریق صفحه هم‌پوشانی که نشان‌دهنده لنز است نمایش می‌دهد. این ویژگی تجربه کاربری درج و انتخاب نوشتار را بهبود می‌بخشد. هنگام اعمال ذره‌بین روی نوشتار، کاربر می‌تواند با مشاهده نوشتار بزرگ‌شده در قاب دنبال‌کننده انگشت، مکان‌نما یا دستگیره‌های انتخاب را به‌طور دقیق قرار دهد.

شکل ۱ نشان می‌دهد که ذره‌بین چگونه انتخاب نوشتار را تسهیل می‌کند. میاناهای برنامه‌سازی کاربردی ذره‌بین به نوشتار وابسته نیستند و می‌توانید از این ابزاره در موارد استفاده مختلفی استفاده کنید، مثلاً خواندن نوشتار کوچک یا بزرگ کردن نام مکان‌هایی که به‌سختی در نقشه‌ها دیده می‌شوند.

تصویری که نشان می‌دهد پس‌از گرفتن دسته انتخاب راست، ذره‌بین چگونه ظاهر می‌شود
شکل ۱. درحال درشت‌نمایی نوشتار. وقتی کاربر دستگیره انتخاب سمت راست را می‌کشد، ذره‌بین بالا می‌آید تا به جای‌گذاری دقیق کمک کند.

ذره‌بین ازقبل با ابزاره‌های پلاتفرم مثل TextView، EditText، و WebView ادغام شده است. این ویژگی امکان دستکاری هماهنگ نوشتار را در برنامه‌های مختلف فراهم می‌کند. این ابزاره با یک میانای برنامه‌سازی کاربردی ساده ارائه می‌شود و می‌توان از آن برای بزرگ‌نمایی هر View بسته به بافتار برنامه‌تان استفاده کرد.

استفاده از میانای برنامه‌سازی کاربردی

می‌توانید از ذره‌بین به‌صورت برنامه‌نویسی‌شده در نمای دلخواه به‌صورت زیر استفاده کنید:

کاتلین

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

درشت‌نمایی هنگام تعامل کاربر

یک مورد استفاده رایج برای ذره‌بین این است که به کاربر اجازه می‌دهد با لمس کردن یک ناحیه از نما، آن را بزرگ کند، همان‌طور که در شکل ۲ نشان داده شده است.

شکل ۲. ذره‌بین لمس کاربر را دنبال می‌کند. این ویژگی به ViewGroup اعمال شده است که حاوی `ImageView` در سمت چپ و TextView در سمت راست است.

می‌توانید این کار را با به‌روزرسانی ذره‌بین براساس رویدادهای لمسی دریافتی توسط نما به‌صورت زیر انجام دهید:

کاتلین

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 فعال کنید. موارد زیر را درنظر بگیرید:

  • وقتی کاربر دسته درج یا انتخاب را می‌گیرد، ذره‌بین بلافاصله فعال می‌شود.
  • ذره‌بین همیشه به‌آرامی انگشت کاربر را به‌صورت افقی دنبال می‌کند، درحالی‌که به‌صورت عمودی روی مرکز خط نوشتار فعلی ثابت است.
  • هنگام حرکت افقی، ذره‌بین فقط بین مرزهای چپ و راست خط فعلی حرکت می‌کند. علاوه‌براین، وقتی لمس کاربر از این مرزها خارج می‌شود و فاصله افقی بین لمس و نزدیک‌ترین مرز بیشتر از نصف عرض اصلی محتوای ذره‌بین است، ذره‌بین بسته می‌شود، زیرا مکان‌نما دیگر در داخل ذره‌بین قابل‌مشاهده نیست.
  • وقتی قلم نوشتار خیلی بزرگ باشد، ذره‌بین هرگز فعال نمی‌شود. وقتی تفاوت بین نزول و صعود قلم بزرگ‌تر از ارتفاع محتوایی باشد که در ذره‌بین جا می‌شود، نوشتار بیش‌ازحد بزرگ درنظر گرفته می‌شود. در این مورد، فعال کردن ذره‌بین ارزشی اضافه نمی‌کند.