管理捷徑

建立捷徑後，您可能必須在應用程式的生命週期中管理這些捷徑。舉例來說，您可以決定使用者透過捷徑完成特定動作的頻率，藉此將應用程式最佳化。在另一種情況下，您可以決定停用固定捷徑，避免應用程式執行過時或缺少的動作。如果對話中提及快速鍵，您可能需要追蹤使用情況，提供有助於提升快速鍵排名的信號。

本頁將說明上述以及其他數種用於管理捷徑的常見方式。

捷徑行為

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

捷徑瀏覽權限

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

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

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

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

分享目標是動態快速鍵的子集，會顯示在 Android 分享功能表的直接分享列中。

捷徑顯示順序

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

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

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

排名是非負的連續整數。靜態快速鍵會依據在 shortcuts.xml 檔案中的顯示順序，從第一個到最後一個排序。如果是動態捷徑，呼叫 updateShortcuts(Context, List)、addDynamicShortcuts(Context, List)、pushDynamicShortcut(Context, ShortcutInfoCompat) 或 setDynamicShortcuts(Context, List) 時，可以更新現有捷徑的排序。

分享目標的排序依據包括使用者過去的記錄、近期活動、頻率、排名提示、應用程式使用情形，以及與分享捷徑相關聯的對話設定優先順序。使用 Sharing Shortcuts API 建立的分享目標，優先於 Android 11 中已淘汰的 ChooserTargetService 產生的分享目標。在 Android 12 以上版本中，系統不會再於分享功能表顯示由已淘汰的 ChooserTargetService 產生的分享目標。

大多數啟動器最多可顯示四個捷徑。無論定義的靜態和動態捷徑組合為何，啟動器最多只會顯示兩個靜態捷徑和兩個動態捷徑。舉例來說，如果您定義四個靜態捷徑，並以程式輔助方式建立三個動態捷徑，啟動器會顯示前兩個靜態捷徑，以及排名最高的兩個動態捷徑。

管理多個意圖和活動

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

開始其他活動

靜態捷徑不得使用自訂意圖旗標。靜態捷徑的第一個意圖一律會設定 Intent.FLAG_ACTIVITY_NEW_TASK 和 Intent.FLAG_ACTIVITY_CLEAR_TASK。換句話說，在應用程式執行期間，一旦啟動靜態捷徑，應用程式中的所有現有活動都會刪除。如要避免這種情況，可以使用 Trampoline 活動 (啟動其他活動的隱藏活動)，方法是在啟動區塊或 onCreate 內呼叫 finish，然後再設定 Compose 內容：

1. 在 AndroidManifest.xml file 中，將屬性指派 android:taskAffinity="" 納入 Trampoline 活動。

2. 在捷徑資源檔案中，參照靜態捷徑內意圖中的 Trampoline 活動。

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

設定意圖旗標

您可以使用任何一組 Intent 旗標發布動態捷徑。最好在快速指令的意圖中指定 Intent.FLAG_ACTIVITY_SINGLE_TOP 和 Intent.FLAG_ACTIVITY_CLEAR_TOP 的組合。這樣一來，如果 ComponentActivity 已處於啟用狀態，系統就會將其帶到前景並重複使用，不會毀損，讓單一活動架構透過 onNewIntent() 順利處理捷徑事件。

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

更新捷徑

每個應用程式啟動器圖示最多可包含的靜態和動態捷徑數目總和，等於 getMaxShortcutCountPerActivity 傳回的值。應用程式可建立的固定捷徑數量並無限制。

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

請參考以下範例，假設 getMaxShortcutCountPerActivity 傳回的值為 4：

1. 即時通訊應用程式會發布四個動態捷徑，代表最近的四個對話：c1、c2、c3 和 c4。
2. 使用者固定這四個捷徑。
3. 後來，使用者又開啟了三個其他對話：c5、c6 和 c7。發布者應用程式會重新發布動態捷徑。新的動態捷徑清單如下：c4、c5、c6 和 c7。

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

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

1. 應用程式可透過 updateShortcuts(Context, List) 更新現有七個捷徑中的任一個。舉例來說，您可以在即時通訊對象的圖示有所變更時，更新這組捷徑。
2. 您可以使用 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 方法。

如果是對話相關的快速鍵，請務必追蹤外寄和內送訊息的使用情況。詳情請參閱「人員和對話的最佳做法」。

停用捷徑

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

頻率限制

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

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

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

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

$ adb shell cmd shortcut reset-throttling [ --user <var>your-user-id</var> ]

備份與還原

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

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

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

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.getDynamicShortcuts(this).isEmpty()) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts(this).isNotEmpty()) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }

        }
    }
    // ...
}