navigationevent

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

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

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

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

Groovy

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

Kotlin

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

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

الملاحظات

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

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

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

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

الإصدار 1.0

الإصدار 1.0.0

‫19 نوفمبر 2025

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

الميزات الرئيسية في الإصدار 1.0.0:

أصبحت مكتبة Navigation Event مستقرة الآن. ‫Navigation Event هي مكتبة AndroidX للتعامل مع التفاعلات على مستوى النظام، مثل الرجوع إلى الخلف على مستوى النظام والرجوع التوقّعي في Android (وغيره من الأنظمة الأساسية).

  • للتعامل مع NavigationEvent، يمكنك تنفيذ NavigationEventHandler خاص بك يتجاوز الدوال المطلوبة. بعد ذلك، عليك إضافة المعالج إلى NavigationEventDispatcher. بدءًا من إصدار النشاط 1.12.0، تنفّذ ComponentActivity واجهة NavigationEventDispatcherOwner الجديدة التي توفّر أداة إرسال جاهزة للاستخدام :

    // The NavigationEventInfo provides information about a navigation state
object CurrentInfo : NavigationEventInfo()

// you can retrieve this from any component that is a NavigationEventDispatcherOwner
// or you can instantiate your own custom dispatcher
val dispatcher = myActivity.navigationEventDispatcher

val myHandler = object : NavigationEventHandler<NavigationEventInfo>(
            initialInfo = CurrentInfo,
            isBackEnabled = true
        ) {
            override fun onBackStarted(event: NavigationEvent) {
                // Prepare for the back event
            }

            override fun onBackProgressed(event: NavigationEvent) {
                // Use event.progress for predictive animations
            }

            // This is the required method for final event handling
            override fun onBackCompleted() {
                // Complete the back event
            }

            override fun onBackCancelled() {
                // Cancel the back event
            }
        }

dispatcher.addHandler(myHandler)

  • يوفّر الوحدة navigationevent:navigationevent-compose دالة إنشاء ملائمة NavigationBackHandler تربط المعالج تلقائيًا بأقرب LocalNavigationEventDispatcherOwner في NavigationEventDispatcher وتسمح للمطوّرين بتوفير السلوك المطلوب كمعلَمات:

    object CurrentInfo : NavigationEventInfo()
object PreviousInfo : NavigationEventInfo()

val navEventState = rememberNavigationEventState(
  currentInfo = CurrentInfo,
  backInfo = PreviousInfo
)

// Inside composition
NavigationBackHandler(
    State = navEventState,
    isBackEnabled = true,
    // optional
    onBackCancelled = { // Cancel the back event },
    // required
    onBackCompleted = { // Complete the back event } ,
)

يؤدي استخدام هذا النمط في Compose إلى تسهيل عملية نقل NavigationEventState والسماح بمراقبتها من خلال عناصر Composable مختلفة (أي في حالة Navigation3، حيث يمكنك نقل الحالة خارج NavDisplay).

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

    // Non-Compose
val parentDispatcher = NavigationEventDispatcher()
val childDispatcher = NavigationEventDispatcher(parent = parentDispatcher)

// Compose
val composeChildDispatcher = rememberNavigationEventDispatcher(
    // This defaults to `LocalNavigationEventDispatcherOwner.current`
    // Must explicitly provide null to have an unparented dispatcher created here
    parent = NavigationEventDispatch() 
)

  • تتيح المكتبة أيضًا تقديم الإشارات مباشرةً إلى NavigationEventDispatcher من خلال NavigationEventInput. تعمل NavigationEventInputs كجانب "الإدخال" في نظام التنقّل، حيث تحوّل الأحداث الخاصة بالنظام الأساسي (مثل إيماءات الرجوع في النظام أو النقرات على الأزرار) إلى أحداث موحّدة يمكن إرسالها إلى NavigationEventDispatcher. يوفّر وحدة navigationevent:navigationevent حاليًا NavigationEventInputَين: DirectNavigationEventInput أكثر عمومية للسماح بإرسال أي حدث، وOnBackInvokedInput خاص بنظام التشغيل Android يسمح NavigationEventDispatcher بتوفير إمكانية الرجوع إلى الخلف في النظام وإيماءة الرجوع التوقّعية. إذا كنت تستخدم أداة إرسال خاصة بك (بدلاً من الأداة التي توفّرها ComponentActivity)، عليك إضافة الإدخال يدويًا باتّباع الخطوات التالية:

    val dispatcher = NavigationEventDispatcher()

dispatcher.addInput(DirectNavigationEventInput())
dispatcher.addInput(OnBackInvokedDefaultInput(invoker))

الإصدار 1.0.0-rc01

‫5 نوفمبر 2025

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

الإصدار 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 الآن على الإصدار 1.9.0-beta03 من Compose Runtime الذي يتيح للعنصر 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 أضافت أداة "إنشاء الموسيقى" مقطوعة موسيقية محلية جديدة 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، وتهدف إلى أن تكون بديلاً أقلّ تحكّمًا في طريقة الاستخدام لواجهات برمجة التطبيقات الخاصة بـ Activity في المكوّنات ذات المستوى الأعلى أو استخدام واجهات برمجة التطبيقات OnBackInvokedDispatcher لإطار عمل Android مباشرةً. تمت إعادة كتابة واجهات برمجة التطبيقات androidx.activity استنادًا إلى واجهات برمجة التطبيقات Navigation Event كجزء من الإصدار 1.12.0-alpha01 من "مكوّن الأنشطة".