ایجاد میانبرها

میانبرها با کمک به کاربران برای دسترسی سریع به بخش‌هایی از برنامه، انواع خاصی از محتوا را به آنها ارائه می‌دهند.

نحوه ارائه محتوا با میانبرها به مورد استفاده شما و اینکه آیا زمینه میانبر توسط برنامه یا کاربر هدایت می‌شود، بستگی دارد. اگرچه زمینه یک میانبر ایستا تغییر نمی‌کند و زمینه یک میانبر پویا دائماً تغییر می‌کند، برنامه شما در هر دو مورد زمینه را هدایت می‌کند. در مواردی که کاربر نحوه ارائه محتوا توسط برنامه شما را انتخاب می‌کند، مانند یک میانبر پین شده، زمینه توسط کاربر تعریف می‌شود. سناریوهای زیر چند مورد استفاده برای هر نوع میانبر را شرح می‌دهند:

• میانبرهای ایستا برای برنامه‌هایی که در طول مدت تعامل کاربر با برنامه، با استفاده از یک ساختار ثابت به محتوا پیوند می‌دهند، بهترین گزینه هستند. از آنجا که اکثر لانچرها فقط چهار میانبر را به طور همزمان نمایش می‌دهند ، میانبرهای ایستا برای انجام یک کار روتین به روشی ثابت مفید هستند، مانند زمانی که کاربر می‌خواهد تقویم یا ایمیل خود را به روشی خاص مشاهده کند.
• میانبرهای پویا برای اقداماتی در برنامه‌هایی استفاده می‌شوند که حساس به متن هستند. میانبرهای حساس به متن متناسب با اقداماتی هستند که کاربران در یک برنامه انجام می‌دهند. به عنوان مثال، اگر بازی‌ای بسازید که به کاربر اجازه می‌دهد از سطح فعلی خود در هنگام اجرا شروع کند، باید میانبر را مرتباً به‌روزرسانی کنید. استفاده از یک میانبر پویا به شما امکان می‌دهد هر بار که کاربر یک سطح را تمام می‌کند، میانبر را به‌روزرسانی کنید.
• میانبرهای پین‌شده برای اقدامات خاص کاربرمحور استفاده می‌شوند. برای مثال، ممکن است کاربر بخواهد یک وب‌سایت خاص را به لانچر پین کند. این مفید است زیرا به کاربر اجازه می‌دهد یک اقدام سفارشی - مانند پیمایش به وب‌سایت در یک مرحله - را سریع‌تر از استفاده از نمونه پیش‌فرض مرورگر انجام دهد.

ایجاد میانبرهای ثابت

میانبرهای ایستا پیوندهایی به اقدامات عمومی درون برنامه شما ارائه می‌دهند و این اقدامات باید در طول عمر نسخه فعلی برنامه شما ثابت بمانند. گزینه‌های خوب برای میانبرهای ایستا شامل مشاهده پیام‌های ارسالی، تنظیم زنگ هشدار و نمایش فعالیت ورزشی کاربر در طول روز است.

برای ایجاد یک میانبر استاتیک، موارد زیر را انجام دهید:

1. در فایل AndroidManifest.xml برنامه خود، اکتیویتی‌ای را پیدا کنید که فیلترهای intent آن روی اکشن android.intent.action.MAIN و دسته android.intent.category.LAUNCHER تنظیم شده است.

2. یک عنصر <meta-data> به این فعالیت اضافه کنید که به فایل منبعی که میانبرهای برنامه در آن تعریف شده‌اند، ارجاع می‌دهد:

   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
             package="com.example.myapplication">
     <application ... >
       <activity android:name="Main">
         <intent-filter>
           <action android:name="android.intent.action.MAIN" />
           <category android:name="android.intent.category.LAUNCHER" />
         </intent-filter>
         <meta-data android:name="android.app.shortcuts"
                    android:resource="@xml/shortcuts" />
       </activity>
     </application>
   </manifest>
   

3. یک فایل منبع جدید به نام res/xml/shortcuts.xml ایجاد کنید.

4. در فایل منبع جدید، یک عنصر ریشه <shortcuts> اضافه کنید که شامل لیستی از عناصر <shortcut> باشد. در هر عنصر <shortcut> ، اطلاعاتی در مورد یک میانبر ثابت از جمله آیکون آن، برچسب‌های توضیحات و اهدافی که در برنامه اجرا می‌کند، قرار دهید:

   <shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
     <shortcut
       android:shortcutId="compose"
       android:enabled="true"
       android:icon="@drawable/compose_icon"
       android:shortcutShortLabel="@string/compose_shortcut_short_label1"
       android:shortcutLongLabel="@string/compose_shortcut_long_label1"
       android:shortcutDisabledMessage="@string/compose_disabled_message1">
       <intent
         android:action="android.intent.action.VIEW"
         android:targetPackage="com.example.myapplication"
         android:targetClass="com.example.myapplication.Main" />
       <!-- If your shortcut is associated with multiple intents, include them
            here. The last intent in the list determines what the user sees when
            they launch this shortcut. -->
       <categories android:name="android.shortcut.conversation" />
       <capability-binding android:key="actions.intent.CREATE_MESSAGE" />
     </shortcut>
     <!-- Specify more shortcuts here. -->
   </shortcuts>
   

