navigationevent

  
توفّر مكتبة "حدث التنقّل" واجهة برمجة تطبيقات متوافقة مع KMP للتعامل مع الرجوع إلى الخلف في النظام بالإضافة إلى ميزة الرجوع التنبؤي.
آخر الأخبار الإصدار الثابت إصدار محتمل الإصدار التجريبي الإصدار الأوّلي
‫8 أكتوبر 2025 - - 1.0.0-beta01 -

تحديد الاعتماديات

لإضافة اعتمادية على navigationevent، يجب تضمين مستودع Google Maven في مشروعك. اطّلِع على مستودع Maven من Google لمزيد من المعلومات.

أضِف الاعتماديات الخاصة بالعناصر التي تحتاج إليها في ملف build.gradle لتطبيقك أو وحدتك:

Groovy

dependencies {
    implementation "androidx.navigationevent:navigationevent:1.0.0-beta01"
}

Kotlin

dependencies {
    implementation("androidx.navigationevent:navigationevent:1.0.0-beta01")
}

لمزيد من المعلومات حول الاعتماديات، يُرجى الاطّلاع على إضافة اعتماديات البناء.

الملاحظات

تساعدنا ملاحظاتك في تحسين Jetpack. يُرجى إعلامنا إذا اكتشفت مشاكل جديدة أو كانت لديك أفكار لتحسين هذه المكتبة. يُرجى الاطّلاع على المشاكل الحالية في هذه المكتبة قبل إنشاء مشكلة جديدة. يمكنك إضافة صوتك إلى مشكلة حالية من خلال النقر على زر النجمة.

إنشاء مشكلة جديدة

يُرجى الاطّلاع على مستندات Issue Tracker للحصول على مزيد من المعلومات.

لا تتوفّر ملاحظات إصدار لهذا العنصر.

الإصدار 1.0

الإصدار 1.0.0-beta01

‫8 أكتوبر 2025

تم طرح androidx.navigationevent:navigationevent-*:1.0.0-beta01. يتضمّن الإصدار 1.0.0-beta01 هذه التعديلات.

تغييرات واجهة برمجة التطبيقات

  • تصحيح التعليق التوضيحي FloatRange الخاص بـ NavigationEvent.touchX وNavigationEvent.touchY تمثّل هذه القيم إحداثيات البكسل المطلقة وليس لها حدّ أعلى 1.0. (I4b205، b/445989313)
  • أعِد تصميم الدالة البرمجية القابلة للإنشاء NavigationEventDispatcherOwner لتصبح rememberNavigationEventDispatcherOwner. تعرض الدالة الآن NavigationEventDispatcherOwner مباشرةً. لتوفير هذا المالك لتركيبة فرعية، استخدِم CompositionLocalProvider. (I874b2، b/444446629)

الإصدار 1.0.0-alpha09

‫24 سبتمبر 2025

تم طرح androidx.navigationevent:navigationevent-*:1.0.0-alpha09. يتضمّن الإصدار 1.0.0-alpha09 هذه التعديلات.

