التحكّم في لوحة مفاتيح البرنامج وتحريكها

تجربة طريقة "إنشاء"

‫Jetpack Compose هي مجموعة أدوات واجهة المستخدم المقترَحة لنظام التشغيل Android. تعرَّف على كيفية استخدام لوحة المفاتيح في ميزة "الكتابة".

لوحة المفاتيح البرمجية في Compose →

باستخدام WindowInsetsCompat، يمكن لتطبيقك طلب بيانات من لوحة المفاتيح على الشاشة والتحكّم فيها (المعروفة أيضًا باسم IME) بطريقة مشابهة لطريقة تفاعلها مع أشرطة النظام. يمكن لتطبيقك أيضًا استخدام WindowInsetsAnimationCompat لإنشاء انتقالات سلسة عند فتح لوحة المفاتيح البرمجية أو إغلاقها.

المتطلبات الأساسية

قبل إعداد عناصر التحكّم والرسوم المتحركة للوحة المفاتيح البرمجية، اضبط تطبيقك على عرض المحتوى من الحافة إلى الحافة. ويتيح ذلك معالجة حواف نوافذ النظام، مثل أشرطة النظام ولوحة المفاتيح على الشاشة.

الصورة المتحركة التلقائية للحدود المتزامنة

بدءًا من المستوى 37.2 لواجهة برمجة التطبيقات والإصدارات الأحدث، يمكن للتطبيقات التي تستخدم تعديلات تلقائية على تخطيط النافذة (مثل SOFT_INPUT_ADJUST_RESIZE أو SOFT_INPUT_ADJUST_PAN عند عرض طريقة الإدخال باستخدام WindowInsetsController.show(WindowInsets.Type.ime())) بدون تنفيذ WindowInsetsAnimationCompat.Callback مخصّص الاستفادة من الرسوم المتحركة المتزامنة على مستوى النظام إطارًا بإطار. عند تفعيل هذه الميزة، يتم تلقائيًا تطبيق الحواف الداخلية على كل إطار وتفعيل عملية تخطيط، ما يؤدي إلى إنشاء انتقال سلس أثناء تحرّك لوحة المفاتيح.

لتفعيل هذا السلوك، أضِف علامة <property> التالية إلى نشاطك أو تطبيقك في ملف AndroidManifest.xml:

<property
    android:name="android.window.PROPERTY_COMPAT_ALLOW_SYNCHRONIZED_INSETS_ANIMATION"
    android:value="true" />

تنفيذ الرسوم المتحركة الخاصة بعمليات الإدراج خارج سلسلة التعليمات الرئيسية

بشكلٍ تلقائي، يؤدي تسجيل WindowInsetsAnimationCompat.Callback إلى فرض تشغيل الرسوم المتحركة الخاصة بإضافة مساحة داخل النافذة في سلسلة المحادثات الرئيسية للتطبيق. ويكون ذلك ضروريًا إذا كان تطبيقك يحدّث ويُزامن تخطيط العرض باستمرار أثناء الرسوم المتحركة (مثلما يحدث في الطريقة onProgress). ومع ذلك، إذا كان تطبيقك يحتاج فقط إلى الاستماع إلى عمليات الانتقال بين مراحل النشاط (مثل بدء أو إنهاء تحريك IME)، ولا يحتاج إلى تعديل طرق العرض بمعدّل كل إطار، قد يؤدي التشغيل على سلسلة التعليمات الرئيسية إلى زيادة الحمل غير الضروري وتأخُّر الحركة، خاصةً إذا كانت سلسلة التعليمات الرئيسية مشغولة.

بدءًا من المستوى 37.2 لواجهة برمجة التطبيقات والإصدارات الأحدث، يمكنك استخدام ViewTreeObserver.WindowInsetsAnimationListener لمراقبة عمليات الانتقال هذه بدلاً من ذلك. بما أنّ أداة معالجة الأحداث هذه لا تتلقّى تعديلات على مستوى التقدّم في كل إطار (لا يوجد معاودة اتصال onProgress)، يمكن للنظام تشغيل الصورة المتحركة للإزاحة على سلسلة تعليمات مخصّصة للصور المتحركة بدلاً من سلسلة التعليمات الرئيسية، ما يؤدي إلى انتقال أكثر سلاسة.

