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

کتابخانه رویداد ناوبری (Navigation Event) یک API مبتنی بر KMP برای مدیریت بازگشت سیستم (system back) و همچنین بازگشت پیش‌بینی‌کننده (Predictive Back) ارائه می‌دهد.
آخرین به‌روزرسانی انتشار پایدار کاندیدای انتشار انتشار بتا انتشار آلفا
۵ نوامبر ۲۰۲۵ - ۱.۰.۰-rc01 - -

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

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

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

شیار 

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

کاتلین 

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

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

بازخورد

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

ایجاد یک مسئله جدید

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

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

نسخه ۱.۰

نسخه ۱.۰.۰-rc01

۵ نوامبر ۲۰۲۵

androidx.navigationevent:navigationevent-*:1.0.0-rc01 منتشر شد. نسخه 1.0.0-rc01 شامل این کامیت‌ها است.

نسخه ۱.۰.۰-بتا۰۱

۸ اکتبر ۲۰۲۵

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 را مستقیماً برمی‌گرداند. برای ارائه این مالک به یک sub-composition، از CompositionLocalProvider استفاده کنید. ( I874b2 , b/444446629 )

نسخه ۱.۰.۰-آلفا۰۹

۲۴ سپتامبر ۲۰۲۵

androidx.navigationevent:navigationevent-*:1.0.0-alpha09 منتشر شد. نسخه 1.0.0-alpha09 شامل این کامیت‌ها است.