تغييرات واجهة برمجة التطبيقات

  • استخدِم عنصر NavigationEventTransitionState.Idle الفردي مباشرةً بدلاً من إنشاء مثيل Idle(). (Ic7d9e، b/444734264)
  • اجعل دوال الإنشاء المريحة داخلية، واحصل على مثيلات من خلال NavigationEventDispatcher.history العامة بدلاً من الإنشاء المباشر. (I3b7e0، b/444734264)
  • يجب إنشاء NavigationEventState من خلال rememberNavigationEventState، وأصبحت طريقة وضع التصميم داخلية. (Ie143c، b/444734264)
  • استخدِم onBackCompletedFallback بدلاً من fallbackOnBackPressed ومَعلمة الدالة الإنشائية. لم يتغيّر السلوك، ويتم استدعاؤه فقط عند اكتمال أحداث الرجوع غير المعالَجة. (Idabe9، b/444734264)
  • أصبح الآن المنشئ الأساسي للفئة NavigationEventHistory(mergedHistory, currentIndex) هو internal. يجب أن يستخدم المستهلكون الخارجيون أدوات الإنشاء العامة (إما أداة الإنشاء الفارغة أو أداة الإنشاء المستندة إلى الأقسام) لإنشاء مثيلات. (I1c047، b/444734264)
  • إتاحة قبول مالك قابل للقيم الخالية في View.setViewTreeNavigationEventDispatcherOwner (Ic9eb6، b/444436762)
  • أصبح NavigationEventInfo الآن abstract class بدلاً من interface. عدِّل جميع عمليات التنفيذ المخصّصة لتكون مشتقة من الفئة (مثل data class MyInfo : NavigationEventInfo()). (I1e59c، b/444734264)
  • تمت إزالة السمة القديمة NavigationEventDispatcher.state والدالة getState<T>(). استخدِم مسارَي dispatcher.transitionState (لتقدُّم الإيماءة) وdispatcher.history (لمجموعة التنقّل) الجديدَين والمنفصلَين. (Ic2ceb، b/444734264)
  • تم استبدال دالة الاستدعاء NavigationEventInput.onInfoChanged(...). نفِّذ وظيفة الاستدعاء الجديدة onHistoryChanged(history: NavigationEventHistory) لتلقّي التحديثات ككائن NavigationEventHistory واحد. (I23e0b، b/444734264)
  • إطلاق NavigationEventDispatcher.history StateFlow عالمي جديد يتيح هذا المسار غير العام للمراقبين الاشتراك فقط في التغييرات التي تطرأ على حزمة التنقّل، ويظل ثابتًا أثناء تقدّم الإيماءة. هذا هو الجزء المقابل لـ transitionState. (I1db10، b/444734264)
  • إطلاق NavigationEventDispatcher.transitionState StateFlow عالمي جديد يتيح هذا المسار غير العام للمراقبين الاشتراك فقط في حالة الإيماءة الجسدية (Idle/InProgress)، بشكل منفصل عن السجلّ. (I171fa، b/444734264)
  • قدِّم صف NavigationEventHistoryState. ستكون هذه هي واجهة برمجة التطبيقات الأساسية لتتبُّع سجلّ معلومات التنقّل، بشكل منفصل عن حالة الإيماءة. (I81ca5، b/444734264)
  • تم الآن وضع علامة @Immutable على NavigationEvent، ما يتيح لبرنامج Compose Compiler تحسين عمليات إعادة التركيب. (If78c7، b/444734264)
  • تم تعديل واجهات برمجة التطبيقات لمعالج navigationevent-compose. يتوافق النوعان NavigationEventHandler وNavigationBackHandler (والأنواع الفرعية) الآن مع تحميل زائد جديد يقبل NavigationEventStates تم نقلها إلى الأعلى. يتم الاحتفاظ بعمليات التحميل الزائد البسيطة (التي تتضمّن currentInfo) وتستخدم الآن نموذج الحالة الجديد هذا داخليًا. (Ic3251، b/444734264)
  • أضِف أداة معالجة الحالة الجديدة @Stable NavigationEventState<T> إلى مكتبة navigationevent-compose. يجمع هذا العنصر بين السجلّ المحلي وحالة الإيماءة المحلية، وسيكون الرابط الأساسي بين rememberNavigationEventState وNavigationEventHandler. (Ifb69f، b/444734264)
  • أضِف سمة transitionState: TransitionState جديدة عامة للقراءة فقط إلى NavigationEventHandler. تحتفظ المعالجات الآن بحالة الانتقال الخاصة بها، ويمكن للأنظمة الخارجية مراقبتها. (I9acd2، b/444734264)
  • نقدّم لك فئة TransitionState الجديدة المحكمة الإغلاق. ستكون هذه الواجهة بمثابة واجهة برمجة التطبيقات الأساسية لمراقبة حالة الإيماءة، بشكل منفصل عن سجلّ التنقّل. (Id4beb، b/444734264)
  • عرض currentInfo وbackInfo وforwardInfo كسمات عامة للقراءة فقط على NavigationEventHandler (Ia7636، b/444734264)
  • يجب أن توفّر عمليات تنفيذ NavigationEventHandler الآن قيمة initialInfo: T لمنشئ الفئة الأساسية. (Idcfea، b/444734264)
  • استبدِل OnBackInvokedInput بـ OnBackInvokedOverlayInput أو OnBackInvokedDefaultInput. (I5323f، b/428948766)
  • وضع علامة NavigationEventState كـ @Immutable يؤدي ذلك إلى تحسين أداء Compose من خلال التأكّد من أنّ العناصر القابلة للإنشاء التي تراقب هذه الحالة يمكنها تخطّي إعادة التركيب بشكل صحيح. (I399c8)
  • أعِد تسمية NavigationEventInfo.NotProvided إلى NavigationEventInfo.None; لتعديل المراجع. لن يتغير السلوك. (I5e2d4)
  • تم الآن وضع علامة @Immutable على NavigationEventInfo، ما يتيح لبرنامج Compose Compiler تحسين عمليات إعادة التركيب. (I7c112)
  • تحسين سهولة استخدام Java من خلال واجهة ممتعة لتوفير وظيفة احتياطية لإكمال الرجوع (I8a860)
  • تمّت إعادة تسمية onHasEnabledHandlerChanged إلى onHasEnabledHandlersChanged. يوضّح ذلك أنّ تقارير معاودة الاتصال تتضمّن حالة التفعيل الجماعي لجميع المعالِجات، وليس معالِجًا واحدًا فقط. (I1af61، b/443711297)
  • أزِل hasEnabledHandler() من NavigationEventDispatcher; واستخدِم NavigationEventInput.onHasEnabledHandlersChanged بدلاً منه. (Idef72، b/443711297)
  • أضِف onInfoChanged callback إلى NavigationEventInput لإعلام المستمعين بالتغييرات في سجلّ التنقّل. يوفّر ذلك السياق الكامل لمجموعات التراجع والتقدّم الحالية، ما يتيح لـ Inputs التفاعل مع المعلومات السياقية. (I69a8b، b/443282983)
  • اجعل NavigationEvent swipeEdge @IntDef (Icee54، b/443950342)
  • أضِف المَعلمة priority إلى NavigationEventDispatcher.addInput لتحديد نطاق أولوية واحدة للمرسِل، ولن يتم الآن تنشيط أحداث مثل onHasEnabledCallbacksChanged إلا عند تغيير معاودة الاتصال بهذه الأولوية. (I3e488، b/443711297)
  • أعِد تسمية المَعلمة NavigationEventDispatcher من parentDispatcher إلى parent لتوضيحها. (Id4f1f، b/443801782)
  • إزالة NavigationEventPriority واستخدام @IntDef بدلاً منها لمستخدمي Java (I10a9f، b/440514265)
  • فرض عقد معالج التنقّل إذا كانت قيمة NavigationEventHandler تحدّد قيمة isBackEnabled أو isForwardEnabled على أنّها true، عليك الآن تجاهل onBackCompleted أو onForwardCompleted على التوالي. تُصدر عمليات التنفيذ التلقائية الآن استثناءً لمنع حدوث أخطاء غير ظاهرة. (I17c62)
  • فرض قيم أولوية صالحة عند إضافة معالِجات أحداث التنقّل سيؤدي الآن استدعاء addHandler بأولوية غير متوافقة إلى عرض IllegalArgumentException، ما يوفّر ملاحظات فورية بشأن الاستخدام غير الصحيح على جميع الأنظمة الأساسية المستهدَفة. (I3c474)

