ناوبری3

Navigation 3 یک کتابخانه ناوبری جدید است که برای کار با Compose طراحی شده است.
آخرین به‌روزرسانی انتشار پایدار کاندیدای انتشار انتشار بتا انتشار آلفا
۲۲ اکتبر ۲۰۲۵ - - ۱.۰.۰-بتا۰۱ -

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

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

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

شیار 

dependencies {
    implementation "androidx.navigation3:navigation3-runtime:1.0.0-beta01"
    implementation "androidx.navigation3:navigation3-ui:1.0.0-beta01"
}

کاتلین 

dependencies {
    implementation("androidx.navigation3:navigation3-runtime:1.0.0-beta01")
    implementation("androidx.navigation3:navigation3-ui:1.0.0-beta01")
}

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

بازخورد

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

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

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

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

نسخه ۱.۰

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

۲۲ اکتبر ۲۰۲۵

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

تغییرات API

  • SceneStrategyScope اکنون فقط یک سازنده عمومی بدون آرگومان دارد که برای آزمایش SceneStrategy و Scene برگشتی به صورت جداگانه مناسب است. برای موارد استفاده پیچیده‌تر، لطفاً از rememberSceneState() استفاده کنید. ( I8440c ، b/451679047 )

رفع اشکالات

  • مشکل حلقه بی‌نهایت هنگام زنجیره‌سازی SceneStrategy با then برطرف شد. ( Iba3f0 ، b/450323470 )
  • لرزش صفحه هنگام تعویض backStack ارسالی به NavDisplay و استفاده از انیمیشن‌ها برطرف شد. ( Ief7b5 ، b/450967248 )

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

۸ اکتبر ۲۰۲۵

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

تغییرات API

  • متد calculateScene در SceneStrategy دیگر @Composable نیست. در عوض، می‌توانید این کار را به ساخت متد SceneStrategy خود (یعنی در یک متد rememberMySceneStrategy() ) منتقل کنید که به شما امکان می‌دهد طول عمر هر مقدار rememberSaveable یا دستورات key remember را از مقادیر صحیح تعریف کنید. ( If1733 , b/448709506 )
  • پارامتر onBack برای SceneStrategy.calculateScene به محدوده گیرنده جدید SceneStrategyScope منتقل شده است تا واضح‌تر شود که این یک پارامتر اختیاری است و یک نقطه گسترش برای ویژگی‌های آینده Navigation3 فراهم می‌کند. ( I3aea3 ، b/448460407 )
  • لامبدا onBack که به NavDisplay و SceneStrategy شما ارسال می‌شود، دیگر پارامتر count: Int را برای نشان دادن زمان نمایش چندین ورودی ارائه نمی‌دهد. در عوض، لامبدا () -> Unit اکنون چندین بار پشت سر هم در موارد نادری که Scene شما درخواست نمایش چندین ورودی را می‌دهد، فراخوانی می‌شود. ( Idedb5 ، b/446989346 )
  • کلاس NavEntryWrapper را حذف کنید و عملکرد آن را با یک کلاس NavEntry نهایی با یک سازنده ثانویه جدید که یک NavEntry با محتوای جدید می‌گیرد، جایگزین کنید. این کار امکان پشتیبانی مداوم از بسته‌بندی یک ورودی با محتوای جدید را فراهم می‌کند. ( I7da2a , b/444447130 )
  • تابع navEntryDecorator که یک NavEntryDecorator ایجاد و برمی‌گرداند، حذف شده و با کلاس NavEntryDecorator جایگزین شده است که اکنون عمومی شده و برای زیرکلاس‌سازی باز است. ( If81f8 , b/444447434 , b/447381176 )
  • SavedStateNavEntryDecorator به SaveableStateHolderNavEntryDecorator تغییر نام داده است، زیرا ورودی‌ها را با SaveableStateHolder تزئین می‌کند. این دکوراتور همچنین از یک تابع به یک کلاس تغییر یافته است، زیرا از نظر عملکردی یک factory برای NavEntryDecorator است. ( Ie6013 ، b/447381176 )
  • نمایشگرهای سفارشی که از SceneState به عنوان جایگزینی برای استفاده از NavDisplay استفاده می‌کنند، دیگر نیازی به استفاده از ترکیب LocalEntriesToRenderInCurrentScene محلی ندارند، که اکنون داخلی است. ( Ic40ef ، b/414668196 )
  • SceneSetupNavEntryDecorator و rememberSceneSetupNavEntryDecorator() از سطح API عمومی حذف شدند. این قابلیت اکنون به طور پیش‌فرض و بدون نیاز به وارد کردن دستی آن توسط شما، در دسترس است. ( Ieae42 , b/444479133 )
  • NavEntry ، DialogScene ، SinglePaneScene و SceneState اکنون همگی equals را پیاده‌سازی می‌کنند. ( I96121 )
  • رابط صحنه یک فیلد فراداده جدید برای الصاق فراداده‌های مختص صحنه به NavDisplay دارد. این به صحنه اجازه می‌دهد تا فراداده‌های موجود در NavDisplay را نادیده بگیرد، برای مثال با انتقال‌ها ( I1fd96 ، b/443955625 ).
  • با حذف پارامتر نوع عمومی زائد، امضای rememberNavBackStack را ساده کنید. این تابع اکنون vararg elements: NavKey . ( I03e45 )
  • انیمیشن‌های پیش‌فرض برای NavDisplay اکنون بخشی از API مشترک هستند که به آنها اجازه می‌دهد از همه پلتفرم‌ها فراخوانی شوند. ( I71af9 , b/447147159 )
  • نام EntryProviderBuilder را به EntryProviderScope تغییر دهید تا دقیقاً نشان دهد که کلاس یک DSL کاتلین است که محدوده‌ای برای ساخت NavEntries ارائه می‌دهد. ( Ia7465 )

