در اندروید، پیوند عمیق پیوندی است که شما را مستقیماً به یک مقصد خاص در یک برنامه می برد.
مؤلفه Navigation به شما امکان می دهد دو نوع مختلف پیوند عمیق ایجاد کنید: صریح و ضمنی .
یک پیوند عمیق صریح ایجاد کنید
پیوند عمیق صریح یک نمونه واحد از یک پیوند عمیق است که از PendingIntent
برای بردن کاربران به مکان خاصی در برنامه شما استفاده می کند. برای مثال، ممکن است یک پیوند عمیق صریح را به عنوان بخشی از یک اعلان یا یک ویجت برنامه نشان دهید.
هنگامی که کاربر برنامه شما را از طریق یک پیوند عمیق صریح باز می کند، پشته کار پاک می شود و با مقصد پیوند عمیق جایگزین می شود. هنگام تودرتو کردن نمودارها ، مقصد شروع از هر سطح از تودرتو - یعنی مقصد شروع از هر عنصر <navigation>
در سلسله مراتب - نیز به پشته اضافه می شود. این به این معنی است که وقتی کاربر دکمه بازگشت را از مقصد پیوند عمیق فشار میدهد، از پشته ناوبری پشتیبان میگیرد، درست مثل اینکه از نقطه ورودی برنامه شما را وارد کرده است.
همانطور که در مثال زیر نشان داده شده است می توانید از کلاس NavDeepLinkBuilder
برای ساخت PendingIntent
استفاده کنید. توجه داشته باشید که اگر زمینه ارائه شده یک Activity
نباشد، سازنده از PackageManager.getLaunchIntentForPackage()
به عنوان فعالیت پیشفرض برای راهاندازی، در صورت موجود بودن، استفاده میکند.
کاتلین
val pendingIntent = NavDeepLinkBuilder(context) .setGraph(R.navigation.nav_graph) .setDestination(R.id.android) .setArguments(args) .createPendingIntent()
جاوا
PendingIntent pendingIntent = new NavDeepLinkBuilder(context) .setGraph(R.navigation.nav_graph) .setDestination(R.id.android) .setArguments(args) .createPendingIntent();
به طور پیشفرض، NavDeepLinkBuilder
پیوند عمیق صریح شما را به Activity
راهاندازی پیشفرض که در مانیفست برنامه شما اعلام شده است، راهاندازی میکند. اگر NavHost
شما در فعالیت دیگری است، باید نام مؤلفه آن را هنگام ایجاد لینک سازنده عمیق مشخص کنید:
کاتلین
val pendingIntent = NavDeepLinkBuilder(context) .setGraph(R.navigation.nav_graph) .setDestination(R.id.android) .setArguments(args) .setComponentName(DestinationActivity::class.java) .createPendingIntent()
جاوا
PendingIntent pendingIntent = new NavDeepLinkBuilder(context) .setGraph(R.navigation.nav_graph) .setDestination(R.id.android) .setArguments(args) .setComponentName(DestinationActivity.class) .createPendingIntent();
اگر یک ComponentName
دارید، میتوانید آن را مستقیماً به سازنده ارسال کنید:
کاتلین
val componentName = ... val pendingIntent = NavDeepLinkBuilder(context) .setGraph(R.navigation.nav_graph) .setDestination(R.id.android) .setArguments(args) .setComponentName(componentName) .createPendingIntent()
جاوا
ComponentName componentName = ...; PendingIntent pendingIntent = new NavDeepLinkBuilder(context) .setGraph(R.navigation.nav_graph) .setDestination(R.id.android) .setArguments(args) .setComponentName(componentName) .createPendingIntent();
اگر یک NavController
موجود دارید، میتوانید با استفاده از NavController.createDeepLink()
یک پیوند عمیق نیز ایجاد کنید.
یک پیوند عمیق ضمنی ایجاد کنید
پیوند عمیق ضمنی به یک مقصد خاص در یک برنامه اشاره دارد. هنگامی که پیوند عمیق فراخوانی می شود - به عنوان مثال، وقتی کاربر روی یک پیوند کلیک می کند - Android می تواند برنامه شما را به مقصد مربوطه باز کند.
پیوندهای عمیق را می توان با URI، اقدامات قصد، و انواع MIME مطابقت داد. شما می توانید چندین نوع تطابق را برای یک پیوند عمیق مشخص کنید، اما توجه داشته باشید که تطبیق آرگومان URI ابتدا اولویت بندی می شود، سپس اقدام، و سپس نوع MIME.
در اینجا یک نمونه پیوند عمیق است که حاوی یک URI، یک اقدام و یک نوع MIME است:
<fragment android:id="@+id/a"
android:name="com.example.myapplication.FragmentA"
tools:layout="@layout/a">
<deepLink app:uri="www.example.com"
app:action="android.intent.action.MY_ACTION"
app:mimeType="type/subtype"/>
</fragment>
همچنین می توانید از ویرایشگر ناوبری برای ایجاد یک پیوند عمیق ضمنی به یک مقصد به شرح زیر استفاده کنید:
- در برگه طراحی ویرایشگر ناوبری، مقصد پیوند عمیق را انتخاب کنید.
- در قسمت Deep Links پانل Attributes روی + کلیک کنید.
در گفتگوی افزودن پیوند عمیق که ظاهر می شود، اطلاعات پیوند عمیق خود را وارد کنید.
به موارد زیر توجه کنید:
- URI های بدون طرح به عنوان http یا https در نظر گرفته می شوند. برای مثال،
www.google.com
با هر دوhttp://www.google.com
وhttps://www.google.com
مطابقت دارد. - متغیرهای پارامتر مسیر به شکل
{placeholder_name}
با یک یا چند کاراکتر مطابقت دارند. برای مثال،http://www.example.com/users/{id}
باhttp://www.example.com/users/4
مطابقت دارد. مؤلفه Navigation با تطبیق نام مکاننماها با آرگومانهای تعریفشده که برای مقصد پیوند عمیق تعریف شدهاند، تلاش میکند مقادیر مکاننما را به انواع مناسب تجزیه کند. اگر هیچ آرگومانی با همان نام تعریف نشده باشد، یک نوعString
پیش فرض برای مقدار آرگومان استفاده می شود. می توانید از علامت .* برای مطابقت دادن 0 یا بیشتر کاراکتر استفاده کنید. - متغیرهای پارامتر Query را می توان به جای یا همراه با پارامترهای مسیر استفاده کرد. برای مثال،
http://www.example.com/users/{id}?myarg={myarg}
باhttp://www.example.com/users/4?myarg=28
مطابقت دارد. - متغیرهای پارامتر پرس و جو برای متغیرهایی که با مقادیر پیشفرض یا تهی تعریف شدهاند نیازی به مطابقت ندارند. برای مثال،
http://www.example.com/users/{id}?arg1={arg1}&arg2={arg2}
باhttp://www.example.com/users/4?arg2=28
یاhttp://www.example.com/users/4?arg1=7
. این مورد در مورد پارامترهای مسیر صادق نیست. برای مثال،http://www.example.com/users?arg1=7&arg2=28
با الگوی بالا مطابقت ندارد زیرا پارامتر مسیر مورد نیاز ارائه نشده است. - پارامترهای پرس و جو خارجی بر تطابق URI پیوند عمیق تأثیر نمی گذارد. برای مثال،
http://www.example.com/users/{id}
باhttp://www.example.com/users/4?extraneousParam=7
مطابقت دارد، حتی اگرextraneousParam
در الگوی URI تعریف نشده باشد.
- URI های بدون طرح به عنوان http یا https در نظر گرفته می شوند. برای مثال،
(اختیاری) تأیید خودکار را علامت بزنید تا از Google بخواهید تأیید کند که شما مالک URI هستید. برای اطلاعات بیشتر، به تأیید پیوندهای برنامه Android مراجعه کنید.
روی افزودن کلیک کنید. یک نماد پیوند
بالای مقصد انتخاب شده ظاهر می شود تا نشان دهد مقصد دارای پیوند عمیق است.
روی تب Code کلیک کنید تا به نمای XML بروید. یک عنصر
<deepLink>
تودرتو به مقصد اضافه شده است:<deepLink app:uri="https://www.google.com" />
برای فعال کردن پیوند عمیق ضمنی، باید به فایل manifest.xml
برنامه خود نیز اضافه کنید. همانطور که در مثال زیر نشان داده شده است، یک عنصر <nav-graph>
را به فعالیتی که به یک نمودار ناوبری موجود اشاره می کند، اضافه کنید:
<?xml version="1.0" encoding="utf-8"?> <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.myapplication"> <application ... > <activity name=".MainActivity" ...> ... <nav-graph android:value="@navigation/nav_graph" /> ... </activity> </application> </manifest>
هنگام ساخت پروژه، مؤلفه Navigation عنصر <nav-graph>
را با عناصر <intent-filter>
ایجاد شده جایگزین میکند تا با تمام پیوندهای عمیق در نمودار ناوبری مطابقت داشته باشد.
هنگام راهاندازی یک پیوند عمیق ضمنی، وضعیت پشته به این بستگی دارد که آیا Intent
ضمنی با پرچم Intent.FLAG_ACTIVITY_NEW_TASK
راهاندازی شده است یا خیر:
- اگر پرچم تنظیم شده باشد، پشته کار پاک می شود و با مقصد پیوند عمیق جایگزین می شود. مانند پیوند عمیق صریح ، هنگام تودرتو کردن نمودارها ، مقصد شروع از هر سطح تودرتو - یعنی مقصد شروع از هر عنصر
<navigation>
در سلسله مراتب - نیز به پشته اضافه می شود. این به این معنی است که وقتی کاربر دکمه بازگشت را از مقصد پیوند عمیق فشار میدهد، از پشته ناوبری پشتیبان میگیرد، درست مثل اینکه از نقطه ورودی برنامه شما را وارد کرده است. - اگر پرچم تنظیم نشده باشد، در پشته وظیفه برنامه قبلی که پیوند عمیق ضمنی فعال شده است، میمانید. در این حالت، دکمه برگشت شما را به برنامه قبلی برمی گرداند، در حالی که دکمه بالا کار برنامه شما را در مقصد والد سلسله مراتبی در نمودار ناوبری شما شروع می کند.
مدیریت لینک های عمیق
اکیداً توصیه می شود هنگام استفاده از Navigation همیشه از launchMode
پیش فرض standard
استفاده کنید. هنگام استفاده از حالت راه اندازی standard
، Navigation به طور خودکار پیوندهای عمیق را با فراخوانی handleDeepLink()
برای پردازش هر پیوند عمیق صریح یا ضمنی در Intent
کنترل می کند. با این حال، در صورت استفاده مجدد از Activity
هنگام استفاده از launchMode
جایگزین مانند singleTop
، این امر بهطور خودکار اتفاق نمیافتد. در این مورد، لازم است که handleDeepLink()
به صورت دستی در onNewIntent()
فراخوانی کنید، همانطور که در مثال زیر نشان داده شده است:
کاتلین
override fun onNewIntent(intent: Intent?) { super.onNewIntent(intent) navController.handleDeepLink(intent) }
جاوا
@Override protected void onNewIntent(Intent intent) { super.onNewIntent(intent); navController.handleDeepLink(intent); }
منابع اضافی
برای کسب اطلاعات بیشتر در مورد ناوبری، به منابع زیر مراجعه کنید.