إصلاح الأخطاء

  • اجعل addHandler عديم التأثير الجانبي، وتجاهَل عمليات التسجيل المكرّرة. (I052aa، b/444734264)
  • الحفاظ على مزامنة خصائص NavigationEventState أثناء إعادة التركيب (Ib3b4d، b/444734264)
  • تأكَّد من أنّ NavigationEventInputs تتلقّى معلومات السياق الحالية (الحالية والسابقة والتالية) فور التسجيل. (Ie65bf، b/443282983)

الإصدار 1.0.0-alpha08

‫10 سبتمبر 2025

تم طرح androidx.navigationevent:navigationevent-*:1.0.0-alpha08. يتضمّن الإصدار 1.0.0-alpha08 هذه التعديلات.

الميزات الجديدة

  • إضافة واجهة برمجة تطبيقات NavigationEventHandler مستندة إلى تعبير lambda تحلّ محلّ معالج Flow-based. التعامل مع إيماءات الرجوع والتقدّم باستخدام عمليات ردّ نداء بسيطة بدلاً من جمع التدفقات، ما يقلّل من النصوص النموذجية ويتجنّب مشاكل الإلغاء توفير NavigationBackHandler وNavigationForwardHandler كواجهات برمجة تطبيقات مستهدَفة لتسهيل الاستخدام إزالة NavigationEventHandler المستند إلى Flow ونقل البيانات إلى عمليات معاودة الاتصال الجديدة (I23bac، b/436248277)
  • السماح للمستمعين غير النشطين بالوصول إلى حزمة التنقّل الكاملة السابقة من خلال معلومات الرجوع المجمّعة، والسماح لواجهات المستخدم بعرض المعاينات وسجلّ التنقّل المتداخل بدلاً من الاقتصار على معاودة الاتصال الأعلى. (I7a510، b/436248277)
  • تقديم نموذج صريح للخلف/الحالي/الأمام لتوضيح حالة التنقّل وإتاحة التنقّل للأمام باستخدام معالِجات متداخلة (Ib86da، b/420443609)
  • أضِف طرق onForward* وisForwardEnabled إلى NavigationEventCallback. (Ic100f، b/436248290)
  • إضافة إمكانية الانتقال إلى الصفحة التالية في NavigationEventInput (I5734b)

