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

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

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

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

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

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

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

1. در فایل AndroidManifest.xml برنامه خود، فعالیتی را پیدا کنید که فیلترهای هدف آن روی عملکرد 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.ComposeActivity" />
         <!-- 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

عبارتی مختصر که هدف میانبر را توصیف می کند. در صورت امکان، این توضیحات کوتاه را به 10 کاراکتر محدود کنید.

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

android:shortcutLongLabel

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

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

android:shortcutDisabledMessage

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

android:enabled

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

android:icon

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

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

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

intent

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

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

categories

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

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

capability-binding

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

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

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

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

کتابخانه ShortcutManagerCompat Jetpack کمکی برای ShortcutManager API است که به شما امکان می دهد میانبرهای پویا را در برنامه خود مدیریت کنید. استفاده از کتابخانه ShortcutManagerCompat کد دیگ بخار را کاهش می دهد و کمک می کند تا اطمینان حاصل شود که میانبرهای شما به طور مداوم در نسخه های Android کار می کنند. این کتابخانه همچنین برای فشار دادن میانبرهای پویا لازم است تا واجد شرایط ظاهر شدن در سطوح Google (مانند دستیار) با کتابخانه ادغام میانبرهای Google باشند.

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

• فشار و به روز رسانی: از 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)

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

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut);

کتابخانه ادغام میانبرهای گوگل را اضافه کنید

کتابخانه ادغام میانبرهای Google یک کتابخانه اختیاری Jetpack است. این به شما امکان می دهد میانبرهای پویا را فشار دهید که می توانند روی سطوح Android مانند لانچر و سطوح Google مانند Assistant نمایش داده شوند. استفاده از این کتابخانه به کاربران کمک می‌کند میانبرهای شما را برای دسترسی سریع به محتوای خاص یا بازپخش کنش‌های برنامه شما کشف کنند.

به عنوان مثال، یک برنامه پیام رسانی ممکن است پس از ارسال پیام کاربر به آن شخص، یک میانبر پویا برای مخاطبی به نام «الکس» ایجاد کند. پس از فشار دادن میانبر پویا، اگر کاربر از دستیار بپرسد «Hey Google, به Alex در ExampleApp پیام بده»، دستیار می تواند ExampleApp را راه اندازی کند و به طور خودکار آن را برای ارسال پیام به Alex پیکربندی کند.

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

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

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

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

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

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

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

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

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

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

در Android 8.0 (سطح API 26) و بالاتر، می توانید میانبرهای پین شده ایجاد کنید. برخلاف میانبرهای ایستا و پویا، میانبرهای پین شده در لانچرهای پشتیبانی شده به عنوان نمادهای جداگانه ظاهر می شوند. شکل 1 تمایز بین این دو نوع میانبر را نشان می دهد.

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

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

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

   1. اگر میانبر وجود دارد، یک شی ShortcutInfo ایجاد کنید که فقط شامل شناسه میانبر موجود باشد. سیستم تمام اطلاعات دیگر مربوط به میانبر را به صورت خودکار پیدا کرده و پین می کند.
   2. اگر یک میانبر جدید را پین می کنید، یک شی ShortcutInfo ایجاد کنید که شامل شناسه، یک هدف و یک برچسب کوتاه برای میانبر جدید است.

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

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

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

val shortcutManager = getSystemService(ShortcutManager::class.java)

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)
}

ShortcutManager shortcutManager =
        context.getSystemService(ShortcutManager.class);

if (shortcutManager.isRequestPinShortcutSupported()) {
    // Enable the existing shortcut with the ID "my-shortcut".
    ShortcutInfo pinShortcutInfo =
            new 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.
    Intent pinnedShortcutCallbackIntent =
            shortcutManager.createShortcutResultIntent(pinShortcutInfo);

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

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.getIntentSender());
}

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

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

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

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

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

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

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

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