رفع اشکالات

  • rememberNavBackStack() اکنون سریال‌سازی چندریختی را برای NavKey اعمال می‌کند و به یک SavedStateConfiguration سفارشی نیاز دارد که برای اطمینان از بازیابی صحیح وضعیت پیکربندی شده باشد. KDoc به‌روزرسانی شده است تا الزام ثبت تمام زیرگروه‌های NavKey در SerializersModule ارائه شده را منعکس کند. ( I6de37 ، I782f2 ، b/446664383 )

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

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

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

تغییرات API

  • یک سربارگذاری جدید NavDisplay اضافه کنید که لیستی از NavEntry<T> که توسط rememberDecoratedNavEntries تزئین شده است را دریافت کند. ( I4025b , b/441940314 )
  • DialogScene به یک بسته جدید منتقل شد. ( Ia5840 )
  • API عمومی DecorateNavEntry حذف کنید. در عوض از rememberDecoratedNavEntries برای قرار دادن یک NavEntry با لیستی از دکوراتورها استفاده کنید. ( Id8c09 )
  • رابط کاربری Navigation3 اکنون ویژگی‌های پیش‌فرض جدید transitionSpec ارائه می‌دهد. ( Ibcabd )
  • یک شیء SceneState جدید برای کمک به مدیریت صحنه‌ها اضافه شد. این شیء همچنین یک سربارگذاری جدید NavDisplay ارائه می‌دهد که SceneState و NavigationEventState دریافت می‌کند. ( Idfb46 ، b/444479133 )
  • NavDisplay اکنون به شما امکان می‌دهد تا با نگاه کردن به currentState و targetState مربوط به Transition ، انتقال‌ها را بر اساس Scene که به آن می‌روید و از آن خارج می‌شوید، سفارشی کنید. ( I906cc ، b/443872322 )
  • NavigationEventInfo اکنون به جای یک interface یک abstract class است. تمام پیاده‌سازی‌های سفارشی را برای ارث‌بری از کلاس به‌روزرسانی کنید (مثلاً data class MyInfo : NavigationEventInfo() ). ( I1e59c , b/444734264 )
  • رابط‌های برنامه‌نویسی (API) مربوط به مدیریت‌کننده‌ی navigationevent-compose به‌روزرسانی شده‌اند. NavigationEventHandler و NavigationBackHandler (و انواع دیگر) اکنون از یک overload جدید پشتیبانی می‌کنند که یک NavigationEventState را که به صورت hoist شده است، می‌پذیرد. overloadهای ساده (با گرفتن currentInfo ) حفظ شده و اکنون از این مدل state جدید به صورت داخلی استفاده می‌کنند. ( Ic3251 ، b/444734264 )
  • تمام APIهای صحنه از navigation3-ui به navigation3-runtime منتقل شده‌اند. این بدان معناست که اکنون آنها در تمام پلتفرم‌های پشتیبانی شده توسط navigation3-runtime در دسترس هستند. ( I431d0 ، b/444449993 )
  • اضافه بار جدید rememberDecoratedNavEntries اضافه شد که لیستی از NavEntry را برای تزئین می‌گیرد. ورودی‌های ورودی می‌توانند از قبل با سایر دکوراتورهای ورودی تزئین شوند. ( I5a034 ، b/444230270 )
  • پارامترهای نوع wildcard مربوط به navigation3 را حذف کنید ( I02540 )
  • مدیریت ژنریک‌ها برای entryProvider DSL بهبود یافته است. اگر قبلاً androidx.navigation3.runtime.entry را وارد می‌کردید، دیگر نیازی به این کار نیست. ( I299fc )
  • محدود کردن سربارگذاری NavBackStackSerializer مبتنی بر بازتاب به اندروید. این کار با اعمال استفاده از سربارگذاری صریح SavedStateConfiguration در کد چند پلتفرمی، از شکست‌های سریال‌سازی ضمنی زمان اجرا در پلتفرم‌های غیر اندروید جلوگیری می‌کند. ( I73313 ، b/420443609 )
  • swipeEdge مربوط به NavigationEvent را به یک @IntDef تبدیل کنید ( Icee54 , b/443950342 )
  • سریال‌سازی NavBackStack را به اندروید محدود کنید. این کار از خطاهای زمان اجرا در پلتفرم‌های غیر اندروید جلوگیری می‌کند. برای ذخیره وضعیت چند پلتفرمی، از overload rememberNavBackStack با یک SavedStateConfiguration صریح استفاده کنید. ( I1e418 , b/420443609 )

