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

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

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

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

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

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

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

بازخورد

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

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

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

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

نسخه 1.0

نسخه 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 بازنویسی شده‌اند.