رویداد ناوبری

کتابخانه رویداد ناوبری یک KMP-first API برای کنترل سیستم و همچنین پیش‌بینی بازگشت ارائه می‌کند.
آخرین به روز رسانی انتشار پایدار کاندید را آزاد کنید نسخه بتا انتشار آلفا
8 اکتبر 2025 - - 1.0.0-beta01 -

اعلام وابستگی ها

برای افزودن یک وابستگی به navigationevent، باید مخزن Google Maven را به پروژه خود اضافه کنید. برای اطلاعات بیشتر، مخزن Maven Google را بخوانید.

وابستگی‌های مصنوعات مورد نیاز خود را در فایل build.gradle برای برنامه یا ماژول خود اضافه کنید:

شیار 

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

کاتلین 

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

برای اطلاعات بیشتر درباره وابستگی‌ها، به افزودن وابستگی‌های ساخت نگاه کنید.

بازخورد

بازخورد شما به بهتر شدن Jetpack کمک می کند. اگر مسائل جدیدی کشف کردید یا ایده هایی برای بهبود این کتابخانه دارید، به ما اطلاع دهید. لطفاً قبل از ایجاد کتابخانه جدید، به مسائل موجود در این کتابخانه نگاهی بیندازید. با کلیک کردن روی دکمه ستاره می توانید رای خود را به یک موضوع موجود اضافه کنید.

یک شماره جدید ایجاد کنید

برای اطلاعات بیشتر به مستندات ردیاب مشکل مراجعه کنید.

هیچ یادداشت انتشار برای این مصنوع وجود ندارد.

نسخه 1.0

نسخه 1.0.0-beta01

08 اکتبر 2025

androidx.navigationevent:navigationevent-*:1.0.0-beta01 منتشر شد. نسخه 1.0.0-beta01 حاوی این تعهدات است.

تغییرات API

  • حاشیه نویسی 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 حاوی این تعهدات است.

