意圖和意圖篩選器

Intent 是一種訊息物件，可用於向其他應用程式元件要求動作。雖然意圖能以多種方式促進元件之間的通訊，但有三種基本用途：

  • 啟動活動

    Activity 代表應用程式中的單一畫面。您可以將 Intent 傳遞至 startActivity()，啟動 Activity 的新例項。Intent 描述要啟動的活動，並攜帶任何必要資料。

    如要在活動結束時接收結果，請呼叫 startActivityForResult()。活動會在 onActivityResult() 回呼中，以獨立 Intent 物件的形式接收結果。詳情請參閱「活動」指南。

  • 啟動服務

    Service 是在背景執行作業的元件，沒有使用者介面。在 Android 5.0 (API 級別 21) 以上版本中，您可以使用 JobScheduler 啟動服務。如要進一步瞭解 JobScheduler，請參閱其API-reference documentation。

    如果是 Android 5.0 (API 級別 21) 之前的版本，您可以使用 Service 類別的方法啟動服務。您可以將 Intent 傳遞至 startService()，啟動服務來執行一次性作業 (例如下載檔案)。Intent 描述要啟動的服務，並攜帶任何必要資料。

    如果服務採用用戶端-伺服器介面設計，您可以將 Intent 傳遞至 bindService()，從其他元件繫結至服務。詳情請參閱服務指南。

  • 傳送廣播訊息

    廣播是任何應用程式都能接收的訊息。系統會針對系統事件傳送各種廣播，例如系統啟動或裝置開始充電時。您可以將 Intent 傳遞至 sendBroadcast() 或 sendOrderedBroadcast()，將廣播傳送至其他應用程式。

本頁其餘部分將說明意圖的運作方式和使用方法。如需相關資訊，請參閱「與其他應用程式互動」和「分享內容」。

意圖類型

意圖分為兩種類型：

  • 明確意圖：指定完整的 ComponentName，指出哪個應用程式的哪個元件會滿足意圖。您通常會使用明確意圖啟動自己應用程式中的元件，因為您知道要啟動的活動或服務類別名稱。舉例來說，您可能會在應用程式中啟動新活動來回應使用者動作，或啟動服務在背景下載檔案。
  • 「隱含意圖」不會指定特定元件，而是宣告要執行的一般動作，讓其他應用程式的元件處理。舉例來說，如果您想在地圖上向使用者顯示某個位置，可以使用隱含意圖，要求其他具備相關功能的應用程式在地圖上顯示指定位置。

圖 1 顯示啟動活動時如何使用意圖。當 Intent 物件明確指定特定活動元件時，系統會立即啟動該元件。

圖 1. 隱含意圖如何透過系統傳遞，以啟動其他活動：[1]「Activity A」建立含有動作說明的 Intent，並傳遞至 startActivity()。[2] Android 系統會搜尋所有應用程式，找出與意圖相符的意圖篩選器。找到相符項目時，[3] 系統會叫用相符活動 (活動 B) 的 onCreate() 方法，並將 Intent 傳遞給該方法，藉此啟動該活動。

使用隱含意圖時，Android 系統會比較意圖內容與裝置上其他應用程式資訊清單檔案中宣告的意圖篩選器，找出要啟動的適當元件。如果意圖與意圖篩選器相符，系統就會啟動該元件，並將 Intent 物件傳送給該元件。如果有多個相容的意圖篩選器，系統會顯示對話方塊，讓使用者選擇要使用的應用程式。

意圖篩選器是應用程式資訊清單檔案中的運算式，用於指定元件要接收的意圖類型。舉例來說，為活動宣告意圖篩選器後，其他應用程式就能直接透過特定類型的意圖啟動您的活動。同樣地，如果您「未」為活動宣告任何意圖篩選器，則只能透過明確意圖啟動該活動。

注意：為確保應用程式安全，啟動 Service 時請一律使用明確意圖，且不要為服務宣告意圖篩選器。使用隱含意圖啟動服務會危害安全性，因為您無法確定哪個服務會回應意圖，而使用者也無法查看哪個服務會啟動。自 Android 5.0 (API 級別 21) 起，如果您使用隱含意圖呼叫 bindService()，系統會擲回例外狀況。

建立意圖

Intent 物件包含 Android 系統用來判斷要啟動哪個元件的資訊 (例如應接收意圖的確切元件名稱或元件類別)，以及接收端元件用來正確執行動作的資訊 (例如要執行的動作和要處理的資料)。

Intent 包含的主要資訊如下：

元件名稱
要啟動的元件名稱。

這是選用項目，但也是讓意圖明確的重要資訊，也就是說，意圖應只傳送至由元件名稱定義的應用程式元件。如果沒有元件名稱，意圖就是「隱含」，系統會根據其他意圖資訊 (例如動作、資料和類別，如下所述)，決定應接收意圖的元件。如需在應用程式中啟動特定元件，請指定元件名稱。

