管理捷徑

建立捷徑後,您可能需要在應用程式的生命週期中管理這些捷徑。舉例來說,您可以決定使用者多常使用捷徑完成特定動作,來最佳化應用程式。在另一種情況下,您可以決定停用固定捷徑,以免應用程式執行過時或缺少的動作。對於對話中參照的捷徑,建議您追蹤使用情形,提供改善捷徑排名的信號。

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

捷徑行為

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

捷徑瀏覽權限

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

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

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

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

共用目標是動態捷徑的子集,會顯示在 Android 分享工作表的直接分享列中。

Android Sharesheet 的螢幕截圖
圖 1:Android Sharesheet。直接分享目標會顯示在第一列,接著是排名的應用程式,接著是應用程式清單。

捷徑顯示順序

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

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

在每個捷徑類型 (靜態和動態) 中,捷徑的排序方式會根據 ShortcutInfo.getRank 以遞增「排名」排序。Google 助理在決定要向使用者顯示的關聯捷徑時,也會將捷徑排名納入考量。

排名是非負的連續整數。靜態捷徑會依照在 shortcuts.xml 檔案中顯示的順序依先後順序排序。針對動態捷徑,您可以在呼叫 updateShortcuts(Context, List)addDynamicShortcuts(Context, List)pushDynamicShortcut(Context, ShortcutInfoCompat)setDynamicShortcuts(Context, List) 時更新現有捷徑的排名。

共用目標的順序取決於多項因素,包括過去的使用者記錄、回訪率、頻率、排名提示、應用程式使用,以及針對與共用捷徑關聯的對話設定的優先順序。透過 Share Shortcuts API 建立的共用目標,會優先於由 ChooserTargetService (Android 11 中淘汰) 產生的共用目標。在 Android 12 以上版本中,已淘汰 ChooserTargetService 產生的共用目標將不再顯示於分享工作表中。

多數啟動器最多可以顯示四個捷徑。對於已定義的靜態捷徑和動態捷徑組合,啟動器會顯示最多兩個靜態捷徑和兩個動態捷徑。舉例來說,如果您定義了四個靜態捷徑,並透過程式輔助方式建立三個動態捷徑,啟動器會顯示前兩個靜態捷徑,以及兩個排名最高的動態捷徑。

管理多個意圖和活動

如果您希望應用程式在使用者啟用捷徑時執行多項作業,可以設定捷徑以觸發連續活動。您可以按照捷徑的類型指派多個意圖、從另一個活動啟動,或是設定意圖標記來達到這個目標。

指派多個意圖

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

開始其他活動

靜態捷徑無法使用自訂意圖旗標。靜態捷徑的第一個意圖一律具有 Intent.FLAG_ACTIVITY_NEW_TASKIntent.FLAG_ACTIVITY_CLEAR_TASK set,這表示當應用程式執行時,應用程式中的所有現有活動都會在啟動靜態捷徑時刪除。如果您不希望這項行為,可以在 Activity.onCreate(Bundle) 呼叫 Activity.finish()Activity.onCreate(Bundle) 中使用「Trampoline 活動」,這是會啟動另一個活動的隱形活動:

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

如要進一步瞭解 Trampoline 活動,請參閱「從另一個活動啟動一項活動」。

設定意圖旗標

您可以使用任意組合的 Intent 旗標發布動態捷徑。建議您一併指定 Intent.FLAG_ACTIVITY_CLEAR_TASK 和其他標記。否則,如果您在應用程式執行期間嘗試啟動其他工作,目標活動可能不會顯示。

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

更新捷徑

每個應用程式的啟動器圖示最多可包含一些靜態和動態捷徑,且該快速鍵需等於 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 捷徑整合程式庫,讓動態連結顯示在 Google 助理上。

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

處理系統語言代碼的變更

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

追蹤捷徑使用情形

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

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

應用程式會呼叫 pushDynamicShortcut() 方法,並在發生相關事件時將捷徑 ID 傳遞給該方法,藉此追蹤動態捷徑的使用情形。透過這個方法推送動態捷徑,可讓 Google 助理等 Google 助理應用程式向使用者建議相關的快速鍵。由於 pushDynamicShortcut() 方法會在呼叫時回報用量,因此請勿針對相同的捷徑呼叫 reportShortcutUsed() 方法。

對於對話相關捷徑,請務必追蹤傳出和傳入訊息的使用情形。詳情請參閱人員和對話的最佳做法

停用捷徑

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

頻率限制

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

啟用頻率限制時,isRateLimitingActive() 會傳回 true。不過,在特定事件期間會重設頻率限制,因此即使是背景應用程式,也能呼叫 ShortcutManager 方法,直到再次達到頻率限制為止。這些事件包括:

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

如果您在開發或測試期間遇到頻率限制,可以在裝置設定中依序選取「Developer Options」>「Reset ShortcutManager rate-limiting」,或是在 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. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.pinnedShortcuts.size > 0) {
                // Pinned shortcuts are 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. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts().size() > 0) {
                // Pinned shortcuts are restored. Use pdateShortcuts() to make
                // sure they contain up-to-date information.
            }
        }
    }
    // ...
}