意圖和意圖篩選器

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] 活動 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 建構函式設定元件名稱。

動態

指定要執行的通用動作 (例如「查看」或「挑選」) 的字串。

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

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

ACTION_VIEW

當您有一些活動可向使用者顯示的資訊時，請在含有 startActivity() 的意圖中使用這項動作，例如要在相片庫應用程式中查看的相片，或要在地圖應用程式中查看的地址。

ACTION_SEND

這也稱為「分享」意圖。當您有使用者可透過其他應用程式 (例如電子郵件應用程式或社群分享應用程式) 分享的資料時，應在含有 startActivity() 的意圖中使用這項意圖。

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

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

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

KotlinJava 更多選項

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

static final String ACTION_TIMETRAVEL = "com.example.action.TIMETRAVEL";

資料

參照要處理的資料和/或該資料的 MIME 類型的 URI (Uri 物件)。提供的資料類型通常取決於意圖的動作。舉例來說，如果動作是 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 鍵指定 to 收件者，並使用 EXTRA_SUBJECT 鍵指定 subject。

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

KotlinJava 更多選項

const val EXTRA_GIGAWATTS = "com.example.EXTRA_GIGAWATTS"

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

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

旗標

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

詳情請參閱 setFlags() 方法。

明確意圖範例

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

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

KotlinJava 更多選項

// 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)

// 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() 時，使用者可以選擇要透過哪個應用程式分享內容。

KotlinJava 更多選項

// 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.
}

// 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()，並使用附加的文字做為對話方塊標題。

KotlinJava 更多選項

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)
}

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 上的這篇網誌文章。

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

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

注意： 如果您的應用程式指定 Android 12，並在 VmPolicy 定義中使用 detectAll() 方法，系統會自動呼叫 detectUnsafeIntentLaunch() 方法。

KotlinJava 更多選項

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

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 系統就不會將 Intent 傳送至元件。不過，由於元件可能有多個意圖篩選器，因此未通過其中一個篩選器的意圖，可能會通過另一個篩選器。如要進一步瞭解系統如何解析意圖，請參閱下方的「意圖解析」一節。

注意： 使用意圖篩選器並非安全做法，無法防止其他應用程式啟動您的元件。雖然意圖篩選器會限制元件，只回應特定類型的隱含意圖，但如果開發人員判斷出元件名稱，其他應用程式就可能使用明確意圖啟動您的應用程式元件。如果只有您自己的應用程式可以啟動其中一個元件，請勿在資訊清單中宣告意圖篩選器。請改為將該元件的 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，就像是從您應用程式的程序執行一樣。

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

• 宣告使用者對「通知」執行動作時要執行的意圖 (Android 系統的 NotificationManager 會執行 Intent)。
• 宣告使用者透過應用程式小工具執行動作時要執行的意圖 (主畫面應用程式會執行 Intent)。
• 宣告要在指定的未來時間執行的意圖 (Android 系統的 AlarmManager 會執行 Intent)。

如同每個 Intent 物件都是由特定類型的應用程式元件 (Activity、Service 或 BroadcastReceiver) 處理，建立 PendingIntent 時也必須考量這點。使用待處理的 Intent 時，應用程式不會透過 startActivity() 等呼叫執行 Intent。您必須呼叫相應的建立者方法，在建立 PendingIntent 時宣告預期的元件類型：

• PendingIntent.getActivity()，以啟動 Activity。Intent
• PendingIntent.getService()，以啟動 Service 的 Intent。
• PendingIntent.getBroadcast()，以啟動 BroadcastReceiver 的 Intent。

除非應用程式接收來自其他應用程式的待處理意圖，否則上述建立 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 物件不可變更，其他應用程式就無法修改意圖，調整叫用意圖的結果。

KotlinJava 更多選項

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

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()。