val listener = object : ViewTreeObserver.WindowInsetsAnimationListener {
  override fun onPrepare(animation: WindowInsetsAnimation) {
    // Handle preparation before animation starts
  }

  override fun onEnd(animation: WindowInsetsAnimation) {
    // Clean up temporary changes
  }
}

// Add the listener
view.viewTreeObserver.addWindowInsetsAnimationListener(listener)

// Remove the listener when no longer needed
view.viewTreeObserver.removeWindowInsetsAnimationListener(listener)

ViewTreeObserver.WindowInsetsAnimationListener listener =
    new ViewTreeObserver.WindowInsetsAnimationListener() {
      @Override
      public void onPrepare(@NonNull WindowInsetsAnimation animation) {
        // Handle preparation before animation starts
      }

      @Override
      public void onEnd(@NonNull WindowInsetsAnimation animation) {
        // Clean up temporary changes
      }
    };

// Add the listener
view.getViewTreeObserver().addWindowInsetsAnimationListener(listener);

// Remove the listener when no longer needed
view.getViewTreeObserver().removeWindowInsetsAnimationListener(listener);

التحقّق من ظهور برنامج لوحة المفاتيح

استخدِم WindowInsets للتحقّق من إمكانية رؤية لوحة المفاتيح على الشاشة.

val insets = ViewCompat.getRootWindowInsets(view) ?: return
val imeVisible = insets.isVisible(WindowInsetsCompat.Type.ime())
val imeHeight = insets.getInsets(WindowInsetsCompat.Type.ime()).bottom

WindowInsetsCompat insets = ViewCompat.getRootWindowInsets(view);
boolean imeVisible = insets.isVisible(WindowInsetsCompat.Type.ime());
int imeHeight = insets.getInsets(WindowInsetsCompat.Type.ime()).bottom;

بدلاً من ذلك، يمكنك استخدام ViewCompat.setOnApplyWindowInsetsListener لمراقبة التغييرات في إمكانية ظهور لوحة المفاتيح البرمجية.

ViewCompat.setOnApplyWindowInsetsListener(view) { _, insets ->
  val imeVisible = insets.isVisible(WindowInsetsCompat.Type.ime())
  val imeHeight = insets.getInsets(WindowInsetsCompat.Type.ime()).bottom
  insets
}

ViewCompat.setOnApplyWindowInsetsListener(view, (v, insets) -> {
  boolean imeVisible = insets.isVisible(WindowInsetsCompat.Type.ime());
  int imeHeight = insets.getInsets(WindowInsetsCompat.Type.ime()).bottom;
  return insets;
});

مزامنة الصورة المتحركة مع لوحة المفاتيح البرمجية

عندما ينقر المستخدم على حقل إدخال نص، تنزلق لوحة المفاتيح إلى مكانها من أسفل الشاشة، كما هو موضّح في المثال التالي:

• يوضّح المثال الذي يحمل التصنيف "غير متزامن" في الشكل 2 السلوك التلقائي في نظام التشغيل Android 10 (المستوى 29 من واجهة برمجة التطبيقات)، حيث يتم تثبيت حقل النص ومحتوى التطبيق في مكانهما بدلاً من مزامنتهما مع حركة لوحة المفاتيح، وهو سلوك قد يكون مزعجًا بصريًا.

• في الإصدار 11 من نظام التشغيل Android (المستوى 30 لواجهة برمجة التطبيقات) والإصدارات الأحدث، يمكنك استخدام WindowInsetsAnimationCompat لمزامنة انتقال التطبيق مع انزلاق لوحة المفاتيح للأعلى والأسفل من أسفل الشاشة. يبدو هذا أكثر سلاسة، كما هو موضّح في المثال الذي يحمل التصنيف "متزامن" في الشكل 2.

اضبط WindowInsetsAnimationCompat.Callback باستخدام طريقة العرض التي ستتم مزامنتها مع الصورة المتحركة للوحة المفاتيح.

ViewCompat.setWindowInsetsAnimationCallback(
  view,
  object : WindowInsetsAnimationCompat.Callback(DISPATCH_MODE_STOP) {
    // Override methods.
  }
)

ViewCompat.setWindowInsetsAnimationCallback(
    view,
    new WindowInsetsAnimationCompat.Callback(
        WindowInsetsAnimationCompat.Callback.DISPATCH_MODE_STOP
    ) {
      // Override methods.
    });