رفع اشکالات

  • رفع مشکل از کار افتادن برنامه هنگام فراخوانی پیش‌بینانه، زمانی که NavDisplay تو در تو دارای یک ورودی فرزند بود. ( I2cdc0 ، b/441933162 )

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

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

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

تغییرات API

  • DecoratedNavEntryProvider با rememberDecoratedNavEntries جایگزین شده است که NavEntries را ایجاد کرده و با لیستی از دکوراتورهای ارائه شده ( I0fe1c ، b/441328236 ) تزئین می‌کند.
  • NavBackStack اکنون روی نوع NavKey عمومیت دارد. این به برنامه‌ها و کتابخانه‌ها اجازه می‌دهد تا انواع کلید سفارشی را برای پشته‌های پشتی خود تعریف کنند، نه اینکه محدود به NavKey باشند. ( I4d190 ، Iad2f4 ، b/420443609 )
  • NavBackStack اکنون @kotlinx.serialization.Serializable ‎ تبدیل شده است که امکان ذخیره و بازیابی وضعیت ناوبری را در طول مرگ فرآیند و تغییرات پیکربندی بدون کدهای تکراری اضافی فراهم می‌کند. ( I2c3cf ، b/420443609 )
  • RememberNavBackStack به commonMain منتقل شده است تا از ارائه آن در تمام پلتفرم‌های هدف اطمینان حاصل شود. ( Id69e7 ، b/420443609 )