تغييرات واجهة برمجة التطبيقات

  • فعِّل اختبار أحداث التنقّل للأمام باستخدام TestNavigationEventCallback. استخدِم الخطافَين isForwardEnabled وonForward*. (I21fb5، b/420443609)
  • إعادة تسمية عمليات رد الاتصال onEvent* إلى onBack* في NavEvent (I228b3، b/436248290)
  • تحويل SwipeEdge إلى فئة مضمّنة (Id5e01)
  • اجعل مكتبة navigationevent قابلة للتشغيل التفاعلي مع Java. يمكن الآن الوصول إلى جميع واجهات برمجة التطبيقات العامة بالكامل من رمز Java البرمجي، ما يتيح الدمج السلس في المشاريع المختلطة اللغات أو المشاريع التي تستخدم Java فقط. (Ibc944،I5465f، I9fb1e، b/440532890b/443040294)
  • توضيح أدوار واجهة برمجة التطبيقات من خلال إعادة تسمية NavigationEventCallback إلى NavigationEventHandler يعكس هذا التغيير بشكل أفضل الغرض من الفئة وهو التعامل مع إيماءات التنقّل المتعدّدة المراحل. أصبحت طريقة addCallback المقابلة الآن addHandler. (I2492a، b/443040331)

إصلاح الأخطاء

  • منع تشغيل عملية الرجوع الاحتياطية عند التنقّل للأمام (I74814، b/436248290)
  • إضافة ميزة التنقّل التوقّعي للأمام NavigationEvent تتعامل واجهات برمجة التطبيقات الآن مع إيماءات الرجوع والتقدّم، ما يتيح عرض صور متحركة متسقة لكلا الاتجاهين. (Idc98c، b/436248290)
  • منع حدوث عطل في IllegalStateException أثناء إعادة الإنشاء عند إزالة عنصر فرعي NavigationEventDispatcherOwner (Iff50c، b/412629020)
  • يمكن للمستمعين غير النشطين الآن الوصول إلى حزمة التنقّل الكاملة السابقة من خلال معلومات الرجوع المجمّعة، ما يتيح لواجهات المستخدم عرض معاينات وسجلّ التنقّل المتداخل بدلاً من الاقتصار على معاودة الاتصال في أعلى الصفحة. (I7a510، b/436248277)

الإصدار 1.0.0-alpha07

‫27 أغسطس 2025

تم طرح androidx.navigationevent:navigationevent-*:1.0.0-alpha07. يتضمّن الإصدار 1.0.0-alpha07 هذه التعديلات.

تغييرات واجهة برمجة التطبيقات

  • إزالة NavigationEventDispatcher.onHasEnabledCallbacksChanged (I50e97)
  • اجعل NavigationEventCallback.onEventCompleted() مجرّدة. (I36b38)
  • غيِّر طرق NavigationEventCallback#on* إلى protected. عدِّل رمز الاتصال لتجاوزها. (I6b691)
  • إعادة تسمية دوال DirectNavigationEventInput (Iffb62)
  • تمّت إعادة تسمية NavigationEventInput.onAttach إلى onAdded. (I2d0b8)
  • تمّت إعادة تسمية NavigationEventInput.onDetach إلى onRemoved. (I2d0b8)
  • تمّت إعادة تسمية NavigationEventInputHandler إلى NavigationEventInput. (I676a4)
  • إضافة @EmptySuper إلى NavigationEventInput.onHasEnabledCallbacksChanged (If9853)
  • تنفيذ onAttach في NavigationEventInputHandler (I03648)
  • تنفيذ onDetach في NavigationEventInputHandler (I03648)
  • يتم ضبط NavigationEventCallback على "مفعَّل" عند الإنشاء. (Ic0188)
  • استبدِل NavigationEventInput.addOnHasEnabledCallbacksChangedCallback بـ NavigationEventInput.onHasEnabledCallbacksChanged. (I64e93)
  • يجب استخدام سلسلة التعليمات الرئيسية لتنفيذ NavigationEventDispatcher.addInput. (Ic2930)
  • يجب استخدام سلسلة التعليمات الرئيسية لتنفيذ NavigationEventDispatcher.removeInput. (Ic2930)
  • إزالة Dispatcher.addOnHasEnabledCallbacksChangedCallback استبدِلها بـ "Dispatcher.onHasEnabledCallbacksChanged". (Ida3e3، b/436530096)