注意：啟動 Service 時，請務必指定元件名稱。否則，您無法確定哪個服務會回應意圖，使用者也無法查看哪個服務會啟動。

Intent 的這個欄位是 ComponentName 物件，您可以使用目標元件的完整類別名稱 (包括應用程式的套件名稱，例如 com.example.ExampleActivity) 指定該物件。您可以使用 setComponent()、setClass()、setClassName() 或 Intent 建構函式設定元件名稱。

動作
指定要執行的一般動作 (例如 view 或 pick) 的字串。

如果是廣播意圖，則是指已發生並回報的動作。動作在很大程度上決定了意圖其餘部分的結構，尤其是資料和額外資訊中包含的資訊。

您可以指定自己的動作，供應用程式中的意圖使用 (或供其他應用程式叫用應用程式中的元件)，但通常會指定 Intent 類別或其他架構類別定義的動作常數。以下是啟動活動的一些常見動作：

ACTION_VIEW
當您有某些資訊可透過活動向使用者顯示時，例如在相片庫應用程式中查看相片，或在地圖應用程式中查看地址，請在含有 startActivity() 的意圖中使用這項動作。
ACTION_SEND
這也稱為「共用」意圖，當您有一些使用者可以透過其他應用程式 (例如電子郵件應用程式或社群媒體分享應用程式) 共用的資料時，應在意圖中搭配 startActivity() 使用。

如需更多定義一般動作的常數，請參閱 Intent 類別參考資料。其他動作則定義在 Android 架構的其他位置，例如 Settings，用於在系統的「設定」應用程式中開啟特定畫面。

您可以使用 setAction() 或 Intent 建構函式，指定意圖的動作。

如果您自行定義動作，請務必加入應用程式的套件名稱做為前置字元，如以下範例所示：

Kotlin

const val ACTION_TIMETRAVEL = "com.example.action.TIMETRAVEL"

Java

static final String ACTION_TIMETRAVEL = "com.example.action.TIMETRAVEL";
資料
URI (Uri 物件)，參照要處理的資料和/或該資料的 MIME 類型。提供的資料類型通常取決於意圖的動作。舉例來說，如果動作是 ACTION_EDIT，資料應包含要編輯的文件 URI。

建立意圖時，除了 URI 之外，通常也必須指定資料類型 (MIME 類型)。舉例來說，即使 URI 格式可能相似，但能夠顯示圖片的活動可能無法播放音訊檔案。指定資料的 MIME 類型，有助於 Android 系統找出最適合接收意圖的元件。不過，有時可以從 URI 推斷 MIME 類型，尤其是當資料是 content: URI 時。content: URI 表示資料位於裝置上，並由 ContentProvider 控制，因此系統可查看資料 MIME 類型。

如要只設定資料 URI，請呼叫 setData()。如要只設定 MIME 類型，請呼叫 setType()。如有需要，您可以使用 setDataAndType() 明確設定這兩者。

注意：如要同時設定 URI 和 MIME 類型，請「不要」呼叫 setData() 和 setType()，因為這兩者會使彼此的值失效。請一律使用 setDataAndType() 設定 URI 和 MIME 類型。

類別
字串，包含應處理意圖的元件種類相關額外資訊。意圖中可以放置任意數量的類別說明，但大多數意圖不需要類別。以下是幾個常見類別：
CATEGORY_BROWSABLE
目標活動允許網路瀏覽器啟動，以顯示連結參照的資料，例如圖片或電子郵件訊息。
CATEGORY_LAUNCHER
活動是工作的初始活動，且列在系統的應用程式啟動器中。

如需完整類別清單，請參閱 Intent 類別說明。

你可以使用 addCategory() 指定類別。

上述屬性 (元件名稱、動作、資料和類別) 代表意圖的定義特徵。Android 系統會讀取這些屬性，判斷應啟動哪個應用程式元件。不過，意圖可以攜帶額外資訊，但不會影響解析為應用程式元件的方式。意圖也可以提供下列資訊：

額外內容
鍵/值組合，用於攜帶完成要求動作所需的額外資訊。正如某些動作會使用特定類型的資料 URI，某些動作也會使用特定額外項目。

您可以使用各種 putExtra() 方法新增額外資料，每種方法都接受兩個參數：索引鍵名稱和值。您也可以建立包含所有額外資料的 Bundle 物件，然後使用 putExtras() 將 Bundle 插入 Intent。

舉例來說，建立意圖以使用 ACTION_SEND 傳送電子郵件時，您可以使用 EXTRA_EMAIL 鍵指定「收件者」，並使用 EXTRA_SUBJECT 鍵指定「主旨」。

Intent 類別會為標準化資料類型指定許多 EXTRA_* 常數。如需宣告自己的額外索引鍵 (用於應用程式接收的意圖)，請務必加入應用程式的套件名稱做為前置字元，如以下範例所示：