تغییرات API

  • به جای نمونه‌سازی Idle() مستقیماً از شیء تک‌لایه NavigationEventTransitionState.Idle استفاده کنید. ( Ic7d9e ، b/444734264 )
  • سازنده‌های کمکی را داخلی کنید؛ نمونه‌ها را از طریق public NavigationEventDispatcher.history به جای ساخت مستقیم دریافت کنید. ( I3b7e0 , b/444734264 )
  • نیاز به ایجاد NavigationEventState از طریق rememberNavigationEventState ؛ سازنده اکنون داخلی است. ( Ie143c ، b/444734264 )
  • تابع onBackCompletedFallback جایگزین تابع fallbackOnBackPressed و پارامتر سازنده می‌شود. رفتار آن بدون تغییر باقی می‌ماند؛ فقط در رویدادهای back که تکمیل و مدیریت نشده‌اند، فراخوانی می‌شود. ( Idabe9 ، b/444734264 )
  • سازنده اصلی NavigationEventHistory(mergedHistory, currentIndex) اکنون internal است. مصرف‌کنندگان خارجی باید از سازنده‌های عمومی (یا سازنده خالی یا سازنده مبتنی بر پارتیشن) برای ایجاد نمونه‌ها استفاده کنند. ( I1c047 ، b/444734264 )
  • تابع View.setViewTreeNavigationEventDispatcherOwner طوری تنظیم کنید که مالک nullable ( 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 )
  • یک جریان StateFlow سراسری جدید به نام NavigationEventDispatcher.history معرفی کنید. این جریان غیر ژنریک به ناظران اجازه می‌دهد فقط در تغییرات پشته ناوبری مشترک شوند و در طول پیشرفت ژست‌ها پایدار می‌ماند. این معادل transitionState است. ( I1db10 , b/444734264 )
  • یک NavigationEventDispatcher.transitionState StateFlow سراسری جدید معرفی کنید. این جریان غیر ژنریک به ناظران اجازه می‌دهد فقط در حالت ژست فیزیکی (Idle/InProgress) مشترک شوند، جدا از تاریخچه. ( I171fa , b/444734264 )
  • کلاس NavigationEventHistoryState را معرفی کنید. این کلاس به عنوان API اصلی برای مشاهده تاریخچه اطلاعات ناوبری، جدا از وضعیت ژست‌ها، عمل خواهد کرد. ( I81ca5 ، b/444734264 )
  • NavigationEvent اکنون به عنوان @Immutable علامت‌گذاری شده است و به کامپایلر Compose اجازه می‌دهد تا ترکیب‌بندی‌های مجدد را بهینه کند. ( If78c7 , b/444734264 )
  • رابط‌های برنامه‌نویسی (API) مربوط به مدیریت‌کننده‌ی navigationevent-compose به‌روزرسانی شده‌اند. NavigationEventHandler و NavigationBackHandler (و انواع دیگر) اکنون از یک overload جدید پشتیبانی می‌کنند که یک NavigationEventState را که به صورت hoist شده است، می‌پذیرد. overloadهای ساده (با گرفتن currentInfo ) حفظ شده و اکنون از این مدل state جدید به صورت داخلی استفاده می‌کنند. ( Ic3251 ، b/444734264 )
  • نگهدارنده وضعیت جدید @Stable NavigationEventState<T> ‎ را به کتابخانه navigationevent-compose اضافه کنید. این شیء تاریخچه محلی را با وضعیت ژست محلی ترکیب می‌کند و پیوند اصلی بین rememberNavigationEventState و NavigationEventHandler خواهد بود. ( Ifb69f ، b/444734264 )
  • یک ویژگی عمومی و فقط خواندنی جدید به نام transitionState: TransitionState به NavigationEventHandler اضافه کنید. اکنون کنترل‌کننده‌ها حالت گذار خود را حفظ می‌کنند که سیستم‌های خارجی می‌توانند آن را مشاهده کنند. ( I9acd2 ، b/444734264 )
  • کلاس جدید TransitionState را معرفی کنید. این کلاس به عنوان 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 علامت‌گذاری کنید. این کار با اطمینان از اینکه Composableهایی که این حالت را مشاهده می‌کنند می‌توانند به درستی از ترکیب مجدد صرف نظر کنند، عملکرد Compose را بهبود می‌بخشد. ( I399c8 )
  • تغییر نام NavigationEventInfo.NotProvided به NavigationEventInfo.None; به‌روزرسانی ارجاع‌ها. بدون تغییر رفتار. ( I5e2d4 )
  • NavigationEventInfo اکنون به عنوان @Immutable علامت‌گذاری شده است و به کامپایلر Compose اجازه می‌دهد تا ترکیب‌بندی‌های مجدد را بهینه کند. ( I7c112 )
  • بهبود ارگونومی جاوا با رابط کاربری سرگرم‌کننده برای پشتیبانی از تکمیل کد به عقب ( I8a860 )
  • تغییر نام onHasEnabledHandlerChanged به onHasEnabledHandlersChanged . این روشن می‌کند که callback وضعیت فعال‌سازی جمعی همه handlerها را گزارش می‌دهد، نه فقط یکی را. ( 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 اضافه کنید تا یک dispatcher را به یک اولویت محدود کنید؛ رویدادهایی مانند onHasEnabledCallbacksChanged اکنون فقط زمانی اجرا می‌شوند که فراخوانی‌های با آن اولویت تغییر کنند. ( I3e488 ، b/443711297 )
  • برای وضوح بیشتر، نام پارامتر NavigationEventDispatcher از parentDispatcher به parent تغییر دهید. ( Id4f1f ، b/443801782 )
  • برای کاربران جاوا، NavigationEventPriority به نفع @IntDef حذف کنید ( 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 )

نسخه ۱.۰.۰-آلفا۰۸

۱۰ سپتامبر ۲۰۲۵

androidx.navigationevent:navigationevent-*:1.0.0-alpha08 منتشر شد. نسخه 1.0.0-alpha08 شامل این کامیت‌ها است.

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

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

تغییرات API

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

رفع اشکالات

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

نسخه ۱.۰.۰-آلفا۰۷

۲۷ آگوست ۲۰۲۵

androidx.navigationevent:navigationevent-*:1.0.0-alpha07 منتشر شد. نسخه 1.0.0-alpha07 شامل این کامیت‌ها است.

تغییرات API

  • حذف NavigationEventDispatcher.onHasEnabledCallbacksChanged ( I50e97 )
  • NavigationEventCallback.onEventCompleted() انتزاعی (abstract) کنید ( I36b38 ).
  • متدهای NavigationEventCallback#on* را به protected تغییر دهید. کد فراخوانی را به‌روزرسانی کنید تا آنها را بازنویسی کند. ( I6b691 )
  • تغییر نام توابع DirectNavigationEventInput . ( Iffb62 )
  • تغییر نام NavigationEventInput.onAttach به onAdded ( I2d0b8 )
  • تغییر نام NavigationEventInput.onDetach به onRemoved ( I2d0b8 )
  • نام NavigationEventInputHandler را به NavigationEventInput تغییر دهید. ( I676a4 )
  • @EmptySuper به NavigationEventInput.onHasEnabledCallbacksChanged اضافه کنید. ( اگر ۹۸۵۳ )
  • پیاده‌سازی 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 )

نسخه ۱.۰.۰-alpha06

۱۳ آگوست ۲۰۲۵

androidx.navigationevent:navigationevent-*:1.0.0-alpha06 منتشر شد. نسخه 1.0.0-alpha06 شامل این کامیت‌ها است.

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

API شنونده‌های غیرفعال

اکنون می‌توانید اطلاعات متنی سفارشی را از هر میزبان ناوبری ارسال کنید و به صورت غیرفعال به تغییرات حالت ژست از هر کجای رابط کاربری خود گوش دهید . این امر انیمیشن‌های آگاه از متن را برای پیش‌بینی بازگشت و سایر ناوبری‌های مبتنی بر ژست فعال می‌کند.