إصلاح الأخطاء

  • إصلاح الخطأ الذي يؤدي إلى تشغيل منطق دورة الحياة غير الصحيح عند إضافة معالج مرفق أو إزالة معالج غير مرفق (I9e47b)

الإصدار 1.0.0-alpha06

‫13 أغسطس 2025

تم طرح androidx.navigationevent:navigationevent-*:1.0.0-alpha06. يتضمّن الإصدار 1.0.0-alpha06 هذه التعديلات.

الميزات الجديدة

Passive Listeners API

يمكنك الآن تمرير معلومات سياقية مخصّصة من أي مضيف تنقّل والاستماع بشكل غير مباشر إلى تغييرات حالة الإيماءات من أي مكان في واجهة المستخدم. يتيح ذلك الصور المتحركة الواعية بالسياق لإيماءة الرجوع إلى الخلف التنبؤية وغيرها من عمليات التنقّل المستندة إلى الإيماءات.

تتضمّن هذه الميزة جزأين:

  1. توفير المعلومات: استخدِم NavigationEventInfo لنقل البيانات المخصّصة.
  2. حالة الاستهلاك: استخدِم dispatcher.state (NavigationEventState) لمراقبة تقدّم الإيماءة وسياقها.
  • تعرض السمة NavigationEventCallback الآن الطريقة setInfo(currentInfo, previousInfo) لضبط سياق الإيماءة في مكالمة واحدة (I1d5e7، b/424470518).
  • تضيف NavigationEventHandler حمولة زائدة جديدة تقبل currentInfo وpreviousInfo، ما يجعلها واجهة برمجة التطبيقات الأساسية لتوفير السياق في تطبيقات Compose (I6ecd3، b/424470518).

مثال:

  data class MyScreenInfo(val screenName: String) : NavigationEventInfo

  NavigationEventHandler(
      enabled = true,
      currentInfo = MyScreenInfo("Details Screen"),
      previousInfo = MyScreenInfo("Home Screen")
  ) { /* Handle back completion */ }
  • تعرض السمة NavigationEventDispatcher الآن السمتَين dispatcher.state وdispatcher.getState<T>() (If7fae وIa90ca وb/424470518). تتيح واجهات برمجة التطبيقات المستندة إلى StateFlow لأي واجهة مستخدم مراقبة تقدّم الإيماءة والبيانات السياقية بدون معالجة الحدث مباشرةً.

مثال:

  val gestureState by LocalNavigationEventDispatcherOwner.current!!
      .navigationEventDispatcher
      .state
      .collectAsState()

  val progress = gestureState.progress // Returns latestEvent.progress or 0F

  when (val state = gestureState) {
      is InProgress -> {
          val toScreen = state.currentInfo as MyScreenInfo
          val fromScreen = state.previousInfo as MyScreenInfo
          println("Navigating from ${fromScreen.screenName} to ${toScreen.screenName}")
      }
      is Idle -> { /* Idle state */ }
  }

  • أضِف السمة progress إلى NavigationEventState (I7b196) التي تعرض latestEvent.progress عندما تكون الحالة "قيد التقدّم"، أو 0F في الحالات الأخرى:

    val progress = state.progress

  • أضِف NavigationEventDispatcherOwner composable لإنشاء مثيلات NavigationEventDispatcher وربطها والتخلص منها بشكل هرمي. تفعيل التحكّم الديناميكي في حالة التفعيل في أداة الإرسال والتنظيف التلقائي

    @Composable
fun Sample() {
    NavigationEventDispatcherOwner(enabled = true) {
        val localDispatcherOwner = LocalNavigationEventDispatcherOwner.current
    }
}

تغييرات واجهة برمجة التطبيقات

  • تمّت إزالة المَعلمة isPassthrough من NavigationEventCallback. (I99028، b/424470518)
  • أصبحت دوال الإنشاء NavigationEventState داخلية الآن. لإجراء الاختبار، عدِّل الحالة (القيمة التلقائية هي Idle) من خلال DirectNavigationEventInputHandler. اتّصِل بالرقم handleOnStarted أو handleOnProgressed لضبط الحالة على InProgress، وبالرقم handleOnCompleted أو handleOnCancelled لإعادتها إلى Idle. لتحديث NavigationEventInfo، استخدِم NavigationEventCallback.setInfo. (I93dca، b/424470518)
  • تمت إضافة مَعلمات تلقائية إلى NavigationEvent للسماح بإنشاء مثيل أسهل ولتبسيط الاختبار الذي يجب استخدامه بدلاً من TestNavigationEvent. (I5dc49, I232f4)
  • تمت إضافة TestNavigationEventCallback لاختبار أحداث التنقّل بحالات حالية/سابقة معيّنة. (Idd22e، b/424470518)
  • تم تحويل NavigationEventInputHandler إلى فئة مجرّدة لاستبدال AbstractNavigationEventInputHandler السابقة بتنفيذ في DirectNavigationEventInputHandler (Iadde5، Ifed40I3897c، b/432616296، b/435416924)
  • تمت إعادة تسمية البادئات الخاصة بالدوال send* في NavigationEventInputHandler إلى handle*. (Iffcaf)
  • توسّع OnBackInvokedInputHandler الآن نطاق abstract NavigationInputHandler الجديد. (Ib45aa)
  • تم تغيير NavigationEventDispatcherOwner ليتطلّب موزعًا رئيسيًا يجب فيه تمرير null بشكل صريح لإنشاء موزع رئيسي. (Ia6f64، b/431534103)

