navigationevent

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

تعريف التبعيات

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

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

Groovy

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

Kotlin

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

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

الملاحظات

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

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

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

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

الإصدار 1.0

الإصدار 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 أضافت أداة 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 من "مكوّن التنقّل".