رفع اشکالات

  • NavDisplay اکنون به درستی هر NavEntry به Lifecycle.State صحیح منتقل می‌کند. ( I30aac ، b/440145700 )
  • مشکلی که باعث می‌شد NavDisplay هر تنظیم تودرتوی NavigationEventDispatcherOwner که از طریق LocalNavigationEventDispatcherOwner کتابخانه NavigationEvent تنظیم شده بود، نادیده بگیرد، برطرف شد. ( I6224a )

تغییرات وابستگی

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

۲۷ آگوست ۲۰۲۵

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

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

  • اهداف جدید Kotlin MultiPlatform (KMP) به مصنوعات Navigation3 Runtime اضافه شد. Navigation3 Runtime اکنون در مجموع از پلتفرم‌های زیر پشتیبانی می‌کند: JVM (اندروید و دسکتاپ)، Native (لینوکس، iOS، watchOS، macOS، MinGW) و وب (جاوااسکریپت، WasmJS). ( I55078 ، b/424410398 ، b/419294028 ، b/419046226 ). توجه: این اهداف KMP را برای مصنوع رابط Navigation3 UI ارائه نمی‌دهد. در سایر پلتفرم‌ها، باید NavDisplay سفارشی خود را پیاده‌سازی کنید. اگر مایل به پشتیبانی از آن هستید، لطفاً در اینجا به موضوع Jetbrains رأی دهید و پیشرفت پشتیبانی بیشتر را در آنجا پیگیری کنید.
  • شیء NavDisplayInfo اکنون عمومی است و می‌تواند برای بازیابی لیست ورودی‌های قابل مشاهده از NavDisplay استفاده شود. ( Ibc91f )

تغییرات API

  • یک NavBackStackSerializer جدید اضافه شده است تا در رابطه با rememberNavBackStack برای انجام بازیابی وضعیت استفاده شود. rememberNavBackStack() اکنون یک SavedStateConfiguration نیز می‌گیرد که می‌تواند برای ارائه پیکربندی شخصی شما استفاده شود. ( I2f4d2 ، I4cd58 ، b/420443609 )

رفع اشکالات

  • مشکلی که باعث می‌شد پیمایش باعث ایجاد رویدادهای نادرست چرخه عمر شود، برطرف شد. ( I8bf6d ، b/425901162 ، b/434109022 )

مشکلات شناخته شده

  • یک اشکال توسط I8bf6d معرفی شده بود که باعث می‌شد Lifecycleها به جای ورودی‌های منفرد، بر اساس صحنه‌ها باشند، که این امر Lifecycle را برای هر موردی که key ارائه شده به NavEntry یک String نیست یا NavEntry شما contentKey بازنویسی نکرده و آن را برابر با key قرار نداده است، از کار می‌انداخت (توجه داشته باشید که انجام این کار مستلزم آن است که کلید شما بتواند در یک Bundle ذخیره شود). این مشکل در نسخه بعدی برطرف شده است. ( b/440145700 )

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

۱۳ آگوست ۲۰۲۵

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

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

تغییرات API

  • SavedStateNavEntryDecorator اکنون از SaveableStateRegistry که در SaveableStateProvider تعبیه شده است برای ذخیره و بازیابی حالت‌ها استفاده می‌کند. ( If8d9a )
  • ویژگی predictivePopTransitionSpec اکنون لبه‌ی سوایپ را به عنوان پارامتر ارائه می‌دهد و به شما امکان می‌دهد تا انتقال را بر اساس لبه‌ای که کاربر حرکت Predictive Back را از آن شروع کرده است، سفارشی کنید. ( I753a8 )

