יצירת קיצורי דרך

קיצורי דרך עוזרים להציג למשתמשים תכנים מסוגים מסוימים לגשת במהירות לחלקים באפליקציה.

איור 1. קיצורי דרך של אפליקציות וקיצורי דרך מוצמדים.

האופן שבו אתם מעבירים תוכן באמצעות קיצורי דרך תלוי בתרחיש לדוגמה שלכם ובשאלה אם ההקשר של קיצור הדרך הוא מבוסס-אפליקציה או מבוסס-משתמש. אף על פי ההקשר של קיצור הדרך לא משתנה וההקשר של קיצור הדרך הדינמי לא משתנה כל הזמן משתנה, האפליקציה מעודדת את ההקשר בשני המקרים. במקרים שבהם משתמש בוחר איך האפליקציה תציג תוכן, למשל באמצעות קיצור דרך מוצמד, ההקשר מוגדר על ידי המשתמש. התרחישים הבאים מתארים כמה שימושים בקשות תמיכה לכל סוג של קיצור דרך:

• סטטי קיצורי דרך הם המתאימים ביותר לאפליקציות שמקשרות לתוכן באמצעות לכל אורך החיים של האינטראקציה של המשתמש עם כי רוב מרכזי האפליקציות להציג רק ארבע קיצורי דרך בו-זמנית, קיצורי דרך סטטיים שימושיים לביצוע תרחיש באופן עקבי, למשל אם המשתמש רוצה לצפות ביומן שלו אימייל באופן ספציפי .
• דינמית קיצורי דרך משמשים לפעולות באפליקציות תלויי הקשר. מקשי הקיצור תלויי-הקשר מותאמים פעולות שמשתמשים מבצעים באפליקציה. לדוגמה, אם אתם מפתחים משחק שמאפשר המשתמש מתחיל מהרמה הנוכחית שלו בהפעלה, צריך לעדכן את לעתים קרובות. שימוש בקיצור דרך דינמי מאפשר לך לעדכן את קיצור הדרך בכל פעם שהמשתמש עובר לשלב הבא.
• שיחות מוצמדות קיצורי דרך משמשים לפעולות ספציפיות שמבוצעות על ידי המשתמשים. לדוגמה, משתמש עשוי לרצות להצמיד אתר ספציפי למרכז האפליקציות. הדבר מועילות כי היא מאפשרת למשתמש לבצע פעולה מותאמת אישית, כמו ניווט אל האתר בשלב אחד, מהר יותר מאשר שימוש בברירת מחדל מופע של דפדפן.

יצירת קיצורי דרך סטטיים

קיצורי דרך סטטיים מספקים קישורים לפעולות כלליות בתוך האפליקציה. הפעולות חייבות להיות עקביות בכל משך החיים של הגרסה הנוכחית של האפליקציה. אפשרויות טובות לקיצורי דרך סטטיים כוללות הצגת הודעות שנשלחו, הגדרת שעון מעורר, והצגת פעילות גופנית של משתמש במהלך היום.

כדי ליצור קיצור דרך סטטי, מבצעים את הפעולות הבאות:

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>
     

   הערה: אם משתמשים activity-alias להגדיר את המטא-נתונים בכינוי הפעילויות במקום את הפעילות שאליה הם מטרגטים באמצעות targetActivity .

3. יוצרים קובץ משאבים חדש בשם res/xml/shortcuts.xml.

4. בקובץ המשאב החדש, מוסיפים רכיב בסיס (root) <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 האובייקט מבצע פעולות עליו.

הערה: אי אפשר להגדיר את הערך של המאפיין הזה כמחרוזת משאב, כמו בתור @string/shortcut_id.

android:shortcutShortLabel

ביטוי תמציתי שמתאר את מטרת קיצור הדרך. כשהדבר אפשרי, יש להגביל את התיאור הקצר ל-10 תווים.

מידע נוסף זמין במאמר הבא: setShortLabel()

הערה: הערך של המאפיין הזה חייב להיות מחרוזת משאב, כמו @string/shortcut_short_label

