App 快捷方式——管理快捷方式

原文連結

目錄

快捷方式的行為

快捷方式可見性

快捷方式顯示順序

管理多個 intents 和 activities

配置設定多個 intents

從另一個 activity 開啟一個 activity

設定 intent flags

更新快捷方式

處理系統區域設定更改

跟蹤快捷方式用法

禁用快捷方式

速率限制

備份還原

其他資源

建立快捷方式後，您可能需要在應用的生命周期内管理它們。 例如，您可能希望通過确定使用者使用快捷方式完成特定操作的頻率來優化您的應用。 在另一種情況下，您可能決定禁用固定快捷方式，以防止您的應用執行過期或丢失的操作。 本指南介紹了管理快捷方式的這些和其他幾種常用方法。

快捷方式的行為

以下部分包含有關快捷方式行為的一般資訊，包括可見性，顯示順序和排名。

快捷方式可見性

重要安全說明：所有快捷方式資訊都存儲在憑據加密存儲中，是以您的應用在解鎖裝置之前無法通路使用者的快捷方式。

當使用者執行特定手勢時，靜态快捷方式和動态快捷方式将顯示在受支援的啟動器中。 在目前支援的啟動器上，手勢是長按應用程式的啟動器圖示，但實際手勢可能與其他啟動器應用程式不同。

LauncherApps

 類為啟動器應用程式提供API以通路快捷方式。

由于固定快捷方式出現在啟動器本身，是以它們始終可見。 僅在以下情況下才會從啟動器中删除固定的快捷方式：

• 使用者将其删除。
• 與快捷方式關聯的應用程式已解除安裝。
• 使用者通過轉到設定>應用和通知，選擇應用，然後按存儲>清除存儲來清除應用的資料。

快捷方式顯示順序

當啟動器顯示應用程式的快捷方式時，它們應按以下順序顯示：

1. 靜态快捷方式： 

   isDeclaredInManifest()

    方法傳回 

   true

    的快捷方式。
2. 動态快捷方式： 

   ShortcutInfo.isDynamic()

    方法傳回 

   true

    的快捷方式。

在每種快捷方式類型（靜态和動态）中，快捷方式按照 

ShortcutInfo.getRank()

 遞增排名的順序排序。

排名是非負的連續整數。 您可以在調用

updateShortcuts(List)

， 

addDynamicShortcuts(List)

或 

setDynamicShortcuts(List)

.時更新現有快捷方式的排名。

注意：排名是自動調整的，是以它們對于每種類型的快捷方式（靜态或動态）都是唯一的。 例如，如果有三個具有排名0,1和2的動态快捷方式，則添加另一個排名為1的動态快捷方式表示将此快捷方式放在第二個位置的請求。 作為響應，第三和第四個快捷方式移動到快捷方式清單的底部，其排名分别變為2和3。

管理多個 intents 和 activities

如果您希望應用在使用者激活快捷方式時執行多項操作，則可以将其配置為觸發連續的 activities。 您可以通過配置設定多個 intents、從另一個 activity 開啟一個 activity 或者設定 intent flags 來實作此目的，具體取決于快捷方式的類型。

配置設定多個 intents

使用 

ShortcutInfo.Builder

 建立快捷方式時，可以使用 

setIntents()

 而不是 

setIntent()

。 通過調用 

setIntents()

，您可以在使用者選擇快捷方式時在應用程式中啟動多個 activities，将除清單中最後一個 activity 之外的所有 activities 放在傳回棧上。 如果使用者随後決定按裝置的傳回按鈕，他們将在您的應用中看到另一個 activity，而不是傳回裝置的啟動器。

注意：當使用者選擇快捷方式然後按後退鍵時，您的應用程式将啟動與資源檔案中列出的快捷方式倒數第二個 intent 相對應的 activity。 重複按下後退按鈕後，此行為模式繼續，直到使用者清除快捷方式建立的傳回棧。 當使用者下一次按下後退按鈕時，系統會将它們導航回啟動器。

從另一個 activity 開啟一個 activity

靜态快捷方式不能具有自定義 intent flags。 靜态快捷方式的第一個意圖始終設定為 

Intent.FLAG_ACTIVITY_NEW_TASK

 和 

Intent.FLAG_ACTIVITY_CLEAR_TASK

。 這意味着，當應用程式已經運作時，啟動靜态快捷方式時，應用程式中的所有現有 activities 都将被銷毀。 如果不希望出現這種情況，可以使用 , trampoline activity，或者在 

Activity.onCreate(Bundle)

中啟動另一個 activity 的不可見 activity，然後調用 

Activity.finish()

：

1. 在 

   AndroidManifest.xml

    檔案中，trampoline activity 應該包含屬性指派 

   android:taskAffinity=""

   。
2. 在快捷方式資源檔案中，靜态快捷方式中的 intent 應引用 trampoline activity。

有關 trampoline activities 的更多資訊，請閱讀 Start one activity from another。

設定 intent flags

可以使用任何 

Intent

 flags 集釋出動态快捷方式。 您最好指定 

Intent.FLAG_ACTIVITY_CLEAR_TASK

 以及其他标志。 否則，如果您在應用程式運作時嘗試啟動其他任務，則可能不會顯示目标 activity。

要了解有關任務和 intent flags 的更多資訊，請閱讀任務和傳回棧指南。

更新快捷方式

每個應用程式的啟動器圖示最多可以包含 

getMaxShortcutCountPerActivity()

 個靜态和動态快捷方式組合。但是，應用程式可以建立的固定快捷方式數量沒有限制。