هناك عدة طرق لتجاوز WindowInsetsAnimationCompat.Callback، وهي onPrepare() وonStart() وonProgress() وonEnd(). ابدأ بالاتصال بالرقم onPrepare() قبل إجراء أي تغييرات على التنسيق.

يتم استدعاء onPrepare عند بدء حركة إدخال، وقبل إعادة تخطيط طرق العرض بسبب الحركة. يمكنك استخدامها لحفظ حالة البدء، وهي في هذه الحالة الإحداثي السفلي للعرض.

يعرض المقتطف التالي نموذجًا لطلب onPrepare:

var startBottom = 0f

override fun onPrepare(
  animation: WindowInsetsAnimationCompat
) {
  startBottom = view.bottom.toFloat()
}

float startBottom;

@Override
public void onPrepare(
    @NonNull WindowInsetsAnimationCompat animation
) {
  startBottom = view.getBottom();
}

يتم استدعاء onStart عند بدء صورة متحركة للعناصر الناشئة. يمكنك استخدامها لضبط جميع خصائص العرض على الحالة النهائية لتغييرات التصميم. إذا كان لديك OnApplyWindowInsetsListener تم ضبطه على أي من طرق العرض، سيتم استدعاؤه في هذه المرحلة. هذا هو الوقت المناسب لحفظ الحالة النهائية لخصائص العرض.

يعرض المقتطف التالي نموذجًا لطلب onStart:

var endBottom = 0f

override fun onStart(
  animation: WindowInsetsAnimationCompat,
  bounds: WindowInsetsAnimationCompat.BoundsCompat
): WindowInsetsAnimationCompat.BoundsCompat {
  // Record the position of the view after the IME transition.
  endBottom = view.bottom.toFloat()

  return bounds
}

float endBottom;

@NonNull
@Override
public WindowInsetsAnimationCompat.BoundsCompat onStart(
    @NonNull WindowInsetsAnimationCompat animation,
    @NonNull WindowInsetsAnimationCompat.BoundsCompat bounds
) {
  endBottom = view.getBottom();
  return bounds;
}

يتم استدعاء onProgress عندما تتغير الحواف كجزء من تشغيل صورة متحركة، لذا يمكنك إلغاءها وتلقّي إشعار بشأن كل إطار أثناء الصورة المتحركة للوحة المفاتيح. عدِّل خصائص طريقة العرض لتتحرّك بشكل متزامن مع لوحة المفاتيح.

في هذه المرحلة، تكون جميع تغييرات التنسيق قد اكتملت. على سبيل المثال، إذا كنت تستخدم View.translationY لنقل العرض، تنخفض القيمة تدريجيًا مع كل استدعاء لهذه الطريقة، وتصل في النهاية إلى 0 في موضع التنسيق الأصلي.

يعرض المقتطف التالي نموذجًا لطلب onProgress:

override fun onProgress(
  insets: WindowInsetsCompat,
  runningAnimations: MutableList<WindowInsetsAnimationCompat>
): WindowInsetsCompat {
  // Find an IME animation.
  val imeAnimation = runningAnimations.find {
    it.typeMask and WindowInsetsCompat.Type.ime() != 0
  } ?: return insets

  // Offset the view based on the interpolated fraction of the IME animation.
  view.translationY =
    (startBottom - endBottom) * (1 - imeAnimation.interpolatedFraction)

  return insets
}

@NonNull
@Override
public WindowInsetsCompat onProgress(
    @NonNull WindowInsetsCompat insets,
    @NonNull List<WindowInsetsAnimationCompat> runningAnimations
) {
  // Find an IME animation.
  WindowInsetsAnimationCompat imeAnimation = null;
  for (WindowInsetsAnimationCompat animation : runningAnimations) {
    if ((animation.getTypeMask() & WindowInsetsCompat.Type.ime()) != 0) {
      imeAnimation = animation;
      break;
    }
  }
  if (imeAnimation != null) {
    // Offset the view based on the interpolated fraction of the IME animation.
    view.setTranslationY((startBottom - endBottom)

        *   (1 - imeAnimation.getInterpolatedFraction()));
  }
  return insets;
}

يمكنك اختياريًا إلغاء onEnd. يتم استدعاء هذه الطريقة بعد انتهاء الصورة المتحركة. هذا هو الوقت المناسب لإزالة أي تغييرات مؤقتة.

مراجع إضافية

• WindowInsetsAnimation على GitHub