android:shortcutLongLabel

ביטוי מורחב שמתאר את המטרה של קיצור הדרך. אם יש מספיק במרכז האפליקציות מציג את הערך הזה במקום android:shortcutShortLabel ככל האפשר, יש להגביל את משך הזמן הזה באורך של עד 25 תווים.

מידע נוסף זמין במאמר הבא: setLongLabel()

הערה: הערך של המאפיין הזה חייב להיות מחרוזת משאב, כמו @string/shortcut_long_label

android:shortcutDisabledMessage

ההודעה שמופיעה במרכז אפליקציות נתמך כשהמשתמש מנסה הפעלת קיצור דרך מושבת. בהודעה צריך להסביר למשתמש למה קיצור הדרך מושבת. לערך של המאפיין הזה אין השפעה אם android:enabled היא true.

הערה: הערך של המאפיין הזה חייב להיות מחרוזת משאב, כמו @string/shortcut_disabled_message

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 שהיא פעולות באפליקציה כוונה מובנית. קישור היכולת הזה מאפשר למשתמשים להשתמש בפקודות קוליות עם Google Assistant כדי להפעיל קיצור דרך.

יצירת קיצורי דרך דינמיים

קיצורי דרך דינמיים מספקים קישורים לפעולות ספציפיות ותלויות-הקשר בתוך באפליקציה שלך. הפעולות האלה יכולות להשתנות בין השימוש באפליקציה לבין זמן השימוש באפליקציה פועלת. שימושים טובים בקיצורי דרך דינמיים כוללים התקשרות לאדם ספציפי, ניווט למיקום ספציפי וטעינה של משחק מתוך השמירה האחרונה של המשתמש לנקודה. אפשר גם להשתמש בקיצורי דרך דינמיים כדי לפתוח שיחה.

ShortcutManagerCompat ספריית Jetpack עוזרת ShortcutManager ממשק API, שמאפשר לנהל את קיצורי הדרך הדינמיים באפליקציה. באמצעות הספרייה ShortcutManagerCompat מפחיתה את הקוד הסטנדרטי ועוזרת כדי להבטיח שמקשי הקיצור יפעלו באופן עקבי בכל הגרסאות של Android. הזה נדרשת גם כדי להפעיל קיצורי דרך דינמיים, כך שהם יהיו כשירים. להופיע בפלטפורמות של Google — כמו Assistant — ספריית שילוב קיצורי הדרך של Google

ה-API של ShortcutManagerCompat מאפשר לאפליקציה לבצע את הפעולות הבאות פעולות עם קיצורי דרך דינמיים:

• דחיפה ועדכון: משתמשים pushDynamicShortcut() כדי לפרסם ולעדכן את קיצורי הדרך הדינמיים. אם יש כבר מודעות דינמיות או קיצורי דרך מוצמדים עם אותו מזהה, כל קיצור דרך מתעדכן.
• הסרה: הסרת קבוצה של קיצורי דרך דינמיים באמצעות removeDynamicShortcuts(). הסרת כל קיצורי הדרך הדינמיים באמצעות removeAllDynamicShortcuts()

למידע נוסף על ביצוע פעולות על קיצורי דרך, אפשר לעיין במאמר ניהול מקשי הקיצור את הרצף ShortcutManagerCompat הפניה.

הנה דוגמה ליצירת קיצור דרך דינמי ולשיוך שלו אל app:

Kotlin

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)

Java

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

ספריית השילוב של קיצורי הדרך של Google היא ספרייה אופציונלית ב-Jetpack. הוא מאפשר להעביר קיצורי דרך דינמיים שמוצגים בפלטפורמות של Android, במרכז האפליקציות ובפלטפורמות של Google, למשל Assistant. בשימוש בספרייה הזו עוזר למשתמשים לגלות את קיצורי הדרך שלכם כדי לגשת במהירות לתוכן ספציפי או להפעלה חוזרת פעולות באפליקציה.