Kotlin

const val EXTRA_GIGAWATTS = "com.example.EXTRA_GIGAWATTS"

Java

static final String EXTRA_GIGAWATTS = "com.example.EXTRA_GIGAWATTS";

注意：傳送預期由其他應用程式接收的意圖時，請勿使用 Parcelable 或 Serializable 資料。如果應用程式嘗試存取 Bundle 物件中的資料，但無法存取 Parcelable 或序列化類別，系統就會引發 RuntimeException。

標記
旗標定義在 Intent 類別中，做為意圖的中繼資料。這些旗標可能會指示 Android 系統如何啟動活動 (例如活動應屬於哪個任務)，以及在啟動後如何處理活動 (例如是否屬於最近活動清單)。

詳情請參閱 setFlags() 方法。

明確意圖範例

明確意圖用於啟動特定應用程式元件，例如應用程式中的特定活動或服務。如要建立明確意圖，請定義 Intent 物件的元件名稱，所有其他意圖屬性均為選用。

舉例來說，如果您在應用程式中建構名為 DownloadService 的服務，用於從網路下載檔案，則可使用下列程式碼啟動該服務：

Kotlin

// Executed in an Activity, so 'this' is the Context
// The fileUrl is a string URL, such as "http://www.example.com/image.png"
val downloadIntent = Intent(this, DownloadService::class.java).apply {
    data = Uri.parse(fileUrl)
}
startService(downloadIntent)

Java

// Executed in an Activity, so 'this' is the Context
// The fileUrl is a string URL, such as "http://www.example.com/image.png"
Intent downloadIntent = new Intent(this, DownloadService.class);
downloadIntent.setData(Uri.parse(fileUrl));
startService(downloadIntent);

Intent(Context, Class) 建構函式會為應用程式 Context 和元件提供 Class 物件。因此，這項意圖會明確啟動應用程式中的 DownloadService 類別。

如要進一步瞭解如何建構及啟動服務，請參閱「服務」指南。

隱含意圖範例

隱含意圖會指定一項動作，可叫用裝置上任何能執行該動作的應用程式。如果您的應用程式無法執行動作，但其他應用程式可能可以，且您希望使用者選擇要使用的應用程式，則適合使用隱含意圖。

舉例來說，如果您希望使用者與其他人分享內容，請使用 ACTION_SEND 動作建立意圖，並新增指定要分享內容的額外項目。當您使用該意圖呼叫 startActivity() 時，使用者可以選擇要透過哪個應用程式分享內容。

Kotlin

// Create the text message with a string.
val sendIntent = Intent().apply {
    action = Intent.ACTION_SEND
    putExtra(Intent.EXTRA_TEXT, textMessage)
    type = "text/plain"
}

// Try to invoke the intent.
try {
    startActivity(sendIntent)
} catch (e: ActivityNotFoundException) {
    // Define what your app should do if no activity can handle the intent.
}

Java

// Create the text message with a string.
Intent sendIntent = new Intent();
sendIntent.setAction(Intent.ACTION_SEND);
sendIntent.putExtra(Intent.EXTRA_TEXT, textMessage);
sendIntent.setType("text/plain");

// Try to invoke the intent.
try {
    startActivity(sendIntent);
} catch (ActivityNotFoundException e) {
    // Define what your app should do if no activity can handle the intent.
}

呼叫 startActivity() 時，系統會檢查所有已安裝的應用程式，判斷哪些應用程式可以處理這類意圖 (具有 ACTION_SEND 動作且包含「text/plain」資料的意圖)。如果只有一個應用程式可以處理，該應用程式會立即開啟並接收意圖。如果沒有其他應用程式可以處理，您的應用程式可以擷取發生的 ActivityNotFoundException。如果有多個活動接受意圖，系統會顯示對話方塊 (如圖 2 所示)，讓使用者選擇要使用的應用程式。

如要進一步瞭解如何啟動其他應用程式，請參閱將使用者導向其他應用程式指南。

圖 2. 選擇工具對話方塊。

強制顯示應用程式選擇工具

如果有多個應用程式回應您的隱含意圖，使用者可以選取要使用的應用程式，並將該應用程式設為該動作的預設選項。如果使用者通常想用同一款應用程式執行動作，例如可能只使用一個網路瀏覽器開啟網頁，那麼選取預設應用程式的功能就很實用。

不過，如果有多個應用程式可以回應意圖，且使用者可能每次都想使用不同的應用程式，則應明確顯示選擇器對話方塊。選擇工具對話方塊會要求使用者選取要用於該動作的應用程式 (使用者無法選取動作的預設應用程式)。舉例來說，當應用程式透過 ACTION_SEND 動作執行「分享」時，使用者可能會想根據目前情況使用其他應用程式分享，因此您應一律使用選擇器對話方塊，如圖 2 所示。

