navigationevent

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

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

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

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

Groovy

dependencies {
    implementation "androidx.navigationevent:navigationevent:1.1.0-rc01"
}

Kotlin

dependencies {
    implementation("androidx.navigationevent:navigationevent:1.1.0-rc01")
}

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

الملاحظات

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

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

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

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

الإصدار 1.1

الإصدار ‎1.1.0-rc01

‫8 أبريل 2026

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

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

  • تم تعديل Compose compileSdk إلى الإصدار 37 من واجهة برمجة التطبيقات. وهذا يعني أنّه يجب توفُّر الإصدار 9.2.0 أو إصدار أحدث من "مكوّن Android الإضافي" عند استخدام Compose. (Id45cd، b/413674743)

الإصدار 1.1.0-beta01

‫27 مارس 2026

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

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

  • أضِف OnForwardCompletedFallback إلى NavigationEventDispatcher، ما يتيح سلوكًا تلقائيًا للنظام لأحداث التنقّل إلى الأمام التي لم تتم معالجتها. (Iac620، b/489138116)

الإصدار ‎1.1.0-alpha01

‫25 فبراير 2026

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

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

  • إتاحة جميع أهداف Kotlin Multiplatform (KMP) في NavigationEvent-Compose فصل عملية تحديد المالك عن LocalView للسماح لمضيفي المنصات بتوفير قيمة تلقائية LocalNavigationEventDispatcherOwner مع الحفاظ على LocalView كخيار احتياطي آمن على Android (Iae980، b/434940570، Iccf58)

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

  • أضِف دالّتَي الإضافة NavigationEvent.toBackEvent() وBackEvent.toNavigationEvent() للتحويل بين BackEvent وNavigationEvent في Android. (Ie3b71، b/477001292)

الإصدار 1.0

الإصدار 1.0.2

‫28 يناير 2026

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

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

  • إصلاح تعطُّل عند استخدام NavigationEventHandler في "إصدارات استوديو Android التجريبية" يرصد المعالج الآن وضع الفحص ولا ينفّذ أي إجراء، ما يسمح بعرض "المعاينة" بدون توفير أداة إرسال. (I370f2، b/454313986).

الإصدار 1.0.1

‫3 ديسمبر 2025

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

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

  • إصلاح ConcurrentModificationException عند التخلص من عنصر ثانوي NavigationEventDispatcher، مثل العناصر التي تم إنشاؤها باستخدام rememberNavigationEventDispatcherOwner() (ec68a9، b/454363524)

الإصدار 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 تربط المعالج تلقائيًا بـ NavigationEventDispatcher الأقرب إلى LocalNavigationEventDispatcherOwner وتسمح للمطوّرين بتوفير السلوك المطلوب كمعلَمات:

    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 قابلاً للإنشاء لإنشاء مثيلات 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 أضافت أداة 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 من "مكوّن التنقّل".