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

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

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

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

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

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

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

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 است که به شما امکان می‌دهد میان‌برهای پویا را در برنامه‌تان مدیریت کنید. استفاده از کتابخانه ShortcutManagerCompat کد تکراری را کاهش می‌دهد و به اطمینان از عملکرد یکنواخت میان‌برها در نسخه‌های مختلف Android کمک می‌کند. این کتابخانه برای ارسال میان‌برهای پویا نیز لازم است تا این میان‌برها واجدشرایط نمایش در سطوح Google—مثل «دستیار»—با کتابخانه یکپارچه‌سازی میان‌برهای Google باشند.

«میانای برنامه‌سازی کاربردی» 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)
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() را در فعالیتی که برای ایجاد میان‌بر سفارشی‌شده استفاده شده است فرا می‌خواند.

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

امتحان کردن میان‌برها

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

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