如要顯示選擇工具，請使用 createChooser() 建立 Intent，並傳送至 startActivity()，如以下範例所示。這個範例會顯示對話方塊，其中列出回應意圖的應用程式，該意圖會傳遞至 createChooser() 方法，並使用提供的文字做為對話方塊標題。

Kotlin

val sendIntent = Intent(Intent.ACTION_SEND)
...

// Always use string resources for UI text.
// This says something like "Share this photo with"
val title: String = resources.getString(R.string.chooser_title)
// Create intent to show the chooser dialog
val chooser: Intent = Intent.createChooser(sendIntent, title)

// Verify the original intent will resolve to at least one activity
if (sendIntent.resolveActivity(packageManager) != null) {
    startActivity(chooser)
}

Java

Intent sendIntent = new Intent(Intent.ACTION_SEND);
...

// Always use string resources for UI text.
// This says something like "Share this photo with"
String title = getResources().getString(R.string.chooser_title);
// Create intent to show the chooser dialog
Intent chooser = Intent.createChooser(sendIntent, title);

// Verify the original intent will resolve to at least one activity
if (sendIntent.resolveActivity(getPackageManager()) != null) {
    startActivity(chooser);
}

偵測不安全的意圖啟動

應用程式可能會啟動意圖，在應用程式內部的元件之間導覽，或代表其他應用程式執行動作。為提升平台安全性，Android 12 (API 級別 31) 以上版本提供偵錯功能，可在應用程式執行不安全的意圖啟動作業時發出警告。舉例來說，應用程式可能會不安全地啟動巢狀意圖，也就是在另一個意圖中做為額外項目傳遞的意圖。

如果應用程式同時執行下列兩項動作，系統會偵測到不安全的意圖啟動作業，並發生 StrictMode 違規事項：

  1. 應用程式將巢狀意圖從已傳遞意圖的額外項目中拆解出來。
  2. 應用程式立即使用該巢狀意圖啟動應用程式元件，例如將意圖傳遞至 startActivity()、startService() 或 bindService()。

如要進一步瞭解如何找出這種情況並修改應用程式，請參閱 Medium 上的 Android 巢狀意圖網誌文章。

檢查是否有不安全的意圖啟動

如要檢查應用程式中是否有不安全的意圖啟動，請在設定 VmPolicy 時呼叫 detectUnsafeIntentLaunch()，如以下程式碼片段所示。如果應用程式偵測到 StrictMode 違規，建議您停止執行應用程式，保護可能機密的資訊。

Kotlin

fun onCreate() {
    StrictMode.setVmPolicy(VmPolicy.Builder()
        // Other StrictMode checks that you've previously added.
        // ...
        .detectUnsafeIntentLaunch()
        .penaltyLog()
        // Consider also adding penaltyDeath()
        .build())
}

Java

protected void onCreate() {
    StrictMode.setVmPolicy(new VmPolicy.Builder()
        // Other StrictMode checks that you've previously added.
        // ...
        .detectUnsafeIntentLaunch()
        .penaltyLog()
        // Consider also adding penaltyDeath()
        .build());
}

以更負責任的方式使用意圖

為盡可能降低不安全意圖啟動和 StrictMode 違規的可能性，請遵循下列最佳做法。

請只複製意圖中的必要額外項目，並執行任何必要的清理和驗證。應用程式可能會將額外項目從一個意圖複製到另一個意圖，用於啟動新元件。當應用程式呼叫 putExtras(Intent) 或 putExtras(Bundle) 時，就會發生這種情況。如果應用程式執行上述任一作業，請僅複製接收元件預期的額外項目。如果另一個意圖 (接收副本) 啟動的元件未匯出，請先清理並驗證額外項目，再複製到啟動元件的意圖。

請勿不必要地匯出應用程式元件。舉例來說，如果您打算使用內部巢狀意圖啟動應用程式元件，請將該元件的 android:exported 屬性設為 false。

請使用 PendingIntent，而非巢狀意圖。這樣一來，當其他應用程式取消剖析包含 Intent 的 PendingIntent 時，其他應用程式就能使用您應用程式的身分啟動 PendingIntent。這項設定可讓其他應用程式安全地啟動您應用程式中的任何元件，包括未匯出的元件。

圖 2 顯示系統如何將控制權從您的 (用戶端) 應用程式傳遞至另一個 (服務) 應用程式，然後再傳回您的應用程式：

  1. 應用程式建立意圖，叫用另一個應用程式中的活動。在該意圖中，您新增 PendingIntent 物件做為額外項目。這個待處理意圖會叫用應用程式中的元件，但不會匯出該元件。
  2. 另一個應用程式收到應用程式的意圖後，會擷取巢狀 PendingIntent 物件。
  3. 另一個應用程式會叫用 PendingIntent 物件的 send() 方法。
  4. 將控制權交回應用程式後，系統會使用應用程式的背景資訊叫用待處理意圖。

