管理捷徑

建立捷徑後，您可能必須在應用程式的生命週期中管理這些捷徑。舉例來說，您可以決定使用者透過捷徑完成特定動作的頻率，藉此將應用程式最佳化。在另一種情況下，您可以決定停用固定捷徑，避免應用程式執行過時或缺少的動作。本導覽將說明上述以及其他數種用於管理捷徑的常見方式。

捷徑行為

下列各節包含捷徑行為的一般資訊，包括瀏覽權限、顯示順序和排名。

捷徑瀏覽權限

重要安全性注意事項：所有捷徑資訊均儲存在憑證加密的儲存空間，因此，除非使用者解鎖裝置，否則應用程式無法存取使用者的捷徑。

當使用者執行特定手勢或語音指令時，靜態捷徑和動態捷徑會顯示在支援的啟動器或助理中。在支援的啟動器上，手勢是長按應用程式的啟動器圖示，但其他啟動器應用程式的實際手勢可能會有所不同。透過 Google 助理，捷徑可能會顯示在 Google 助理中，或是透過使用者語音指令啟動。

LauncherApps 類別提供讓啟動器應用程式存取捷徑的 API。

由於固定捷徑會顯示在啟動器中，因此固定捷徑一律會顯示。只有在下列情況下，系統才會將固定捷徑從啟動器中移除：

  • 使用者移除捷徑。
  • 已解除安裝與捷徑相關聯的應用程式。
  • 使用者依序前往「設定」>「應用程式與通知」，並選取應用程式，然後按下「儲存空間」>「清除儲存空間」，藉此清除應用程式資料。

捷徑顯示順序

啟動器顯示應用程式捷徑時，應按照下列順序：

  1. 靜態捷徑： isDeclaredInManifest() 方法傳回 true 的捷徑。
  2. 動態捷徑： ShortcutInfo.isDynamic() 方法傳回 true 的捷徑。

在這兩種捷徑類型 (靜態和動態) 中，捷徑會根據 ShortcutInfo.getRank() 的遞增「排名」排序。Google 助理在向使用者顯示內容比對相關捷徑時，也會將捷徑排名納入考量。

排名是非負的連續整數。呼叫 updateShortcuts(Context, List)、 addDynamicShortcuts(Context, List) 或 setDynamicShortcuts(Context, List) 時，您可以更新現有捷徑的排序。

注意：排名會自動調整，因此每個類型的捷徑 (靜態或動態) 都不會重複。舉例來說，假設有三個動態捷徑排名為 0、1 和 2，那麼新增另一個排名為 1 的動態捷徑，表示要求將此捷徑放在第二個位置。也就是說，第三和第四個捷徑更接近捷徑清單底部，而排名會分別變更至 2 和 3。

管理多個意圖和活動

如果您希望應用程式在使用者啟用捷徑時執行多項作業，可以設定讓應用程式觸發連續的活動。視捷徑的類型而定，您可以指派多個意圖、從活動開始其他活動或設定意圖旗標，以完成此動作。

指派多個意圖

使用 ShortcutInfoCompat.Builder 建立捷徑時，您可以使用 setIntents() 而不是 setIntent()。藉由呼叫 setIntents()，當使用者選取捷徑時，您可以在應用程式中啟動多項活動，並將最後一個活動除外的全部活動放在返回堆疊的清單中。如果使用者之後決定按下裝置的返回按鈕，就會看到您的應用程式中的另一個活動，而不是返回裝置的啟動器。

注意：當使用者選取捷徑，然後按下返回鍵時，您的應用程式就會啟動資源檔案中第二個至最後一個意圖相對應的活動。使用者再次按下返回按鈕時，此行為模式會繼續執行，直到使用者清除捷徑建立的返回堆疊為止。當使用者下次按下返回按鈕時，系統會將其導回啟動器。

開始其他活動