固定動态快捷方式時，即使釋出者将其作為動态快捷方式删除，固定的快捷方式仍然可見并可啟動。這允許應用程式擁有超過 

getMaxShortcutCountPerActivity()

 個快捷方式。

例如，假設 

getMaxShortcutCountPerActivity()

 為四：

1. 聊天應用程式釋出四個動态快捷方式，表示最近的四個對話 (c1, c2, c3, c4)。
2. 使用者固定所有四個快捷方式。

3. 之後，使用者又啟動了三個額外的對話（c5，c6 和 c7），是以釋出者應用程式會重新釋出其動态快捷方式。 新的動态快捷清單是：c4，c5，c6，c7。

   該應用程式必須删除 c1，c2 和 c3，因為它無法顯示四個以上的動态快捷方式。 但是，c1，c2 和 c3 仍然是使用者可以通路和啟動的固定快捷方式。

   使用者現在可以通路總共七個連結到釋出者應用程式中的 activities 的快捷方式。 這是因為總數包括最大快捷方式數和三個固定快捷方式。

4. 應用程式可以使用 

   updateShortcuts(List)

    來更新現有七個快捷方式中的任何一個。例如，當聊天夥伴的圖示發生變化時，您可能會更新這組快捷方式。

5. addDynamicShortcuts(List)

    和 

   setDynamicShortcuts(List)

    方法也可用于更新具有相同ID的現有快捷方式。 但是，它們不能用于更新非動态固定快捷方式，因為這兩種方法會嘗試将給定的快捷方式清單轉換為動态快捷方式。

要詳細了解我們的應用程式快捷方式指南，包括更新快捷方式，請閱讀最佳實踐。

處理系統區域設定更改

應用程式在收到 

Intent.ACTION_LOCALE_CHANGED

 廣播時應更新動态和固定快捷方式，表示系統區域設定已更改。

跟蹤快捷方式用法

要确定應出現靜态和動态快捷方式的情況，啟動器會檢查快捷方式的激活曆史記錄。 您可以通過調用 

reportShortcutUsed()

 方法并在發生以下任一事件時向其傳遞快捷方式的 ID，來跟蹤使用者何時在您的應用中完成特定操作：

• 使用者選擇具有給定 ID 的快捷方式。
• 在應用程式内，使用者手動完成與同一快捷方式對應的操作。

禁用快捷方式

由于應用程式及其使用者可以将快捷方式固定到裝置的啟動器，是以這些固定快捷方式可能會引導使用者執行應用程式中過期或不再存在的操作。要管理這種情況，您可以通過調用 

disableShortcuts()

來禁用不希望使用者選擇的快捷方式，這将從靜态和動态快捷方式清單中删除指定的快捷方式，并禁用這些快捷方式的任何固定副本。您還可以使用此方法的另一個重載版本，它接受一個字元序列作為自定義錯誤消息。當使用者試圖啟動任何已禁用的快捷方式時，就會出現該錯誤消息。

注意：如果在更新應用程式時删除了某些應用程式的靜态快捷方式，系統會自動禁用這些快捷方式。

速率限制

使用 

setDynamicShortcuts()

，

addDynamicShortcuts()

或 

updateShortcuts()

 方法時，請記住，您可能隻能在背景應用程式中調用這些方法特定的次數，這個應用程式目前在前台沒有任何 activities 或 services 。 可以調用這些方法的特定次數限制稱為速率限制。 此功能用于防止 

ShortcutManager

 過度消耗裝置資源。

當速率限制激活時，

isRateLimitingActive()

 傳回 true。但是，在某些事件中會重置速率限制，是以即使背景應用程式也可以調用 

ShortcutManager

 方法，直到再次達到速率限制。這些事件包括：

• 一個應用程式來到前台。
• 系統區域設定更改。
• 使用者對通知執行 inline reply 操作。

如果在開發或測試期間遇到速率限制，可以從裝置的設定中選擇開發人員選項>重置ShortcutManager速率限制，或者您可以在 

adb

 中輸入以下指令：

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

備份還原

通過在應用程式的清單檔案中包含 

android:allowBackup="true"

 屬性配置設定，您可以允許使用者在更改裝置時對應用程式執行備份和還原操作。 如果您允許備份和還原，請記住以下有關應用程式快捷方式的要點：

• 靜态快捷方式會自動重新釋出，但隻有使用者在新裝置上重新安裝應用程式後才能重新釋出。
• 不會備份動态快捷方式，是以您必須在應用中包含邏輯，以便在使用者在新裝置上打開您的應用時重新釋出它們。
• 固定快捷方式會自動恢複到裝置的啟動器，但系統不會備份與固定快捷方式關聯的圖示。 是以，您應該在應用中儲存固定快捷方式的圖像，以便在新裝置上輕松恢複它們。

以下代碼段顯示了如何最好地恢複應用的動态快捷方式，以及如何檢查應用的固定快捷方式是否已保留：

class MyMainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val shortcutManager = getSystemService(ShortcutManager::class.java)

        if (shortcutManager!!.dynamicShortcuts.size == 0) {
            // 應用程式已還原。需要重新釋出動态快捷方式。
            if (shortcutManager.pinnedShortcuts.size > 0) {
                // 已還原固定的快捷方式。
                // 使用 updateShortcuts() 確定它們包含最新資訊。
            }

        }
    }
    // ...
}
           

其他資源

Android AppShortcuts 示例進一步示範了此頁面上涵蓋的工作流程的使用。