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

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

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

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

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

شیار 

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

کاتلین 

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

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

بازخورد

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

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

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

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

نسخه 1.0

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