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

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

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

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

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

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

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

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.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>
   shortcuts.xml

سفارشی‌سازی مقادیر مشخصه

فهرست زیر شامل شرحی از مشخصه‌های مختلف در میان‌بر ایستا است. مقداری برای 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

کنشی که سیستم هنگام انتخاب میان‌بر توسط کاربر راه‌اندازی می‌کند. این هدف باید مقداری برای مشخصه android:action ارائه دهد.

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

categories

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

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

capability-binding

قابلیت پیوندشده با میان‌بر را اعلام می‌کند.

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

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

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

کتابخانه Jetpack ShortcutManagerCompat کمکی برای 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)
ShortcutsSnippets.kt

افزودن کتابخانه ادغام میان‌برهای Google

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

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

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

«کتابخانه ادغام میان‌برهای Google» هیچ عملکرد قابل‌دسترسی را به‌تنهایی ارائه نمی‌دهد. با افزودن این کتابخانه به برنامه‌تان، سطوح Google می‌توانند میان‌برهایی را که برنامه‌تان بااستفاده از ShortcutManagerCompat ارسال می‌کند دریافت کنند.

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

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

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

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

ایجاد میان‌برهای سنجاق‌شده

در Android 8.0 (سطح میانای برنامه‌سازی کاربردی ۲۶) و بالاتر، می‌توانید میان‌برهای سنجاق‌شده ایجاد کنید. برخلاف میان‌برهای پویا و ایستا، میان‌برهای سنجاق‌شده در راه‌اندازهای پشتیبانی‌شده به‌صورت نمادهای جداگانه نشان داده می‌شوند. شکل ۱ تفاوت بین این دو نوع میان‌بر را نشان می‌دهد.

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

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

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

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

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

تکه‌کد زیر نحوه ایجاد میان‌بر سنجاق‌شده را نشان می‌دهد:

if (ShortcutManagerCompat.isRequestPinShortcutSupported(context)) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfoCompat.Builder(context, "my-shortcut")
        .setShortLabel("Website")
        .setIntent(
            Intent(
                Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")
            )
        )
        .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 =
        ShortcutManagerCompat.createShortcutResultIntent(context, 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 */ PendingIntent.FLAG_IMMUTABLE
    )

    ShortcutManagerCompat.requestPinShortcut(
        context,
        pinShortcutInfo,
        successCallback.intentSender
    )
}
ShortcutsSnippets.kt

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

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

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

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

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

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

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

• نماد راه‌انداز برنامه‌تان را لمس کنید و نگه دارید تا میان‌برهایی را که برای برنامه‌تان تعریف کرده‌اید ببینید.
• میان‌بری را بکشید تا آن را به راه‌انداز دستگاه سنجاق کنید.