圖 2. 使用巢狀待處理意圖時，應用程式間通訊的圖表。

接收隱含意圖

如要宣傳應用程式可接收的隱含意圖，請在資訊清單檔案中，使用 <intent-filter> 元素為每個應用程式元件宣告一或多個意圖篩選器。每個意圖篩選器都會根據意圖的動作、資料和類別，指定接受的意圖類型。只有在隱含意圖能通過其中一個意圖篩選器時，系統才會將該意圖傳送至應用程式元件。

注意：無論元件宣告任何意圖篩選器，明確意圖一律會傳送至目標。

應用程式元件應為可執行的每項不重複工作，分別宣告篩選器。舉例來說，相片庫應用程式中的某個活動可能有兩個篩選器：一個用於查看圖片，另一個用於編輯圖片。活動啟動時，會檢查 Intent，並根據 Intent 中的資訊決定行為 (例如是否顯示編輯器控制項)。

每個意圖篩選器都是由應用程式資訊清單檔案中的 <intent-filter> 元素定義，並巢狀結構於對應的應用程式元件 (例如 <activity> 元素) 中。

在每個包含 <intent-filter> 元素的應用程式元件中，明確設定 android:exported 的值。這項屬性會指出其他應用程式是否能存取該應用程式元件。在某些情況下，例如意圖篩選器包含 LAUNCHER 類別的活動，將這項屬性設為 true 會很有幫助。否則，建議將這項屬性設為 false。

警告：如果應用程式中的活動、服務或廣播接收器使用意圖篩選器，且未明確設定 android:exported 的值，則應用程式無法安裝在搭載 Android 12 以上版本的裝置上。

在 <intent-filter> 中，您可以使用下列一或多個元素，指定要接受的意圖類型：

<action>
在 name 屬性中宣告接受的意圖動作。這個值必須是動作的常值字串值，而非類別常數。
<data>
使用一或多個屬性指定資料 URI (scheme、host、port、path) 和 MIME 類型的各個面向，藉此宣告接受的資料類型。
<category>
在 name 屬性中宣告接受的意圖類別。這個值必須是動作的常值字串值，而非類別常數。

注意：如要接收隱含意圖，您必須在意圖篩選器中加入 CATEGORY_DEFAULT 類別。startActivity() 和 startActivityForResult() 方法會將所有意圖視為皆已宣告 CATEGORY_DEFAULT 類別。如果未在意圖篩選器中宣告這個類別，系統就不會將任何隱含意圖解析至您的活動。

舉例來說，以下活動宣告包含意圖篩選器，可在資料類型為文字時接收 ACTION_SEND 意圖：

<activity android:name="ShareActivity" android:exported="false">
    <intent-filter>
        <action android:name="android.intent.action.SEND"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:mimeType="text/plain"/>
    </intent-filter>
</activity>

您可以建立包含多個 <action>、<data> 或 <category> 執行個體的篩選器。如果這麼做，您必須確保元件能處理這些篩選條件元素的任何組合。

如要處理多種意圖，但僅限於動作、資料和類別類型的特定組合，則需要建立多個意圖篩選器。

系統會將意圖與三個元素逐一比較，藉此測試隱含意圖是否符合篩選條件。意圖必須通過所有三項測試，才能傳送至元件。如果其中一個條件不符，Android 系統就不會將意圖傳送至元件。不過，由於元件可能有多個意圖篩選器，因此未通過元件其中一個篩選器的意圖，可能會通過另一個篩選器。如要進一步瞭解系統如何解析意圖，請參閱下方的「意圖解析」一節。

注意： 使用意圖篩選器並非防止其他應用程式啟動元件的安全做法。雖然意圖篩選器會限制元件只能回應特定類型的隱含意圖，但如果開發人員決定元件名稱，其他應用程式仍有可能使用明確意圖啟動應用程式元件。如果只有您的應用程式才能啟動其中一個元件，請勿在資訊清單中宣告意圖篩選器。請改為將該元件的 exported 屬性設為 "false"。

同樣地，為避免不小心執行其他應用程式的 Service，請一律使用明確意圖啟動自己的服務。

注意： 您必須在資訊清單檔案中，為所有活動宣告意圖篩選器。 不過，您可以呼叫 registerReceiver()，動態註冊廣播接收器的篩選器。接著，您可以使用 unregisterReceiver() 取消註冊接收器。這樣一來，應用程式就能在執行期間，只在指定時間內監聽特定廣播。

篩選器示例

以下是社群分享應用程式資訊清單檔案的範例，示範部分意圖篩選器行為：

<activity android:name="MainActivity" android:exported="true">
    <!-- This activity is the main entry, should appear in app launcher -->
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