سفارشی‌سازی مقادیر ویژگی‌ها

لیست زیر شامل توضیحاتی برای ویژگی‌های مختلف درون یک میانبر استاتیک است. مقداری برای android:shortcutId و android:shortcutShortLabel وارد کنید. سایر مقادیر اختیاری هستند.

android:shortcutId

یک رشته‌ی تحت‌اللفظی که نشان‌دهنده‌ی میانبر است، زمانی که یک شیء ShortcutManager عملیاتی را روی آن انجام می‌دهد.

android:shortcutShortLabel

یک عبارت مختصر که هدف میانبر را شرح می‌دهد. در صورت امکان، این توضیح کوتاه را به ۱۰ کاراکتر محدود کنید.

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

android:shortcutLongLabel

یک عبارت طولانی که هدف میانبر را توصیف می‌کند. اگر فضای کافی وجود داشته باشد، لانچر این مقدار را به جای android:shortcutShortLabel نمایش می‌دهد. در صورت امکان، این توضیح طولانی را به ۲۵ کاراکتر محدود کنید.

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

android:shortcutDisabledMessage

پیامی که در یک لانچر پشتیبانی‌شده، هنگام تلاش کاربر برای راه‌اندازی یک میانبر غیرفعال، ظاهر می‌شود. این پیام باید به کاربر توضیح دهد که چرا میانبر غیرفعال است. مقدار این ویژگی در صورتی که android:enabled true باشد، هیچ تأثیری ندارد.

android:enabled

تعیین می‌کند که آیا کاربر می‌تواند از طریق یک لانچر پشتیبانی‌شده با میانبر تعامل داشته باشد یا خیر. مقدار پیش‌فرض android:enabled برابر با true است. اگر آن را روی false تنظیم کنید، یک android:shortcutDisabledMessage تنظیم کنید که دلیل غیرفعال کردن میانبر را توضیح دهد. اگر فکر نمی‌کنید که نیازی به ارائه چنین پیامی دارید، میانبر را به طور کامل از فایل XML حذف کنید.

android:icon

آیکون بیت‌مپ یا تطبیقی ​​که لانچر هنگام نمایش میانبر به کاربر از آن استفاده می‌کند. این مقدار می‌تواند مسیر یک تصویر یا فایل منبعی باشد که شامل تصویر است. هر زمان که ممکن است از آیکون‌های تطبیقی ​​​​برای بهبود عملکرد و سازگاری استفاده کنید.

پیکربندی عناصر داخلی

فایل XML که میانبرهای استاتیک یک برنامه را فهرست می‌کند، از عناصر زیر در داخل هر عنصر <shortcut> پشتیبانی می‌کند. شما باید برای هر میانبر استاتیکی که تعریف می‌کنید، یک عنصر داخلی intent نیز اضافه کنید.

intent

عملی که سیستم هنگام انتخاب میانبر توسط کاربر اجرا می‌کند. این intent باید مقداری برای ویژگی android:action ارائه دهد.

شما می‌توانید چندین هدف (Intent) برای یک میانبر ارائه دهید. برای جزئیات بیشتر به مدیریت چندین هدف و فعالیت ، تنظیم یک هدف و مرجع کلاس TaskStackBuilder مراجعه کنید.

categories

دسته‌بندی‌ای برای انواع اقداماتی که میانبرهای برنامه شما انجام می‌دهند، مانند ایجاد پیام‌های چت جدید، ارائه می‌دهد.

برای فهرستی از دسته‌های میانبر پشتیبانی‌شده، به مرجع کلاس ShortcutInfo مراجعه کنید.

capability-binding

قابلیت مرتبط با میانبر را اعلام می‌کند.

در مثال قبلی، میانبر به قابلیتی که برای CREATE_MESSAGE تعریف شده است، لینک شده است که یک اینتنت داخلی App Actions است. این اتصال قابلیت به کاربران اجازه می‌دهد تا از دستورات گفتاری با دستیار گوگل برای فراخوانی یک میانبر استفاده کنند.

ایجاد میانبرهای پویا