إصلاح الأخطاء

  • تحسين الكفاءة من خلال تجنُّب نُسخ المجموعات في NavigationEventDispatcher.dispose() (I4ab09)
  • تم حلّ المشكلة المتمثّلة في عدم استجابة NavigationEventHandler بشكلٍ صحيح للتغييرات في حالته المفعّلة. (Ia5268 وI19bec وI5be5c وb/431534103)

آخر الأخبار في "مستندات Google"

  • تم توسيع نطاق KDocs الخاص بـ NavigationEvent لتوضيح دوره كغلاف موحّد للأحداث وسلوك خاصية التفاصيل في مختلف أنواع التنقّل (الإيماءات والنقرات). (I91e8d)
  • تم تعديل المستندات الخاصة بواجهات برمجة التطبيقات (BackHandler وPredictiveBackHandler وNavigationEventHandler) التي تتعامل مع الرجوع إلى الخلف على مستوى النظام لتوضيح السلوك المتعلق بترتيب معاودة الاتصال. (I7ab94, )

تحديث الاعتماديات

  • يعتمد الإصدار NavigationEvent الآن على Compose Runtime 1.9.0-beta03 الذي يتيح للعنصر navigationevent-compose دعم جميع أهداف KMP. (Ia1b87)

الإصدار 1.0.0-alpha05

‫30 يوليو 2025

تم طرح androidx.navigationevent:navigationevent-*:1.0.0-alpha05. يتضمّن الإصدار 1.0.0-alpha05 هذه التعديلات.

إتاحة التدرّج الهرمي بين الحسابات الرئيسية والفرعية:

يمكن أن يحتوي NavigationEventDispatcher الآن على أدوات إرسال رئيسية وثانوية، ما يؤدي إلى إنشاء بنية شجرية هرمية. يتيح ذلك نشر أحداث التنقّل وإدارتها بمرونة أكبر على مستوى مكوّنات واجهة المستخدم المعقّدة في Compose من خلال عرض التسلسل الهرمي البنيوي لواجهة المستخدم من خلال أدوات إرسال متسلسلة. (I194ac)

  // Create a parent dispatcher that will manage navigation events at a higher level.
  val parentDispatcher = NavigationEventDispatcher()

  // Create a child dispatcher linked to the parent, forming a hierarchy.
  val childDispatcher = NavigationEventDispatcher(parentDispatcher)

تتيح السمة الهرمية isEnabled التحكّم في أداة إرسال من أعلى إلى أسفل. عند ضبط isEnabled على false في أداة إرسال، يتم تلقائيًا إيقاف جميع أدوات الإرسال الفرعية. تتيح هذه الميزة إيقاف فروع كاملة من نظام أحداث التنقّل بكفاءة. (I9e985)

  // Disabling the child dispatcher disables all its callbacks and any of its children recursively.
  childDispatcher.isEnabled = false

بالإضافة إلى ذلك، تراعي السمة isEnabled في NavigationEventCallback الآن حالة التفعيل الخاصة ببرنامج الإرسال المرتبط بها. وهذا يعني أنّه لا يتم اعتبار معاودة الاتصال مفعَّلة إلا إذا تم تفعيل كلّ من معاودة الاتصال نفسها وبرنامج إرسالها (بما في ذلك العناصر الرئيسية)، ما يضمن التحكّم الهرمي المتسق في تفعيل معاودة الاتصال. (I1799a)

  // Create a test callback and add it to the child dispatcher.
  val callback1 = TestNavigationEventCallback(isEnabled = true)
  childDispatcher.addCallback(callback1)

  // Since the childDispatcher is disabled, the callback is effectively disabled as well.
  assertThat(callback1.isEnabled).isFalse()