לדוגמה, באפליקציית הודעות אפשר להעביר קיצור דרך דינמי לאיש קשר מסוים בשם "Alex" אחרי שמשתמש שולח הודעה לאותו משתמש. אחרי שקיצור הדרך הדינמי הוא נדחפת, אם המשתמש שואל את Assistant, "Ok Google, message to Alex on exampleApp, Assistant יכולה להפעיל את ExampleApp ולהגדיר אותה באופן אוטומטי. כדי לשלוח הודעה לאלכס.

קיצורי דרך דינמיים שהועברו בספרייה הזו לא כפופים ל מגבלות לקיצורי דרך אכיפה ברמת המכשיר. כך האפליקציה שלך יכולה לשלוח בדחיפה קיצור דרך בכל פעם משתמש משלים פעולה משויכת באפליקציה שלכם. העברה בדחיפה של קיצורי דרך תכופים שמאפשר ל-Google להבין את דפוסי השימוש של המשתמש ולהציע הקשר את קיצורי הדרך הרלוונטיים אליהם.

לדוגמה, Assistant יכולה ללמוד מקיצורי דרך שהופעלו באמצעות אפליקציית מעקב כושר שמשתמש מפעיל בדרך כלל מדי בוקר באופן יזום להציע 'התחלת ריצה'. קיצור דרך כאשר המשתמש מרים את הטלפון שלו בבוקר.

בספריית השילוב של קיצורי הדרך של 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, מוסיפים יחסי תלות של ספריית שילוב קיצורי הדרך ו-ShortcutManagerCompat:

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

עם יחסי התלות של הספריות שנוספו לפרויקט Android שלך, האפליקציה יכולה להשתמש ה-method pushDynamicShortcut() מ- ShortcutManagerCompat כדי להעביר קיצורי דרך דינמיים שעומדים בדרישות להצגה במרכז האפליקציות ובפלטפורמות של Google שמשתתפות בו.

הערה: אנחנו ממליצים להשתמש ב-pushDynamicShortcut כדי לדחוף קיצורי דרך דינמיים באמצעות ספריית השילוב של קיצורי הדרך של Google. האפליקציה שלך יכולה משתמשים בשיטות אחרות לפרסום קיצורי דרך, אבל הם עלולים להיכשל אם הם יגיעו אל מספר מקסימלי של קיצורי דרך.

יצירת קיצורי דרך מוצמדים

במכשירי Android בגרסה 8.0 (רמת API 26) ואילך, אפשר ליצור קיצורי דרך מוצמדים. בניגוד לקיצורי דרך סטטיים ודינמיים, קיצורי הדרך המוצמדים מופיעים של מרכזי אפליקציות כסמלים נפרדים. איור 1 מציג את ההבחנה בין שני המצבים כמה סוגים של קיצורי דרך.

הערה: כשמנסים להצמיד קיצור דרך למרכז אפליקציות נתמך, המשתמש מקבל תיבת דו-שיח לאישור שמבקשת ממנו להצמיד את מקש קיצור. אם המשתמש לא מאפשר להצמיד את קיצור הדרך, מרכז האפליקציות מבוטל לבקשה.

כדי להצמיד קיצור דרך למרכז אפליקציות נתמך באמצעות האפליקציה שלך, צריך להשלים את את השלבים הבאים:

1. כדאי להשתמש isRequestPinShortcutSupported() כדי לוודא שמרכז האפליקציות המוגדר כברירת מחדל במכשיר תומך בהצמדה של

2. אפשר ליצור אובייקט ShortcutInfo באחת משתי דרכים, בהתאם אם קיצור הדרך קיים:

   1. אם קיצור הדרך קיים, יוצרים אובייקט ShortcutInfo מכיל רק את המזהה של קיצור הדרך הקיים. המערכת מאתרת ומצמידה את כל הפריטים מידע נוסף שקשור לקיצור הדרך באופן אוטומטי.
   2. אם מצמידים קיצור דרך חדש, צריך ליצור ShortcutInfo שמכיל מזהה, Intent ותווית קצרה מקש קיצור.
   הערה: כי המערכת מבצעת גיבוי ומשחזרים באופן אוטומטי בקיצורי הדרך המוצמדים, מזהים חייב להכיל מחרוזות קבועות וקבועות או מזהים בצד השרת, מאשר מזהים שנוצרים באופן מקומי ושעשויים להיות לא הגיוניים מכשירים.