تغییرات API

  • به جای نمونه سازی Idle() مستقیماً از شی singleton NavigationEventTransitionState.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 اکنون به جای یک interface یک abstract class است. همه پیاده سازی های سفارشی را برای ارث بردن از کلاس به روز کنید (به عنوان مثال، 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 جهانی جدید را معرفی کنید. این جریان غیرعمومی به ناظران اجازه می‌دهد که فقط در حالت حرکت فیزیکی (بیکار/در حال پیشرفت)، جدا از تاریخچه مشترک شوند. ( I171fa , b/444734264 )
  • کلاس NavigationEventHistoryState را معرفی کنید. این به عنوان API اصلی برای مشاهده تاریخچه اطلاعات ناوبری، جدا از وضعیت حرکت عمل می کند. ( I81ca5 , b/444734264 )
  • NavigationEvent اکنون به‌عنوان @Immutable علامت‌گذاری شده است و به Compose Compiler اجازه می‌دهد تا ترکیب‌های مجدد را بهینه کند. ( If78c7 , b/444734264 )
  • APIهای کنترل کننده 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 sealed را معرفی کنید. این به عنوان API اصلی برای مشاهده وضعیت حرکت، جدا از تاریخچه پیمایش عمل می کند. ( ID4beb , b/444734264 )
  • currentInfo ، backInfo و forwardInfo به‌عنوان ویژگی‌های عمومی و فقط خواندنی در NavigationEventHandler نمایش دهید. ( Ia7636 , b/444734264 )
  • پیاده سازی های NavigationEventHandler اکنون باید یک initialInfo: T اولیه را به سازنده پایه ارائه دهند. ( Idcfea , b/444734264 )
  • OnBackInvokedInput با OnBackInvokedOverlayInput یا OnBackInvokedDefaultInput جایگزین کنید. ( I5323f , b/428948766 )
  • NavigationEventState به‌عنوان @Immutable علامت‌گذاری کنید. این کار با اطمینان از اینکه Composables با مشاهده این حالت می تواند به درستی از ترکیب مجدد رد شود، عملکرد Compose را بهبود می بخشد. ( I399c8 )
  • تغییر نام NavigationEventInfo.NotProvided به NavigationEventInfo.None; به روز رسانی مراجع بدون تغییر رفتار ( I5e2d4 )
  • NavigationEventInfo اکنون به‌عنوان @Immutable علامت‌گذاری شده است و به Compose Compiler اجازه می‌دهد تا ترکیب‌های مجدد را بهینه کند. ( I7c112 )
  • ارگونومی جاوا را با رابط سرگرم‌کننده برای تکمیل مجدد بهبود دهید. ( I8a860 )
  • تغییر نام onHasEnabledHandlerChanged به onHasEnabledHandlersChanged . این روشن می‌کند که تماس برگشتی وضعیت فعالسازی جمعی همه کنترل‌کننده‌ها را گزارش می‌کند، نه فقط یک. ( I1af61 , b/443711297 )
  • حذف hasEnabledHandler() از NavigationEventDispatcher; به جای آن از NavigationEventInput.onHasEnabledHandlersChanged استفاده کنید. ( IDef72 , b/443711297 )
  • پاسخ تماس onInfoChanged به NavigationEventInput اضافه کنید تا شنوندگان را از تغییرات در تاریخچه پیمایش مطلع کنید. این زمینه کامل پشته های جاری، عقب و جلو را فراهم می کند و ورودی ها را قادر می سازد به اطلاعات متنی واکنش نشان دهند. ( I69a8b , b/443282983 )
  • swipeEdge NavigationEvent را به @IntDef تبدیل کنید ( Icee54 , b/443950342 )
  • یک پارامتر priority را به NavigationEventDispatcher.addInput اضافه کنید تا یک توزیع کننده را به یک اولویت اختصاص دهید. رویدادهایی مانند onHasEnabledCallbacksChanged اکنون تنها زمانی فعال می‌شوند که پاسخ‌های تماس در آن اولویت تغییر کنند. ( I3e488 , b/443711297 )
  • برای وضوح، نام پارامتر NavigationEventDispatcher را از parentDispatcher به والد تغییر دهید. ( Id4f1f , b/443801782 )
  • حذف NavigationEventPriority به نفع @IntDef برای کاربران جاوا ( I10a9f ، b/440514265 )
  • اجرای قرارداد ناوبری. اگر NavigationEventHandler شما isBackEnabled یا isForwardEnabled روی true تنظیم می کند، اکنون باید به ترتیب onBackCompleted یا onForwardCompleted لغو کنید. پیاده سازی های پیش فرض اکنون یک استثنا برای جلوگیری از خرابی های بی صدا ایجاد می کنند. ( I17c62 )
  • هنگام اضافه کردن کنترل کننده رویدادهای پیمایش، مقادیر اولویت معتبر را اعمال کنید. تماس با addHandler با اولویت پشتیبانی‌نشده، اکنون یک IllegalArgumentException ایجاد می‌کند و بازخورد فوری برای استفاده نادرست در همه پلتفرم‌های هدف ارائه می‌کند. ( I3c474 )

رفع اشکال

  • addHandler را idempotent کنید. ثبت نام های تکراری را نادیده بگیرید ( 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 حاوی این تعهدات است.

ویژگی های جدید

  • یک API NavigationEventHandler مبتنی بر lambda را معرفی کنید که جایگزین کنترل کننده مبتنی بر Flow شود. به جای جمع‌آوری جریان‌ها، کاهش صفحه دیگ بخار و اجتناب از مشکلات لغو، با ژست‌های برگشت و جلو با تماس‌های ساده برخورد کنید. NavigationBackHandler و NavigationForwardHandler به عنوان APIهای راحتی هدفمند ارائه دهید. حذف NavigationEventHandler مبتنی بر جریان. به تماس های جدید مهاجرت کنید. ( I23bac , b/436248277 )
  • به شنوندگان غیرفعال اجازه دهید از طریق اطلاعات پشتی ترکیبی به پشته ناوبری کامل دسترسی داشته باشند. رابط‌های کاربری را فعال کنید تا پیش‌نمایش‌ها و تاریخچه پیمایش تودرتو را به‌جای محدود شدن به بالاترین پاسخ به تماس، ارائه دهند. ( I7a510 , b/436248277 )
  • برای روشن کردن وضعیت ناوبری و پشتیبانی از ناوبری رو به جلو با کنترل‌کننده‌های تودرتو، یک مدل صریح برگشت/جریان/جلو معرفی کنید. ( Ib86da , b/420443609 )
  • روش‌های onForward* را اضافه کنید و به NavigationEventCallback isForwardEnabled . ( Ic100f , b/436248290 )
  • پشتیبانی ناوبری رو به جلو را به NavigationEventInput اضافه کنید. ( I5734b )

تغییرات API

  • تست رویدادهای پیمایش رو به جلو را با TestNavigationEventCallback فعال کنید. از قلاب‌های isForwardEnabled و onForward* استفاده کنید. ( I21fb5 , b/420443609 )
  • در NavEvent نام تماس‌های onEvent* را به onBack* تغییر دهید. ( I228b3 , b/436248290 )
  • SwipeEdge به یک کلاس درون خطی تبدیل کنید. ( ID5e01 )
  • کتابخانه navigationevent را با جاوا سازگار کنید. همه APIهای عمومی اکنون به طور کامل از طریق کد جاوا در دسترس هستند و امکان ادغام یکپارچه با پروژه های مختلط زبان یا فقط جاوا را فراهم می کنند. ( Ibc944 , I5465f , I9fb1e , b/440532890 b/443040294 )
  • با تغییر نام NavigationEventCallback به NavigationEventHandler ، نقش‌های API را روشن کنید. این تغییر هدف کلاس از مدیریت حرکات ناوبری چند مرحله ای را بهتر منعکس می کند. روش addCallback مربوطه اکنون addHandler است. ( I2492a , b/443040331 )

رفع اشکال

  • از اجرای برگشت برگشتی در مسیریابی رو به جلو جلوگیری کنید. ( I74814 , b/436248290 )
  • برای ناوبری رو به جلو پیش بینی پشتیبانی اضافه کنید. APIهای NavigationEvent اکنون هر دو ژست‌های عقب و جلو را کنترل می‌کنند و انیمیشن‌های ثابتی را برای هر دو جهت ناوبری فعال می‌کنند. ( IDc98c , b/436248290 )
  • هنگامی که یک NavigationEventDispatcherOwner فرزند حذف می شود، از خرابی IllegalStateException در حین ترکیب مجدد جلوگیری کنید. ( Iff50c , b/412629020 )
  • شنوندگان غیرفعال اکنون می‌توانند از طریق اطلاعات پشتیبان ترکیبی به پشته ناوبری کامل دسترسی پیدا کنند، و به رابط‌های کاربری امکان می‌دهد به جای محدود شدن به بالاترین تماس، پیش‌نمایش و تاریخچه پیمایش تودرتو را ارائه دهند. ( I7a510 , b/436248277 )

نسخه 1.0.0-alpha07

27 آگوست 2025

androidx.navigationevent:navigationevent-*:1.0.0-alpha07 منتشر شد. نسخه 1.0.0-alpha07 حاوی این commit ها است.

تغییرات API

  • 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 را می‌پذیرد، و آن را به API اصلی برای ارائه زمینه در برنامه‌های 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 ). این APIهای مبتنی بر StateFlow به هر UI اجازه می‌دهند پیشرفت ژست‌ها و داده‌های متنی را بدون رسیدگی مستقیم به رویداد مشاهده کنند.

مثال:

  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

  • برای ایجاد، پیوند دادن و دفع نمونه های NavigationEventDispatcher به صورت سلسله مراتبی NavigationEventDispatcherOwner اضافه کنید. کنترل پویا وضعیت فعال توزیع کننده و پاکسازی خودکار را فعال کنید.

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

تغییرات API

  • پارامتر isPassthrough از NavigationEventCallback حذف شده است. ( I99028 , b/424470518 )
  • سازندگان NavigationEventState اکنون داخلی هستند. برای آزمایش، وضعیت (پیش‌فرض به Idle ) را از طریق DirectNavigationEventInputHandler به‌روزرسانی کنید. برای تنظیم وضعیت روی InProgress ، handleOnStarted یا handleOnProgressed و برای برگرداندن آن به Idle handleOnCompleted یا handleOnCancelled فراخوانی کنید. برای به روز رسانی NavigationEventInfo ، از NavigationEventCallback.setInfo استفاده کنید. ( I93dca , b/424470518 )
  • پارامترهای پیش‌فرض را به NavigationEvent اضافه کرد تا امکان نمونه‌سازی آسان‌تر و ساده‌سازی آزمایش را فراهم کند که باید به جای TestNavigationEvent استفاده شود. ( I5dc49 , I232f4 )
  • یک TestNavigationEventCallback برای آزمایش رویدادهای ناوبری با وضعیت‌های خاص فعلی/قبلی اضافه شد. ( Idd22e , b/424470518 )
  • NavigationEventInputHandler به یک کلاس انتزاعی تبدیل شده است تا جایگزین AbstractNavigationEventInputHandler قبلی با پیاده سازی در DirectNavigationEventInputHandler شود ( Iadde5 , Ifed40 I3897c , 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 )

به روز رسانی Docs

  • KDocs برای NavigationEvent گسترش یافت تا نقش خود را به عنوان یک پوشش رویداد یکپارچه و رفتار ویژگی جزئیات در انواع مختلف پیمایش (ژست‌ها، کلیک‌ها) روشن کند. ( I91e8d )
  • اسناد به‌روزرسانی شده برای مدیریت برگشت سیستم، APIها را بنویسید ( 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 اکنون می تواند توزیع کننده های والد و فرزند داشته باشد که یک ساختار درختی سلسله مراتبی را تشکیل می دهد. این امر به رویدادهای ناوبری امکان می دهد تا با منعکس کردن سلسله مراتب ساختاری UI از طریق توزیع کننده های زنجیره ای، در اجزای پیچیده Compose UI به طور انعطاف پذیرتری منتشر شوند و مدیریت شوند. ( 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 UI در aosp/3692572 مدیریت می کند. با این حال، این تغییر به نسخه فعلی وارد نشد و برای نسخه بعدی برنامه ریزی شده است.

کتابخانه تست ناوبری

  • ماژول navigationevent-testing را برای ارائه ابزارهای آزمایشی اختصاصی برای کتابخانه navigationevent اضافه کنید. ( 0e50b6 )
  • کلاس ابزار جعلی TestNavigationEventCallback برای آزمایش اضافه کنید. تماس‌های روش برگشت به تماس را ضبط می‌کند و موارد دریافتی NavigationEvent را برای پشتیبانی از تأیید ذخیره می‌کند. ( 4a0246 )
  • برای ایجاد نمونه‌های NavigationEvent با مقادیر پیش‌فرض، تابع ابزار جعلی TestNavigationEvent را اضافه کنید و آزمایش‌های واحد را برای پردازش رویدادهای ناوبری ساده کنید. ( 3b63f5 )
  • کلاس ابزار جعلی TestNavigationEventDispatcherOwner برای آزمایش اضافه کنید. برای پشتیبانی از تأیید تعامل در آزمایش‌ها، تعداد رویدادهای بازگشتی و تغییر حالت فعال را دنبال می‌کند. ( c8753e )

تغییرات API

  • NavigationEventInputHandler از androidMain به commonMain منتقل کنید تا در کد رایج KMP در دسترس قرار گیرد. روش‌های public send* جدید را برای ارسال رویدادها اضافه کنید. تغییر توابع ارسال در NavigationEventDispatcher از public به internal . کاربران اکنون باید از NavigationEventInputHandler برای ارسال رویدادها استفاده کنند. ( Ia7114 )
  • تغییر نام NavigationInputHandler به OnBackInvokedInputHandler . ( I63405 )

رفع اشکال

  • Refactor NavigationEventDispatcher برای کاهش سربار با اجتناب از تخصیص لیست میانی و بهبود عملکرد ارسال برگشت به تماس. ( I82702 , I1a9d9 )
  • حاشیه‌نویسی‌های @FloatRange را به فیلدهای touchX ، touchY و progress در NavigationEvent اضافه کنید تا محدوده‌های ارزش معتبر را در زمان کامپایل اعمال کنید و ایمنی API را بهبود بخشید. ( 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 برای اطمینان از تولید صحیح خرد. هیچ تاثیری بر APIهای عمومی یا رفتار ندارد. ( 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 جدید اضافه کرده است. برای تعیین بهتر اینکه آیا در ترکیب فعلی موجود است یا خیر، یک مقدار nullable برمی گرداند. اکنون اگر مالک اصلی پیدا نشود، NavigationEventHandler خطایی ایجاد می کند. ( 62ffda )
  • NavigationEvent Compose یک NavigationEventHandler Composable جدید اضافه کرده است تا رویدادها را مدیریت کند. این یک Flow از اشیاء NavigationEvent ارائه می دهد که باید در لامبدای معلقی که ارائه می کنید 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
  }
}

تغییرات API

  • هر 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 حاوی این تعهدات است.

تغییرات API

  • سازنده ثانویه 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-first API برای کنترل سیستم و همچنین Predictive Back ارائه می‌کند. NavigationEventDispatcher به عنوان یک API رایج برای ثبت یک یا چند نمونه NavigationEventCallback برای دریافت رویدادهای برگشت سیستم عمل می کند.
  • این لایه در زیر APIهای منتشر شده قبلی در androidx.activity قرار دارد و هدف آن این است که جایگزینی با نظر کمتر برای استفاده از APIهای Activity در اجزای سطح بالاتر یا استفاده مستقیم از چارچوب Android OnBackInvokedDispatcher APIها باشد. APIهای androidx.activity در بالای APIهای رویداد ناوبری به عنوان بخشی از Activity 1.12.0-alpha01 بازنویسی شده‌اند.