navigationevent

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

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

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

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

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

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

الملاحظات

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

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

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

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

الإصدار 1.0

الإصدار 1.0.0-alpha07

‫27 أغسطس 2025

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

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

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

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

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

الإصدار 1.0.0-alpha06

‫13 أغسطس 2025

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

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

Passive Listeners API

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

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

1. توفير المعلومات: استخدِم NavigationEventInfo لنقل البيانات المخصّصة.
2. حالة الاستهلاك: استخدِم dispatcher.state (NavigationEventState) لمراقبة تقدّم الإيماءة وسياقها.

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

مثال:

  data class MyScreenInfo(val screenName: String) : NavigationEventInfo

  NavigationEventHandler(
      enabled = true,
      currentInfo = MyScreenInfo("Details Screen"),
      previousInfo = MyScreenInfo("Home Screen")
  ) { /* Handle back completion */ }

• تعرض السمة NavigationEventDispatcher الآن السمتَين dispatcher.state وdispatcher.getState<T>() (If7fae وIa90ca وb/424470518). تتيح واجهات برمجة التطبيقات المستندة إلى StateFlow لأي واجهة مستخدم مراقبة تقدّم الإيماءة والبيانات السياقية بدون معالجة الحدث مباشرةً.

مثال:

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

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

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

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

  val progress = state.progress
  

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

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

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

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

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

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

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

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

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

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

الإصدار 1.0.0-alpha05

‫30 يوليو 2025

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

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

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

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

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

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

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

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

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

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

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

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

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

  val callback2 = TestNavigationEventCallback()

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

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

Navigation Testing Library

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

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

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

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

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

الإصدار 1.0.0-alpha04

‫2 يوليو 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 من "مكوّن التنقّل".