میانبرهای پویا پیوندهایی به اقدامات خاص و حساس به متن در برنامه شما ارائه می‌دهند. این اقدامات می‌توانند بین استفاده از برنامه شما و در حین اجرای برنامه تغییر کنند. کاربردهای خوب میانبرهای پویا شامل تماس با یک شخص خاص، پیمایش به یک مکان خاص و بارگیری یک بازی از آخرین نقطه ذخیره کاربر است. همچنین می‌توانید از میانبرهای پویا برای باز کردن یک مکالمه استفاده کنید.

کتابخانه ShortcutManagerCompat Jetpack یک کمک‌کننده برای API ShortcutManager است که به شما امکان می‌دهد میانبرهای پویا را در برنامه خود مدیریت کنید. استفاده از کتابخانه ShortcutManagerCompat کد تکراری را کاهش می‌دهد و به اطمینان از عملکرد مداوم میانبرهای شما در نسخه‌های مختلف اندروید کمک می‌کند. این کتابخانه همچنین برای ایجاد میانبرهای پویا مورد نیاز است تا آنها واجد شرایط نمایش در سطوح گوگل - مانند دستیار - با کتابخانه ادغام میانبرهای گوگل باشند.

API ShortcutManagerCompat به برنامه شما اجازه می‌دهد تا عملیات زیر را با میانبرهای پویا انجام دهد:

• انتشار و به‌روزرسانی: از pushDynamicShortcut() برای انتشار و به‌روزرسانی میانبرهای پویای خود استفاده کنید. اگر از قبل میانبرهای پویا یا پین‌شده با شناسه یکسان وجود داشته باشد، هر میانبر قابل تغییر به‌روزرسانی می‌شود.
• حذف: مجموعه‌ای از میانبرهای پویا را با استفاده removeDynamicShortcuts() حذف می‌کند. تمام میانبرهای پویا را با استفاده removeAllDynamicShortcuts() حذف می‌کند.

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

در اینجا مثالی از ایجاد یک میانبر پویا و مرتبط کردن آن با برنامه شما آورده شده است:

val shortcut = ShortcutInfoCompat.Builder(context, "id1")
        .setShortLabel("Website")
        .setLongLabel("Open the website")
        .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website))
        .setIntent(Intent(Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")))
        .build()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut)

کتابخانه یکپارچه‌سازی میانبرهای گوگل را اضافه کنید

کتابخانه یکپارچه‌سازی میانبرهای گوگل (Google Shortcuts Integration Library) یک کتابخانه اختیاری جت‌پک (Jetpack) است. این کتابخانه به شما امکان می‌دهد میانبرهای پویایی را ایجاد کنید که می‌توانند در سطوح اندروید، مانند لانچر و سطوح گوگل نمایش داده شوند. استفاده از این کتابخانه به کاربران کمک می‌کند تا میانبرهای شما را کشف کنند تا به سرعت به محتوای خاص دسترسی پیدا کنند یا اقدامات را در برنامه شما تکرار کنند.

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

برای مثال، دستیار گوگل می‌تواند از میان‌برهایی که کاربر معمولاً هر روز صبح از برنامه‌ی ردیابی تناسب اندام شما دریافت می‌کند، یاد بگیرد و وقتی کاربر صبح گوشی خود را برمی‌دارد، به‌طور فعال میان‌بر «شروع دویدن» را پیشنهاد دهد.

کتابخانه یکپارچه‌سازی میانبرهای گوگل (Google Shortcuts Integration Library) به خودی خود هیچ قابلیت آدرس‌دهی‌شده‌ای ارائه نمی‌دهد. افزودن این کتابخانه به برنامه‌تان به سطوح گوگل اجازه می‌دهد میانبرهایی را که برنامه‌تان با استفاده از ShortcutManagerCompat ارائه می‌دهد، دریافت کند.

برای استفاده از این کتابخانه در برنامه خود، مراحل زیر را دنبال کنید:

1. فایل gradle.properties خود را برای پشتیبانی از کتابخانه‌های AndroidX به‌روزرسانی کنید:

   android.useAndroidX=true
   # Automatically convert third-party libraries to use AndroidX
   android.enableJetifier=true
   

2. در app/build.gradle ، وابستگی‌هایی برای کتابخانه ادغام میانبرهای گوگل و ShortcutManagerCompat اضافه کنید:

   dependencies {
     implementation "androidx.core:core:1.6.0"
     implementation 'androidx.core:core-google-shortcuts:1.0.0'
     ...
   }
   

با افزودن وابستگی‌های کتابخانه به پروژه اندروید، برنامه شما می‌تواند از متد pushDynamicShortcut() از ShortcutManagerCompat برای ارسال میانبرهای پویا که واجد شرایط نمایش در لانچر و سطوح گوگل شرکت‌کننده هستند، استفاده کند.

ایجاد میانبرهای پین شده

در اندروید ۸.۰ (سطح API ۲۶) و بالاتر، می‌توانید میانبرهای پین‌شده ایجاد کنید. برخلاف میانبرهای ایستا و پویا، میانبرهای پین‌شده در لانچرهای پشتیبانی‌شده به صورت آیکون‌های جداگانه ظاهر می‌شوند. شکل ۱ تفاوت بین این دو نوع میانبر را نشان می‌دهد.

برای پین کردن یک میانبر به یک لانچر پشتیبانی‌شده با استفاده از برنامه خود، مراحل زیر را انجام دهید:

1. از isRequestPinShortcutSupported() برای تأیید پشتیبانی لانچر پیش‌فرض دستگاه از پین کردن میانبرها در برنامه استفاده کنید.

2. بسته به وجود یا عدم وجود میانبر، یک شیء ShortcutInfo را به یکی از دو روش زیر ایجاد کنید:

   1. اگر میانبر وجود دارد، یک شیء ShortcutInfo ایجاد کنید که فقط شامل شناسه میانبر موجود باشد. سیستم تمام اطلاعات دیگر مربوط به میانبر را به طور خودکار پیدا و پین می‌کند.
   2. اگر می‌خواهید یک میانبر جدید را پین کنید، یک شیء ShortcutInfo ایجاد کنید که شامل یک شناسه (ID)، یک هدف (Intent) و یک برچسب کوتاه (short label) برای میانبر جدید باشد.

3. با فراخوانی requestPinShortcut() ‎، میانبر را به لانچر دستگاه پین ​​کنید. در طول این فرآیند، می‌توانید یک شیء PendingIntent ارسال کنید که فقط زمانی که میانبر با موفقیت پین می‌شود، به برنامه شما اطلاع می‌دهد.

   پس از پین کردن یک میانبر، برنامه شما می‌تواند محتوای آن را با استفاده از متد updateShortcuts() به‌روزرسانی کند. برای اطلاعات بیشتر، بخش به‌روزرسانی میانبرها را مطالعه کنید.

قطعه کد زیر نحوه ایجاد یک میانبر پین شده را نشان می‌دهد.

val shortcutManager = getSystemService<ShortcutManager>()

if (shortcutManager!!.isRequestPinShortcutSupported) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build()

    // Create the PendingIntent object only if your app needs to be notified
    // that the user let the shortcut be pinned. If the pinning operation fails,
    // your app isn't notified. Assume here that the app implements a method
    // called createShortcutResultIntent() that returns a broadcast intent.
    val pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(pinShortcutInfo)

    // Configure the intent so that your app's broadcast receiver gets the
    // callback successfully. For details, see PendingIntent.getBroadcast().
    val successCallback = PendingIntent.getBroadcast(context, /* request code */ 0,
            pinnedShortcutCallbackIntent, /* flags */ 0)

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.intentSender)
}

ایجاد یک فعالیت میانبر سفارشی

همچنین می‌توانید یک فعالیت تخصصی ایجاد کنید که به کاربران در ایجاد میانبرها کمک می‌کند، که شامل گزینه‌های سفارشی و یک دکمه تأیید است. شکل 2 نمونه‌ای از این نوع فعالیت را در برنامه Gmail نشان می‌دهد.

در فایل مانیفست برنامه خود، ACTION_CREATE_SHORTCUT را به عنصر <intent-filter> مربوط به اکتیویتی اضافه کنید. این تعریف، رفتار زیر را هنگام تلاش کاربر برای ایجاد میانبر تنظیم می‌کند:

1. سیستم فعالیت تخصصی برنامه شما را آغاز می‌کند.
2. کاربر گزینه‌های مربوط به میانبر را تنظیم می‌کند.
3. کاربر دکمه تأیید را انتخاب می‌کند.
4. برنامه شما با استفاده از متد createShortcutResultIntent() میانبر را ایجاد می‌کند. این متد یک Intent برمی‌گرداند که برنامه شما با استفاده از setResult() آن را به اکتیویتی که قبلاً در حال اجرا بوده است، منتقل می‌کند.
5. برنامه شما تابع finish() را روی اکتیویتی مورد استفاده برای ایجاد میانبر سفارشی فراخوانی می‌کند.

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

میانبرهای آزمایشی

برای آزمایش میانبرهای برنامه، برنامه خود را روی دستگاهی با لانچری که از میانبرها پشتیبانی می‌کند نصب کنید. سپس، اقدامات زیر را انجام دهید:

• برای مشاهده میانبرهایی که برای برنامه خود تعریف کرده‌اید، نماد راه‌انداز برنامه خود را لمس کرده و نگه دارید.
• یک میانبر را بکشید تا به لانچر دستگاه پین ​​شود.