<activity android:name="ShareActivity" android:exported="false">
    <!-- This activity handles "SEND" actions with text data -->
    <intent-filter>
        <action android:name="android.intent.action.SEND"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:mimeType="text/plain"/>
    </intent-filter>
    <!-- This activity also handles "SEND" and "SEND_MULTIPLE" with media data -->
    <intent-filter>
        <action android:name="android.intent.action.SEND"/>
        <action android:name="android.intent.action.SEND_MULTIPLE"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:mimeType="application/vnd.google.panorama360+jpg"/>
        <data android:mimeType="image/*"/>
        <data android:mimeType="video/*"/>
    </intent-filter>
</activity>

第一個活動 MainActivity 是應用程式的主要進入點，也就是使用者一開始透過啟動器圖示啟動應用程式時開啟的活動：

  • ACTION_MAIN 動作表示這是主要進入點，且不預期任何意圖資料。
  • CATEGORY_LAUNCHER 類別表示這個活動的圖示應放在系統的應用程式啟動器中。如果 <activity> 元素未指定 icon 圖示，系統會使用 <application> 元素的圖示。

這兩者必須配對，活動才會顯示在應用程式啟動器中。

第二個活動 ShareActivity 旨在協助分享文字和媒體內容。雖然使用者可能會從 MainActivity 導覽至這項活動，但他們也可以直接從另一個應用程式進入 ShareActivity，該應用程式會發出與兩個意圖篩選器之一相符的隱含意圖。

注意：MIME 類型 application/vnd.google.panorama360+jpg 是一種特殊資料類型，用於指定全景相片，您可以使用 Google 全景 API 處理。

將意圖與其他應用程式的意圖篩選器配對

如果另一個應用程式指定 Android 13 (API 級別 33) 以上版本，則只有在您的意圖與該應用程式中 <intent-filter> 元素的動作和類別相符時，才能處理應用程式的意圖。如果系統找不到相符項目，就會擲回 ActivityNotFoundException。傳送端應用程式必須處理這個例外狀況。

同樣地，如果您將應用程式更新為指定 Android 13 以上版本，則只有在該意圖與應用程式宣告的 <intent-filter> 元素的動作和類別相符時，系統才會將來自外部應用程式的所有意圖傳送至應用程式的匯出元件。無論傳送應用程式的目標 SDK 版本為何，都會發生這種行為。

在下列情況下，系統不會強制執行意圖比對：

  • 意圖傳送至未宣告任何意圖篩選器的元件。
  • 來自同一個應用程式的意圖。
  • 源自系統的意圖，也就是從「系統 UID」(uid=1000) 傳送的意圖。系統應用程式包括 system_server 和將 android:sharedUserId 設為 android.uid.system 的應用程式。
  • 源自根目錄的意圖。

進一步瞭解意圖比對。

使用待處理意圖

PendingIntent 物件是 Intent 物件的包裝函式。PendingIntent 的主要用途是授予外部應用程式權限，讓其使用包含的 Intent，就像從應用程式自己的程序執行一樣。

待處理意圖的主要用途包括：

就像每個 Intent 物件都設計為由特定類型的應用程式元件 (Activity、Service 或 BroadcastReceiver) 處理一樣，建立 PendingIntent 時也必須考量相同因素。使用待處理意圖時，應用程式不會透過 startActivity() 等呼叫執行意圖。相反地，您必須在建立 PendingIntent 時，呼叫對應的建立工具方法，宣告預期的元件類型：

除非應用程式會從其他應用程式「接收」待處理意圖，否則上述建立 PendingIntent 的方法，可能就是您唯一需要使用的 PendingIntent 方法。

每個方法都會採用目前的應用程式 Context、要包裝的 Intent，以及一或多個指定意圖使用方式的旗標 (例如意圖是否可使用多次)。

如要進一步瞭解如何使用待處理意圖，請參閱各個用途的說明文件，例如通知和應用程式小工具 API 指南。

指定可變動性

如果應用程式指定 Android 12 以上版本，您必須為應用程式建立的每個 PendingIntent 物件指定可變動性。如要宣告指定的 PendingIntent 物件是可變動或不可變動，請分別使用 PendingIntent.FLAG_MUTABLE 或 PendingIntent.FLAG_IMMUTABLE 旗標。

如果應用程式嘗試建立 PendingIntent 物件，但未設定任何可變動性旗標，系統會擲回 IllegalArgumentException，並在 Logcat 中顯示下列訊息：

PACKAGE_NAME: Targeting S+ (version 31 and above) requires that one of \
FLAG_IMMUTABLE or FLAG_MUTABLE be specified when creating a PendingIntent.

Strongly consider using FLAG_IMMUTABLE, only use FLAG_MUTABLE if \
some functionality depends on the PendingIntent being mutable, e.g. if \
it needs to be used with inline replies or bubbles.