3. הצמדת קיצור הדרך למרכז האפליקציות של המכשיר על ידי ביצוע שיחה requestPinShortcut() בתהליך הזה אפשר להעביר PendingIntent אובייקט, שיודיע לאפליקציה רק כשקיצור הדרך מוצמד בהצלחה.

   הערה: אם המשתמש לא מאפשר להצמיד את קיצור הדרך אל במרכז האפליקציות, לא מתקבלת שיחה חוזרת באפליקציה.

   לאחר הצמדת קיצור דרך, האפליקציה יכולה לעדכן את התוכן שלו באמצעות updateShortcuts() . מידע נוסף זמין במאמר הבא: עדכון מקשי קיצור.

קטע הקוד הבא מדגים איך ליצור קיצור דרך מוצמד.

הערה: מופעים של המחלקה ShortcutManager חייבים להיות משיגים באמצעות Context.getSystemService(Class) עם הארגומנט ShortcutManager.class או Context.getSystemService(String) עם הארגומנט Context.SHORTCUT_SERVICE.

Kotlin

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

Java

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

הערה: כדאי לעיין גם בממשקי ה-API של ספריית התמיכה. isRequestPinShortcutSupported() וגם requestPinShortcut(), שפועלים ב-Android 7.1 (רמת API 25) ובגרסאות מוקדמות יותר. ספריית התמיכה נופלת בחזרה ל- EXTRA_SHORTCUT_INTENT כדי לנסות את תהליך ההצמדה.

יצירת פעילות של קיצור דרך בהתאמה אישית

איור 2. דוגמה לפעילות של תיבת דו-שיח עם קיצורי דרך בהתאמה אישית לאפליקציה.

תוכלו גם ליצור פעילות מיוחדת שעוזרת למשתמשים ליצור קיצורי דרך, כולל אפשרויות מותאמות אישית ולחצן אישור. איור 2 מראה דוגמה לפעילות מהסוג הזה באפליקציית Gmail.

בקובץ המניפסט של האפליקציה, יש להוסיף ACTION_CREATE_SHORTCUT לפעילות <intent-filter> לרכיב מסוים. ההצהרה הזו מגדירה את ההתנהגות הבאה כשהמשתמש מנסה כדי ליצור קיצור דרך:

1. המערכת מתחילה את הפעילות המיוחדת של האפליקציה.
2. המשתמש מגדיר אפשרויות לקיצור הדרך.
3. המשתמש לוחץ על לחצן האישור.
4. האפליקציה שלך יוצרת את קיצור הדרך באמצעות createShortcutResultIntent() . השיטה הזו מחזירה Intent, שהאפליקציה שלכם מעבירה בחזרה לפעילות שבוצעה קודם לכן באמצעות setResult().
5. השיחות שלך מהאפליקציה finish() בפעילות ששימשה ליצירת קיצור הדרך המותאם אישית.

באופן דומה, האפליקציה יכולה לבקש מהמשתמשים להוסיף לבית קיצורי דרך מוצמדים. לאחר ההתקנה או בפעם הראשונה שהאפליקציה מופעלת. השיטה הזאת יעילה כי היא עוזרת למשתמשים ליצור קיצור דרך כחלק תהליך העבודה הרגיל.

בדיקת מקשי הקיצור

כדי לבדוק את קיצורי הדרך של האפליקציה, עליך להתקין את האפליקציה במכשיר באמצעות מרכז האפליקציות שתומך בקיצורי דרך. לאחר מכן, מבצעים את הפעולות הבאות:

• מגע ו- צריך ללחוץ לחיצה ארוכה על סמל מרכז האפליקציות של האפליקציה כדי להציג את קיצורי הדרך שהגדרת לאפליקציה.
• גוררים קיצור דרך כדי להצמיד אותו למרכז האפליקציות של המכשיר.