این ویژگی دو بخش دارد:

  1. ارائه اطلاعات - از NavigationEventInfo برای حمل داده‌های سفارشی استفاده کنید.
  2. مصرف وضعیت - از dispatcher.state ( NavigationEventState ) برای مشاهده پیشرفت ژست و زمینه استفاده کنید.
  • NavigationEventCallback اکنون متد setInfo(currentInfo, previousInfo) را برای تنظیم زمینه ژست در یک فراخوانی ( I1d5e7 ، b/424470518 ) ارائه می‌دهد.
  • NavigationEventHandler یک overload جدید اضافه می‌کند که 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 به هر رابط کاربری اجازه می‌دهند تا پیشرفت ژست‌ها و داده‌های زمینه‌ای را بدون مدیریت مستقیم رویداد مشاهده کند.

مثال:

  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 اضافه کنید. کنترل پویای وضعیت فعال‌شده‌ی dispatcher و پاکسازی خودکار را فعال کنید.

    @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 اکنون از NavigationInputHandler abstract جدید ( Ib45aa ) ارث بری می‌کند.
  • NavigationEventDispatcherOwner تغییر کرد تا به یک توزیع‌کننده‌ی والد نیاز داشته باشد، جایی که برای ایجاد یک توزیع‌کننده‌ی ریشه باید صریحاً null را ارسال کنید. ( Ia6f64 ، b/431534103 )

رفع اشکالات

  • با جلوگیری از کپی کردن مجموعه‌ها در NavigationEventDispatcher.dispose() . ( I4ab09 ) کارایی بهبود یافته است.
  • مشکلی که باعث می‌شد NavigationEventHandler به تغییرات در حالت فعال خود به درستی پاسخ ندهد، برطرف شد. ( Ia5268 ، I19bec ، I5be5c ، b/431534103 )

به‌روزرسانی‌های اسناد

  • KDocs برای NavigationEvent گسترش یافت تا نقش آن را به عنوان یک پوشش‌دهنده رویداد یکپارچه روشن کند و رفتار ویژگی را در انواع مختلف ناوبری (حرکات، کلیک‌ها) به تفصیل شرح دهد. ( I91e8d )
  • مستندات مربوط به مدیریت برگشتی سیستم، توسط رابط‌های برنامه‌نویسی Compose ( BackHandler ، PredictiveBackHandler ، NavigationEventHandler ) به‌روزرسانی شد تا رفتار مربوط به ترتیب فراخوانی فراخوانی‌ها ( I7ab94 ،) فراخوانی شود.

به‌روزرسانی وابستگی

  • NavigationEvent اکنون به Compose Runtime 1.9.0-beta03 وابسته است که به شیء navigationevent-compose اجازه می‌دهد از تمام اهداف KMP پشتیبانی کند. ( Ia1b87 )

نسخه ۱.۰.۰-آلفا۰۵

۳۰ ژوئیه ۲۰۲۵

androidx.navigationevent:navigationevent-*:1.0.0-alpha05 منتشر شد. نسخه 1.0.0-alpha05 شامل این کامیت‌ها است.

پشتیبانی سلسله مراتب والدین-فرزند:

یک NavigationEventDispatcher اکنون می‌تواند دارای dispatcherهای والد و فرزند باشد که یک ساختار درختی سلسله مراتبی را تشکیل می‌دهند. این امر با انعکاس سلسله مراتب ساختاری UI از طریق dispatcherهای زنجیره‌ای، امکان انتشار و مدیریت انعطاف‌پذیرتر رویدادهای ناوبری را در کامپوننت‌های پیچیده رابط کاربری 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 امکان کنترل از بالا به پایین یک dispatcher را فراهم می‌کند. وقتی isEnabled روی یک dispatcher روی false تنظیم شود، به طور خودکار تمام dispatcherهای زیرمجموعه آن را غیرفعال می‌کند. این ویژگی باعث می‌شود که کل شاخه‌های سیستم رویداد ناوبری به طور موثر غیرفعال شوند. ( 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() برای پاکسازی صحیح dispatcherها و فرزندان آنها معرفی شده است. فراخوانی dispose() برای جلوگیری از نشت حافظه، listenerها را متوقف می‌کند، به صورت بازگشتی همه dispatcherهای فرزند را dispose می‌کند، همه callbackهای ثبت شده در dispatcher را حذف می‌کند و آن را از والدش جدا می‌کند. این تضمین می‌کند که منابع به درستی آزاد شوند، زمانی که دیگر به dispatcherها نیازی نیست. ( I9e985 )

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

اگر هر متد عمومی در یک dispatcher دارای dispose فراخوانی شود، بلافاصله یک IllegalStateException ایجاد می‌شود. این امر از خطاهای خاموش جلوگیری می‌کند و به توسعه‌دهندگان کمک می‌کند تا استفاده نادرست را در طول توسعه شناسایی کنند. ( Ic2dc3 )

  val callback2 = TestNavigationEventCallback()

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

نکته: ما یک NavigationEventDispatcherOwner Composable جدید معرفی خواهیم کرد که به طور خودکار یک child dispatcher را در رابط کاربری Compose در aosp/3692572 مدیریت می‌کند. با این حال، این تغییر در نسخه فعلی اعمال نشده و برای نسخه بعدی برنامه‌ریزی شده است.

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

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

تغییرات API

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

رفع اشکالات

  • برای کاهش سربار با اجتناب از تخصیص لیست‌های میانی و بهبود عملکرد ارسال فراخوانی NavigationEventDispatcher اصلاح کنید. ( I82702 ، I1a9d9 )
  • حاشیه‌نویسی‌های @FloatRange را به فیلدهای touchX ، touchY و progress در NavigationEvent اضافه کنید تا محدوده‌های مقادیر معتبر در زمان کامپایل اعمال شوند و ایمنی API بهبود یابد. ( Iac0ec )

نسخه ۱.۰.۰-آلفا۰۴

۲ ژوئیه ۲۰۲۵

androidx.navigationevent:navigationevent-*:1.0.0-alpha04 منتشر شد. نسخه 1.0.0-alpha04 شامل این کامیت‌ها است.

رفع اشکالات

  • از implementedInJetBrainsFork برای navigationevent-compose استفاده شده و یک هدف commonStubs برای مطابقت با قراردادهای Compose اضافه شده است. تغییر درخواست شده توسط JetBrains . ( f60c79 )
  • رفع مشکل افزونه کامپایلر Compose برای Kotlin/Native برای اطمینان از تولید صحیح stub. هیچ تاثیری بر APIهای عمومی یا رفتار ندارد. ( 1890c9 )

نسخه ۱.۰.۰-آلفا۰۳

۱۸ ژوئن ۲۰۲۵

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 در یک زمان ثبت شود؛ اضافه کردن آن به چندین dispatcher باعث ایجاد IllegalStateException می‌شود. توجه داشته باشید که این رفتار با OnBackPressedDispatcher که امکان چندین dispatcher را فراهم می‌کند، متفاوت است. ( e82c19 )
  • isPassThrough یک val برای جلوگیری از جهش در حین ناوبری ساخته شده است، که می‌تواند ارسال NavigationEvent را مختل کند. ( I0b287 )

نسخه ۱.۰.۰-آلفا۰۲

۴ ژوئن ۲۰۲۵

androidx.navigationevent:navigationevent-*:1.0.0-alpha02 منتشر شد. نسخه 1.0.0-alpha02 شامل این کامیت‌ها است.

تغییرات API

  • سازنده ثانویه NavigationEventDispatcher را با آرگومان‌های پیش‌فرض جایگزین کنید. ( I716a0 )
  • ویژگی priority را از NavigationEventCallback حذف کنید. به جای آن priority را به NavigationEventDispatcher.addCallback() ارسال کنید. ( I13cae )

رفع اشکالات

  • خطای ConcurrentModificationException که هنگام فراخوانی NavigationEventCallback.remove() به دلیل تغییر همزمان لیست داخلی closeableها رخ می‌داد، برطرف شد. ( b/420919815 )

نسخه ۱.۰.۰-آلفا۰۱

۲۰ مه ۲۰۲۵

androidx.navigationevent:navigationevent-*:1.0.0-alpha01 منتشر شد. نسخه 1.0.0-alpha01 شامل این کامیت‌ها است.

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

  • کتابخانه androidx.navigationevent یک API مبتنی بر KMP برای مدیریت بازگشت سیستم و همچنین بازگشت پیش‌بینی‌شده ارائه می‌دهد. NavigationEventDispatcher به عنوان یک API مشترک برای ثبت یک یا چند نمونه NavigationEventCallback برای دریافت رویدادهای بازگشت سیستم عمل می‌کند.
  • این لایه زیر APIهای منتشر شده قبلی در androidx.activity قرار می‌گیرد و هدف آن جایگزینی کم‌طرفدارتر برای استفاده از APIهای Activity در کامپوننت‌های سطح بالاتر یا استفاده مستقیم از APIهای OnBackInvokedDispatcher چارچوب اندروید است. APIهای androidx.activity به عنوان بخشی از Activity 1.12.0-alpha01، روی APIهای Navigation Event بازنویسی شده‌اند.