盡可能建立不可變動的待處理意圖

在大多數情況下，應用程式應建立不可變動的 PendingIntent 物件，如以下程式碼片段所示。如果 PendingIntent 物件不可變更，其他應用程式就無法修改意圖，調整叫用意圖的結果。

Kotlin

val pendingIntent = PendingIntent.getActivity(applicationContext,
        REQUEST_CODE, intent,
        /* flags */ PendingIntent.FLAG_IMMUTABLE)

Java

PendingIntent pendingIntent = PendingIntent.getActivity(getApplicationContext(),
        REQUEST_CODE, intent,
        /* flags */ PendingIntent.FLAG_IMMUTABLE);

不過，某些用途需要可變動的 PendingIntent 物件：

  • 支援通知中的直接回覆操作。直接回覆需要變更與回覆相關聯的 PendingIntent 物件中的剪輯資料。通常，您會將 FILL_IN_CLIP_DATA 做為旗標傳遞至 fillIn() 方法，藉此要求這項變更。
  • 使用 CarAppExtender 執行個體，將通知與 Android Auto 架構建立關聯。
  • 使用 PendingIntent 執行個體將對話置於對話框中。可變動的 PendingIntent 物件可讓系統套用正確的旗標，例如 FLAG_ACTIVITY_MULTIPLE_TASK 和 FLAG_ACTIVITY_NEW_DOCUMENT。
  • 呼叫 requestLocationUpdates() 或類似 API，要求裝置位置資訊。可變動的 PendingIntent 物件可讓系統新增代表位置生命週期事件的意圖額外項目。這類事件包括位置變更，以及供應商可供使用。
  • 使用 AlarmManager 排定鬧鐘。可變動的 PendingIntent 物件可讓系統新增 EXTRA_ALARM_COUNT 意圖額外項目。這個額外項目代表重複鬧鐘觸發的次數。透過包含這個額外項目，意圖可以準確通知應用程式是否多次觸發重複鬧鐘，例如裝置處於休眠狀態時。

如果應用程式建立可變動的 PendingIntent 物件，強烈建議您使用明確意圖，並填入 ComponentName。這樣一來，每當其他應用程式叫用 PendingIntent 並將控制權交回您的應用程式時，應用程式中的相同元件一律會啟動。

在待處理意圖中使用明確意圖

如要進一步定義其他應用程式如何使用您應用程式的待處理意圖，請一律將待處理意圖包裝在明確意圖中。為遵循這項最佳做法，請執行下列操作：

  1. 確認已設定基本意圖的動作、套件和元件欄位。

  2. 使用 Android 6.0 (API 級別 23) 新增的 FLAG_IMMUTABLE 建立待處理意圖。這個旗標可防止接收 PendingIntent 的應用程式填入未填入的屬性。如果應用程式的 minSdkVersion 為 22 以下，您可以使用下列程式碼，同時提供安全性和相容性：

    if (Build.VERSION.SDK_INT >= 23) {
  // Create a PendingIntent using FLAG_IMMUTABLE.
} else {
  // Existing code that creates a PendingIntent.
}

意圖解析

當系統收到啟動活動的隱含意圖時，會根據下列三個面向，將意圖與意圖篩選器進行比較，找出最適合該意圖的活動：

  • Action。
  • 資料 (URI 和資料類型)。
  • 類別。

以下各節說明如何根據應用程式資訊清單檔案中的意圖篩選器宣告，將意圖與適當的元件進行比對。

動作測試

如要指定接受的意圖動作，意圖篩選器可以宣告零或多個 <action> 元素，如以下範例所示：

<intent-filter>
    <action android:name="android.intent.action.EDIT" />
    <action android:name="android.intent.action.VIEW" />
    ...
</intent-filter>

如要通過這項篩選器，Intent 中指定的動作必須與篩選器中列出的其中一個動作相符。

如果篩選器未列出任何動作，意圖就沒有可比對的項目，因此所有意圖都無法通過測試。不過，如果 Intent 未指定動作，只要篩選器包含至少一個動作，就會通過測試。

類別測試

如要指定接受的意圖類別，意圖篩選器可以宣告零或多個 <category> 元素，如以下範例所示：

<intent-filter>
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    ...
</intent-filter>

意圖必須通過類別測試，也就是 Intent 中的每個類別都必須與篩選器中的類別相符。反之則不一定，意圖篩選器宣告的類別可能多於 Intent 中指定的類別，而 Intent 仍會通過。因此，無論篩選器中宣告哪些類別，不含類別的意圖一律會通過這項測試。

注意：Android 會自動將 CATEGORY_DEFAULT 類別套用至傳遞至 startActivity() 和 startActivityForResult() 的所有隱含意圖。如要讓活動接收隱含意圖，則必須在意圖篩選器中加入 "android.intent.category.DEFAULT" 類別，如前述 <intent-filter> 範例所示。