靜態捷徑不得使用自訂意圖旗標。靜態捷徑的第一個意圖會一律設定 Intent.FLAG_ACTIVITY_NEW_TASK 和 Intent.FLAG_ACTIVITY_CLEAR_TASK。換句話說，在應用程式執行期間，一旦啟動靜態捷徑，您應用程式中的所有現有活動都會刪除。如果不想這麼做，可以使用「Trampoline 活動」，或是在 Activity.onCreate(Bundle) 中開始另一個活動的隱藏活動，然後呼叫 Activity.finish()：

  1. 在 AndroidManifest.xml 檔案中，Trampoline 活動應包含屬性指派 android:taskAffinity=""。
  2. 在捷徑資源檔案中，靜態捷徑中的意圖應參照 Trampoline 活動。

如要進一步瞭解 Trampoline 活動，請參閱開始其他活動。

設定意圖旗標

您可以使用任何一組 Intent 旗標發布動態捷徑。建議您與其他旗標一併指定 Intent.FLAG_ACTIVITY_CLEAR_TASK。否則，如果您在應用程式執行期間嘗試開啟其他工作，目標活動可能無法顯示。

如要進一步瞭解工作和意圖旗標，請參閱工作和返回堆疊指南。

更新捷徑

每個應用程式啟動器圖示可以包含的靜態和動態捷徑數目上限由 getMaxShortcutCountPerActivity() 指定。然而，應用程式可建立的固定捷徑數量並無限制。

將動態捷徑固定後，即使發布者將動態捷徑移除，已固定的捷徑仍會顯示並啟動。這可讓應用程式擁有的捷徑數目超過 getMaxShortcutCountPerActivity()。

舉例來說，假設 getMaxShortcutCountPerActivity() 是四：

  1. 即時通訊應用程式會發布四個動態捷徑，代表最近的四個對話 (c1、c2、c3、c4)。
  2. 使用者固定這四個捷徑。

  3. 後來，使用者又開啟了三個其他對話 (c5、c6 和 c7)，因此發布者應用程式會重新發布動態捷徑。新的動態捷徑清單如下：c4、c5、c6、c7。

    應用程式無法顯示超過四個動態捷徑，因此必須移除 c1、c2 和 c3。不過，c1、c2 和 c3 仍是固定捷徑，可供使用者存取並啟動。

    使用者現在可以存取共七個連結到發布者應用程式中活動的捷徑，這是因為捷徑總數同時包含捷徑數量上限和三個固定捷徑。

  4. 應用程式可透過 updateShortcuts(Context, List) 更新現有七個捷徑中的「任一個」。舉例來說，您可以在即時通訊對象的圖示有所變更時，更新這組捷徑。
  5. addDynamicShortcuts(Context, List) 和 setDynamicShortcuts(Context, List) 方法也可用來更新相同 ID 的現有捷徑。不過，這些更新無法用於更新非動態、固定的捷徑，因為這兩種方法都會試圖將指定的捷徑清單轉換成動態捷徑。

在 Google 助理等小幫手應用程式上，可推送顯示的捷徑數目沒有上限。使用 ShortcutManagerCompat Jetpack 資料庫的 pushDynamicShortcut() 方法建立及更新捷徑，以用於小幫手應用程式。此外，您必須在應用程式中新增 Google 捷徑整合資料庫，動態連結才能在 Google 助理中顯示。

如要進一步瞭解應用程式捷徑的相關指南 (包括更新捷徑)，請參閱最佳做法。

處理系統語言代碼的變更

應用程式收到 Intent.ACTION_LOCALE_CHANGED 廣播時，應更新動態和固定的捷徑，以表示系統語言代碼已變更。

追蹤捷徑使用情形

啟動器會檢查捷徑的活動記錄，藉此判斷靜態和動態捷徑應該顯示的情況。當下列任一事件發生時，針對靜態捷徑，您可以呼叫 reportShortcutUsed() 方法並傳送捷徑的 ID，藉此追蹤使用者在應用程式中完成特定動作的時間：

  • 使用者選取含有指定 ID 的捷徑。
  • 使用者會在應用程式中手動完成對應至相同捷徑的動作。