تم تقديم طريقة dispose() جديدة لتنظيف أدوات الإرسال والعناصر التابعة لها بشكل سليم. يؤدي استدعاء dispose() إلى إيقاف المستمعين لمنع تسرُّب الذاكرة، وإزالة جميع أدوات معالجة الأحداث التابعة بشكل متكرر، وإزالة جميع عمليات معاودة الاتصال المسجّلة في أداة معالجة الأحداث، وإلغاء ربطها بالعنصر الرئيسي. يضمن ذلك تحرير الموارد بشكل صحيح عندما لا تعود هناك حاجة إلى أدوات الإرسال. (I9e985)

  // Dispose the child dispatcher to clean up resources.
  childDispatcher.dispose()

إذا تم استدعاء أي طريقة عامة على أداة معالجة تم التخلص منها، سيتم طرح IllegalStateException على الفور. يمنع ذلك حدوث أخطاء غير ظاهرة ويساعد المطوّرين في تحديد الاستخدام غير السليم أثناء عملية التطوير. (Ic2dc3)

  val callback2 = TestNavigationEventCallback()

  // Attempting to use a disposed dispatcher will throw an exception.
  assertThrows<IllegalStateException> {
      childDispatcher.addCallback(callback2)
  }

ملاحظة: سنطرح NavigationEventDispatcherOwner Composable جديدًا يدير تلقائيًا أداة إرسال تابعة في واجهة مستخدم Compose ضمن aosp/3692572. ومع ذلك، لم يتم تضمين هذا التغيير في الإصدار الحالي، ومن المقرر إدراجه في الإصدار التالي.

Navigation Testing Library

  • أضِف وحدة navigationevent-testing لتوفير أدوات اختبار مخصّصة لمكتبة navigationevent. (0e50b6)
  • أضِف فئة أدوات مساعدة وهمية TestNavigationEventCallback للاختبار. تسجّل هذه السمة طلبات طريقة رد الاتصال وتخزّن عناصر NavigationEvent المستلَمة للمساعدة في عملية التحقّق. (4a0246)
  • أضِف الدالة المساعدة الوهمية TestNavigationEvent لإنشاء مثيلات NavigationEvent بالقيم التلقائية، ما يسهّل اختبارات الوحدات لمعالجة أحداث التنقّل. (3b63f5)
  • أضِف فئة أدوات مساعدة وهمية TestNavigationEventDispatcherOwner للاختبار. يتتبّع هذا العداد عدد أحداث "الرجوع إلى الحالة السابقة" و"تغيير الحالة إلى مفعَّلة" لدعم التحقّق من التفاعل في الاختبارات. (c8753e)

تغييرات واجهة برمجة التطبيقات

  • انقل NavigationEventInputHandler من androidMain إلى commonMain لإتاحته في الرمز البرمجي المشترك في KMP. تمت إضافة طرق public send* جديدة لإرسال الأحداث. تغيير دوال الإرسال في NavigationEventDispatcher من public إلى internal، ويجب أن يستخدم المستخدمون الآن NavigationEventInputHandler لإرسال الأحداث (Ia7114)
  • تمّت إعادة تسمية NavigationInputHandler إلى OnBackInvokedInputHandler. (I63405)

إصلاح الأخطاء

  • أعِد تصميم NavigationEventDispatcher لتقليل الحمل الزائد من خلال تجنُّب عمليات تخصيص القوائم الوسيطة وتحسين أداء إرسال معاودة الاتصال. (I82702، I1a9d9)
  • أضِف تعليقات توضيحية @FloatRange إلى الحقول touchX وtouchY وprogress في NavigationEvent لفرض نطاقات القيم الصالحة في وقت الترجمة وتحسين أمان واجهة برمجة التطبيقات. (Iac0ec)

الإصدار 1.0.0-alpha04

‫2 يوليو 2022

تم طرح androidx.navigationevent:navigationevent-*:1.0.0-alpha04. يتضمّن الإصدار 1.0.0-alpha04 هذه التعديلات.

إصلاح الأخطاء

  • تم استخدام implementedInJetBrainsFork إلى navigationevent-compose وإضافة هدف commonStubs ليتوافق مع اصطلاحات Compose. تم طلب التغيير من قِبل JetBrains. (f60c79)
  • تم إصلاح تطبيق مكوّن إضافي لمترجم Compose في Kotlin/Native لضمان إنشاء رمز تجريبي صحيح. لن يؤثّر ذلك في واجهات برمجة التطبيقات أو السلوكيات العامة. (1890c9)