資料測試

如要指定接受的意圖資料，意圖篩選器可以宣告零或多個 <data> 元素，如以下範例所示：

<intent-filter>
    <data android:mimeType="video/mpeg" android:scheme="http" ... />
    <data android:mimeType="audio/mpeg" android:scheme="http" ... />
    ...
</intent-filter>

每個 <data> 元素都可以指定 URI 結構和資料類型 (MIME 媒體類型)。URI 的每個部分都是獨立屬性：scheme、host、port 和 path：

<scheme>://<host>:<port>/<path>

以下範例顯示這些屬性的可能值：

content://com.example.project:200/folder/subfolder/etc

在這個 URI 中，配置為 content，主機為 com.example.project，通訊埠為 200，路徑為 folder/subfolder/etc。

在 <data> 元素中，這些屬性都是選用的，但存在線性依附關係：

  • 如未指定配置，系統會忽略主機。
  • 如未指定主機，系統會忽略通訊埠。
  • 如果未指定配置和主機，系統會忽略路徑。

將意圖中的 URI 與篩選器中的 URI 規格進行比較時，系統只會與篩選器中包含的 URI 部分進行比較。例如：

  • 如果篩選器只指定配置，則所有具有該配置的 URI 都符合篩選器。
  • 如果篩選器指定配置和授權單位，但未指定路徑，則無論路徑為何，所有具有相同配置和授權單位的 URI 都會通過篩選器。
  • 如果篩選器指定配置、授權單位和路徑，則只有具有相同配置、授權單位和路徑的 URI 才能通過篩選器。

注意：路徑規格可以包含萬用字元星號 (*)，只需要部分符合路徑名稱即可。

資料測試會比較意圖中的 URI 和 MIME 類型，以及篩選器中指定的 URI 和 MIME 類型。規則如下：

  1. 如果意圖不含 URI 或 MIME 類型，只有在篩選器未指定任何 URI 或 MIME 類型時，才能通過測試。
  2. 如果意圖包含 URI，但沒有 MIME 類型 (無論是明確指定或可從 URI 推斷)，則只有在 URI 符合篩選器的 URI 格式，且篩選器同樣未指定 MIME 類型時，才能通過測試。
  3. 如果意圖包含 MIME 類型，但不含 URI，則只有在篩選器列出相同的 MIME 類型，且未指定 URI 格式時，才能通過測試。
  4. 如果意圖同時包含 URI 和 MIME 類型 (明確或可從 URI 推斷)，只有在該類型與篩選器中列出的類型相符時，才會通過測試的 MIME 類型部分。如果 URI 與篩選器中的 URI 相符，或具有 content: 或 file: URI，且篩選器未指定 URI，則會通過測試的 URI 部分。換句話說，如果元件的篩選器「僅」列出 MIME 類型，系統會假設該元件支援 content: 和 file: 資料。

注意：如果意圖指定 URI 或 MIME 類型，且 <intent-filter> 中沒有 <data> 元素，資料測試就會失敗。

最後一項規則 (d) 則反映了元件應能從檔案或內容供應器取得店面資料。因此，篩選器可以只列出資料類型，不需要明確指定 content: 和 file: 配置。以下範例顯示典型案例，其中 <data> 元素會告知 Android，元件可以從內容供應器取得圖片資料並顯示：

<intent-filter>
    <data android:mimeType="image/*" />
    ...
</intent-filter>

指定資料類型而非 URI 的篩選器可能最常見，因為大多數可用資料都是由內容供應器提供。

另一種常見設定是包含配置和資料類型的篩選器。舉例來說，下列 <data> 元素會告知 Android，該元件可從網路擷取影片資料，以便執行動作：

<intent-filter>
    <data android:scheme="http" android:mimeType="video/*" />
    ...
</intent-filter>

意圖比對

意圖會與意圖篩選器進行比對，不僅是為了找出要啟用的目標元件，也是為了找出裝置上的元件組合。舉例來說，Google Home 應用程式會找出所有意圖篩選器指定 ACTION_MAIN 動作和 CATEGORY_LAUNCHER 類別的活動，並填入應用程式啟動器。只有在意圖中的動作和類別與篩選器相符時，比對才會成功，如 IntentFilter 類別說明文件所述。

應用程式可以使用意圖比對，方式與 Google Home 應用程式類似。PackageManager 包含一組 query...() 方法，可傳回所有能接受特定意圖的元件，以及一系列類似的 resolve...() 方法，可判斷回應意圖的最佳元件。舉例來說，queryIntentActivities() 會傳回可執行做為引數傳遞的意圖的所有活動清單，而 queryIntentServices() 則會傳回類似的服務清單。這兩種方法都不會啟用元件，只會列出可回應的元件。廣播接收器也有類似的方法：queryBroadcastReceivers()。