navigationevent

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

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

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

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

Groovy

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

Kotlin

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

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

الملاحظات

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

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

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

الإصدار 1.2

الإصدار 1.2.0-rc01

‫23 سبتمبر 2026

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

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

  • تم تعديل الاعتمادية androidx.lifecycle:lifecycle-runtime إلى الإصدار 2.10.0. هذا الإصدار مطلوب لتشغيل عمليات التحقّق من أخطاء lint المجمَّعة في وقت التشغيل لدورة الحياة مع الإصدار 9.5.0-alpha04 أو إصدار أحدث من "مكوّن Android الإضافي لبرنامج Gradle". (I99bfd، b/556807521)

الإصدار ‎1.2.0-alpha04

‫12 أغسطس 2026

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

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

  • تمت إضافة واجهتَي برمجة التطبيقات الجديدتَين hasEnabledBackHandlers وhasEnabledForwardHandlers إلى NavigationEventInput للسماح بتتبُّع إمكانات تحديد الاتجاه بشكل مستقل. (I772bf، b/123456789)

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

  • إضافة عملية بحث احتياطية عن مسار السياق لحلّ المشكلة LocalNavigationEventDispatcherOwner عند عدم توفّر مالكي شجرة العرض. (I51e30، b/530641649)

الإصدار ‎1.2.0-alpha03

‫29 يوليو 2026

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

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

  • أضِف title وurl إلى NavigationEventInfo للسماح بتخصيص عنوان الوجهة وعنوان URL الخاص بالموقع الجغرافي. (Ie5619)
  • أضِف مصنع NavigationEventDispatcherOwner في navigationevent. (I740d3)
  • أضِف التعليق التوضيحي ExperimentalNavigationEventApi للسماح بالموافقة الصريحة على استخدام واجهات برمجة التطبيقات الجديدة وغير المستقرة. (Ia5d25)

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

  • إتاحة BrowserInput للجميع في استهدافات wasmJs كواجهة برمجة تطبيقات تجريبية (Icc2a8)

الإصدار 1.2.0-alpha02

‫15 يوليو 2026

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

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

  • أضِف السمة hasEnabledHandlers إلى NavigationEventInput للسماح للمطوّرين بالبحث عن حالة المعالج الحالية مباشرةً بدون الاعتماد على عمليات رد الاتصال. (I8ecec)

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

  • إصلاح عملية نشر البيانات الاحتياطية في NavigationEventDispatcher (I015f8، b/531988076)

الإصدار 1.2.0-alpha01

‫01 يوليو 2026

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

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

  • لدى "androidx.benchmark" الآن minSdk يبلغ 24. (Ic2a85)
  • أضِف onForwardCompletedFallback إلى TestNavigationEventDispatcherOwner لتفعيل تتبُّع أحداث التنقّل للأمام غير المعالَجة واختبارها. (I6bbd7)
  • أضِف navigationEventInput إلى TestNavigationEventDispatcherOwner لتسهيل محاكاة أحداث التنقّل في الاختبارات. (I3ef48)

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

  • تنظيف معلومات واجهة برمجة التطبيقات (Ia8066)
  • تجاهل أحداث التنقّل التي يتم إرسالها إلى أجهزة إدخال غير متصلة في السابق، كان إرسال الأحداث إلى إدخال تمت إزالته يؤدي إلى ظهور IllegalStateException. (I1a8bc، b/515890298)
  • منع تكرار الرموز مع الإصدارات القديمة من فرع JetBrains عند الترقية إلى الإصدار 1.11.0 من Compose Multiplatform (I4cc4d)

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

الإصدار 1.1

الإصدار 1.1.2

‫17 يونيو 2026

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

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

  • حدِّث حِزم Compose إلى الإصدار 1.11.2. (a5e9259)

الإصدار 1.1.1

‫6 مايو 2026

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

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

  • تمت إزالة NavigationEventHandler no-op عند تفعيل وضع الفحص لتفعيل ميزة "الرجوع التوقّعي" في الإصدارات التجريبية من "استوديو Android".

الإصدار 1.1.0

‫22 أبريل 2026

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

الإصدار 1.1.0-rc01

‫8 أبريل 2026

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

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

  • تم تعديل compileSdk في Compose إلى الإصدار 37 من واجهة برمجة التطبيقات. وهذا يعني أنّه يجب استخدام الإصدار 9.2.0 من "المكوّن الإضافي لنظام Gradle المتوافق مع 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 تربط المعالج تلقائيًا بأقرب 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 (والسمات المتغيرة) تحميلًا جديدًا يقبل السمة NavigationEventState التي تم نقلها. يتم الاحتفاظ بالتحميلات الزائدة البسيطة (التي تتضمّن 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 للردّ إلى NavigationEventInput لإعلام المستمعين بالتغييرات في سجلّ التنقّل. يوفّر ذلك السياق الكامل لمجموعات التراجع والتقدّم الحالية، ما يتيح لـ Inputs التفاعل مع المعلومات السياقية. (I69a8b، b/443282983)
  • تحويل swipeEdge من NavigationEvent إلى @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

  • أضِف وحدة 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 يوليو 2025

تم طرح 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 من "النشاط".