رفع اشکالات

  • مشکلی که باعث می‌شد صحنه‌های سفارشی بی‌نهایت بار دوباره محاسبه شوند، برطرف شد، زیرا جدیدترین صحنه به خاطر سپرده نمی‌شد. ( I7ba84 ، b/418153031 )

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

نسخه ۱.۰.۰-alpha06

۳۰ ژوئیه ۲۰۲۵

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

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

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

۲ ژوئیه ۲۰۲۵

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

تغییرات رفتاری

  • وضعیت NavEntry اکنون کاملاً بر اساس لیست فعلی دکوراتورهای ارسالی به NavDisplay است. این بدان معناست که در صورت وجود چندین پشته پشتی، دکوراتورها باید در امتداد پشته‌های پشتی شما جابجا شوند تا وضعیت NavEntries در پشته پشتی حفظ شود. در غیر این صورت، وضعیت‌ها طوری پاک می‌شوند که انگار ورودی‌ها برداشته شده‌اند (به جای تعویض). ( I7a759 , b/428033667 )

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

۱۸ ژوئن ۲۰۲۵

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

تغییرات API

  • NavEntry.content اکنون خصوصی است. برای فراخوانی محتوای NavEntry ، API جدید NavEntry.Content() را فراخوانی کنید که دیگر نیازی به پارامتر key برای فراخوانی ندارد. ( Icd0fd , b/420991203 )
  • NavEntry.key اکنون یک فیلد خصوصی است. NavEntry و حالت‌های مرتبط با آن باید توسط فیلد contentKey جدید که از لامبدا contentKeyFactory جدید تولید می‌شود، شناسایی شوند و پیش‌فرض آن یک هش قابل ذخیره تولید شده از NavEntry.key است ( I81a6c ، b/422001357 ، b/420991203 I2d7d4 ، b/420991203 ، b/422841812 ).

تغییرات وابستگی

  • Navigation3 اکنون به مصنوع جدید androidx.navigationevent.compose بستگی دارد.

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

۴ ژوئن ۲۰۲۵

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

رفع اشکالات

  • Navigation3 دیگر حالت‌های دکوراتور مربوط به backStacks که حذف شده و با نمونه‌ی دیگری backStack جایگزین شده‌اند را پاک نمی‌کند. ( I28a42 , b/415076044 )

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

۲۳ مه ۲۰۲۵

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

رفع اشکالات

  • مشکلی در SavedStateNavEntryDecorator که باعث ایجاد تصادم برای کلاس‌های داده مختلف با مقادیر ویژگی یکسان می‌شد، برطرف شد. ( b/418070648 , Iff4775 )
  • مشکل فقدان کلاس که باعث خرابی هنگام اجرا بدون تعریف وابستگی‌های صریح می‌شد، برطرف شد. ( b/419049149 , I4b4ed )

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

۲۰ مه ۲۰۲۵

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

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

Navigation3 یک کتابخانه ناوبری جدید است که به طور خاص برای مدیریت ناوبری درون برنامه‌ای Jetpack Compose ساخته شده است. artifact مربوط به androidx.navigation3.runtime بلوک‌های سازنده را فراهم می‌کند، در حالی که artifact مربوط به androidx.navigation3.ui لایه رابط کاربری را از طریق NavDisplay API فراهم می‌کند. توسعه‌دهندگان می‌توانند وضعیت خود را مستقیماً به تابع قابل ترکیب NavDisplay ارائه دهند، که محتوا را بر اساس تغییرات در وضعیت توسعه‌دهنده تغییر می‌دهد.

@Serialiable object Home : NavKey
@Serialiable object Chat : NavKey

val backStack = rememberNavBackStack(Home)

NavDisplay(backStack, entryProvider = entryProvider {
  entry<Home> {
    Column {
      Text(“Home”)
      Button(onClick = { backStack.add(Chat) } ) {
        Text(“Go to Chat”)
      } 
    }
  }
  entry<Chat> { /* My Composable Content */ }
})

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