الإصدار 1.0.0-alpha03

‫18 يونيو 2025

تم طرح androidx.navigationevent:navigationevent-*:1.0.0-alpha03. يتضمّن الإصدار 1.0.0-alpha03 هذه التعديلات.

الميزات الجديدة

  • تم تقديم وحدة navigationevent-compose جديدة لتوفير ميزات Jetpack Compose في مكتبة navigationevent. (980d78)
  • NavigationEvent أضافت أداة Compose LocalNavigationEventDispatcherOwner تركيبة محلية جديدة. تعرض هذه السمة قيمة تقبل القيم الخالية لتحديد ما إذا كانت متوفّرة في التركيبة الحالية بشكل أفضل. سيؤدي الآن طلب NavigationEventHandler إلى ظهور خطأ في حال عدم العثور على المالك الأساسي. (62ffda)
  • NavigationEvent أضافت Compose عنصر NavigationEventHandler Composable جديدًا للتعامل مع أحداث (إيماءة الرجوع التوقّعية). يوفّر هذا النوع Flow من عناصر NavigationEvent التي يجب جمعها في دالة lambda المعلقة التي تقدّمها c42ba6 :
NavigationEventHandler { progress: Flow<NavigationEvent> ->
  // This block is executed when the back gesture begins.
  try {
    progress.collect { backEvent ->
      // Handle gesture progress updates here.
    }
    // This block is executed if the gesture completes successfully.
  } catch (e: CancellationException) {
    // This block is executed if the gesture is cancelled
    throw e
  } finally {
    // This block is executed either the gesture is completed or cancelled
  }
}

تغييرات واجهة برمجة التطبيقات

  • يمكن الآن تسجيل كل NavigationEventCallback باستخدام NavigationEventDispatcher واحد فقط في كل مرة، وإضافته إلى عدة برامج إرسال يؤدي إلى ظهور IllegalStateException. يُرجى العِلم أنّ هذا السلوك يختلف عن OnBackPressedDispatcher، الذي يسمح باستخدام عدة مرسِلين. (e82c19)
  • تم تحويل isPassThrough إلى val لمنع التغيير أثناء التنقّل، ما قد يؤدي إلى إيقاف عملية إرسال NavigationEvent. (I0b287)

الإصدار 1.0.0-alpha02

‫4 يونيو 2025

تم طرح androidx.navigationevent:navigationevent-*:1.0.0-alpha02. يتضمّن الإصدار 1.0.0-alpha02 هذه التعديلات.

تغييرات واجهة برمجة التطبيقات

  • استبدِل الدالة الإنشائية الثانوية لـ NavigationEventDispatcher بالوسيطات التلقائية. (I716a0)
  • إزالة الموقع ذي الأولوية من NavigationEventCallback يجب نقل الأولوية إلى NavigationEventDispatcher.addCallback() بدلاً من ذلك. (I13cae)

إصلاح الأخطاء

  • تم إصلاح ConcurrentModificationException الذي كان يمكن أن يحدث عند استدعاء NavigationEventCallback.remove() بسبب تعديل قائمة العناصر القابلة للإغلاق الداخلية في الوقت نفسه. (b/420919815)

الإصدار 1.0.0-alpha01

‫20 مايو 2025

تم طرح androidx.navigationevent:navigationevent-*:1.0.0-alpha01. يتضمّن الإصدار 1.0.0-alpha01 هذه التعديلات.

الميزات الجديدة

  • توفر مكتبة androidx.navigationevent واجهة برمجة تطبيقات KMP أولاً للتعامل مع الرجوع إلى الخلف في النظام بالإضافة إلى ميزة الرجوع التوقّعي. يعمل NavigationEventDispatcher كواجهات برمجة تطبيقات شائعة لتسجيل مثيل واحد أو أكثر من NavigationEventCallback لتلقّي أحداث الرجوع إلى الخلف في النظام.
  • تقع هذه الطبقة أسفل واجهات برمجة التطبيقات التي تم إصدارها سابقًا في androidx.activity، وتهدف إلى أن تكون بديلاً أقلّ تحكّمًا في طريقة استخدام واجهات برمجة التطبيقات الخاصة بالأنشطة في المكوّنات ذات المستوى الأعلى أو استخدام واجهات برمجة التطبيقات OnBackInvokedDispatcher لإطار عمل Android مباشرةً. تمت إعادة كتابة واجهات برمجة التطبيقات androidx.activity استنادًا إلى واجهات برمجة التطبيقات Navigation Event كجزء من الإصدار 1.12.0-alpha01 من "مكوّن التنقّل".