您的應用程式會呼叫 pushDynamicShortcut() 方法，並在發生相關事件時傳送捷徑 ID，藉此追蹤動態捷徑的使用情形。如果搭配這種方法推送動態捷徑，就能讓 Google 助理等小幫手應用程式向使用者建議相關的捷徑。由於 pushDynamicShortcut() 方法會在呼叫時回報使用情形，因此不應呼叫同一個捷徑的 reportShortcutUsed() 方法。

注意：您必須使用 Google 捷徑整合資料庫，才能讓應用程式推送的動態連結顯示在 Google 助理等 Google 途徑。將此資料庫新增至應用程式後，Google 助理就能擷取您的動態連結，並透過小幫手應用程式向使用者建議這些連結。

停用捷徑

由於您的應用程式及其使用者可將捷徑固定至裝置啟動器，因此這些固定的捷徑可能會將使用者導向應用程式中過時或不再執行的動作。在這種情況下，您可以呼叫 disableShortcuts() 來停用您不想讓使用者選取的捷徑，此指令會從靜態和動態捷徑清單中移除指定的捷徑，並停用這些捷徑的任何固定副本。您也可以使用此方法的超載版本，接受 CharSequence 做為自訂錯誤訊息。當使用者嘗試啟動任何已停用的捷徑時，系統便會顯示這則錯誤訊息。

注意：更新應用程式時，如果您移除應用程式的部分靜態捷徑，系統會自動停用這些捷徑。

頻率限制

使用 setDynamicShortcuts()、 addDynamicShortcuts() 或 updateShortcuts() 方法時，請記住，您可能只能在「背景應用程式」中呼叫這些方法數次，也就是當下在前景中沒有活動或服務的應用程式。呼叫這些方法的特定次數限制稱為「頻率限制」。這項功能是用於避免 ShortcutManagerCompat 過度使用裝置資源。

啟用頻率限制時， isRateLimitingActive() 會傳回 true。不過，在某些事件下，頻率限制會重設，因此即使是背景應用程式，也可以呼叫 ShortcutManager 方法，直到頻率限制再次達到上限為止。這類事件包括：

  • 應用程式移至前景。
  • 系統語言代碼有所變更。
  • 使用者在通知中執行內嵌回覆動作。

如果在開發或測試期間遇到頻率限制，您可以在裝置設定中選取「開發人員選項」>「重設 ShortcutManager 頻率限制」，或是在 adb 中輸入下列指令：

$ adb shell cmd shortcut reset-throttling [ --user your-user-id ]

備份與還原

您可以在應用程式資訊清單檔案中加入 android:allowBackup="true" 屬性指派設定，藉此允許使用者在變更裝置時執行備份與還原作業。如果您允許使用備份與還原功能，請注意應用程式捷徑的下列要點：

  • 靜態捷徑會自動重新發布，但使用者必須在新的裝置上重新安裝應用程式。
  • 動態捷徑無法備份，因此您必須在應用程式中加入邏輯，當使用者透過新裝置開啟應用程式時，再重新發布應用程式。
  • 固定捷徑會自動還原到裝置的啟動器，但系統並不會備份與固定捷徑相關的圖示。因此，您應將固定的捷徑圖片儲存在應用程式中，以便在新裝置上輕鬆還原。

下列程式碼片段說明如何還原應用程式的動態捷徑，以及如何檢查應用程式的固定捷徑是否保持不變：

Kotlin

class MyMainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.dynamicShortcuts.size == 0) {
            // Application restored. Need to re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.pinnedShortcuts.size > 0) {
                // Pinned shortcuts have been restored. Use
                // updateShortcuts() to make sure they contain
                // up-to-date information.
            }

        }
    }
    // ...
}

Java

public class MainActivity extends Activity {
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        if (ShortcutManagerCompat.getDynamicShortcuts().size() == 0) {
            // Application restored. Need to re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts().size() > 0) {
                // Pinned shortcuts have been restored. Use
                // updateShortcuts() to make sure they contain
                // up-to-date information.
            }
        }
    }
    // ...
}

其他資源

Android AppShortcuts 範例會進一步示範如何使用本頁涵蓋的工作流程。