常用意圖

您可以透過意圖在 Intent 物件中描述您要執行的操作,以便在其他應用程式中開啟活動,例如「查看地圖」或「拍照」。這種類型的意圖稱為「隱含」意圖,因為這種意圖並未指定啟動的應用程式元件,而是指定「動作」,並提供一些要執行動作的「資料」

當您呼叫 startActivity()startActivityForResult() 並傳遞隱含意圖時,系統會將意圖解析至可處理意圖並啟動其對應 Activity 的應用程式。如果有多個應用程式可以處理意圖,系統就會向使用者顯示對話方塊,讓使用者選擇要使用的應用程式。

本頁說明多個隱含意圖,可用來執行常用動作,而這些意圖會按照處理該意圖的應用程式類型分門別類。每個章節還會說明如何建立意圖篩選器,宣傳應用程式執行這項動作的能力。

注意:如果裝置上沒有可接收隱含意圖的應用程式,則應用程式會在呼叫 startActivity() 時異常終止。首先,如要驗證應用程式是否存在接收意圖,請在 Intent 物件上呼叫 resolveActivity()。如果結果不是空值,則至少有一個應用程式可以處理意圖,而且可以放心呼叫 startActivity()。如果結果是空值,請勿使用該意圖,如果可以,請停用叫用意圖的功能。

如果您不熟悉如何建立意圖或意圖篩選器,請先參閱意圖和意圖篩選器

如要瞭解如何從開發主機觸發本頁列出的意圖,請參閱「使用 Android Debug Bridge 驗證意圖」一節。

Google 語音操作

Google Voice Actions 會回應本頁列出的部分意圖,藉此回應語音指令。詳情請參閱「 開始使用系統語音操作」。

鬧鐘

以下是鬧鐘應用程式的常見動作,包括建立意圖篩選器,以宣傳應用程式執行每個動作所需的資訊。

建立鬧鐘

Google 語音操作

  • 「設定早上 7 點的鬧鐘」

如要建立新鬧鐘,請使用 ACTION_SET_ALARM 動作,並使用下列額外項目指定鬧鐘詳細資料,例如時間和訊息。

注意:Android 2.3 (API 級別 9) 以下版本僅支援小時、分鐘和訊息額外項目。其他額外項目適用於較新版本的平台。

動作片
ACTION_SET_ALARM
資料 URI
MIME 類型
額外內容
EXTRA_HOUR
鬧鐘的小時數。
EXTRA_MINUTES
鬧鐘的分鐘數。
EXTRA_MESSAGE
用來識別鬧鐘的自訂訊息。
EXTRA_DAYS
ArrayList,包含這個鬧鐘的每週重複頻率。每天都必須使用 Calendar 類別的整數來宣告,例如 MONDAY

如果是一次性鬧鐘,請不要指定這個額外項目。

EXTRA_RINGTONE
指定用於鬧鐘鈴聲的 content: URI,或 VALUE_RINGTONE_SILENT 表示無鈴聲。

如要使用預設鈴聲,請勿指定這項額外項目。

EXTRA_VIBRATE
指定是否要為這個鬧鐘震動的布林值。
EXTRA_SKIP_UI
布林值,指定回應的應用程式在設定鬧鐘時是否必須略過 UI。如果為 true,應用程式必須略過任何確認 UI 並設定指定的鬧鐘。

意圖範例:

Kotlin

fun createAlarm(message: String, hour: Int, minutes: Int) {
    val intent = Intent(AlarmClock.ACTION_SET_ALARM).apply {
        putExtra(AlarmClock.EXTRA_MESSAGE, message)
        putExtra(AlarmClock.EXTRA_HOUR, hour)
        putExtra(AlarmClock.EXTRA_MINUTES, minutes)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void createAlarm(String message, int hour, int minutes) {
    Intent intent = new Intent(AlarmClock.ACTION_SET_ALARM)
            .putExtra(AlarmClock.EXTRA_MESSAGE, message)
            .putExtra(AlarmClock.EXTRA_HOUR, hour)
            .putExtra(AlarmClock.EXTRA_MINUTES, minutes);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}
注意:

如要叫用 ACTION_SET_ALARM 意圖,應用程式必須具備 SET_ALARM 權限:

<uses-permission android:name="com.android.alarm.permission.SET_ALARM" />

意圖篩選器範例:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.SET_ALARM" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

建立計時器

Google 語音操作

  • 「設定 5 分鐘的計時器。」

如要建立倒數計時器,請使用 ACTION_SET_TIMER 動作並指定計時器詳細資料,例如使用下列額外功能指定持續時間。

注意:這個意圖適用於 Android 4.4 (API 級別 19) 以上版本。

動作片
ACTION_SET_TIMER
資料 URI
MIME 類型
額外內容
EXTRA_LENGTH
計時器的長度 (以秒為單位)。
EXTRA_MESSAGE
用來識別計時器的自訂訊息。
EXTRA_SKIP_UI
布林值,指定回應的應用程式在設定計時器時,是否必須略過 UI。如果為 true,應用程式必須略過任何確認 UI 並啟動指定的計時器。

意圖範例:

Kotlin

fun startTimer(message: String, seconds: Int) {
    val intent = Intent(AlarmClock.ACTION_SET_TIMER).apply {
        putExtra(AlarmClock.EXTRA_MESSAGE, message)
        putExtra(AlarmClock.EXTRA_LENGTH, seconds)
        putExtra(AlarmClock.EXTRA_SKIP_UI, true)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void startTimer(String message, int seconds) {
    Intent intent = new Intent(AlarmClock.ACTION_SET_TIMER)
            .putExtra(AlarmClock.EXTRA_MESSAGE, message)
            .putExtra(AlarmClock.EXTRA_LENGTH, seconds)
            .putExtra(AlarmClock.EXTRA_SKIP_UI, true);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}
注意:

如要叫用 ACTION_SET_TIMER 意圖,應用程式必須具備 SET_ALARM 權限:

<uses-permission android:name="com.android.alarm.permission.SET_ALARM" />

意圖篩選器範例:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.SET_TIMER" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

顯示所有鬧鐘

如要顯示鬧鐘清單,請使用 ACTION_SHOW_ALARMS 動作。

雖然叫用這個意圖的應用程式並不多 (因為系統應用程式主要由系統應用程式使用),但任何做為鬧鐘應用程式的應用程式,都能實作此意圖篩選器,並顯示目前鬧鐘清單做為回應。

注意:這個意圖適用於 Android 4.4 (API 級別 19) 以上版本。

動作片
ACTION_SHOW_ALARMS
資料 URI
MIME 類型

意圖篩選器範例:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.SHOW_ALARMS" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

日曆

新增活動是日曆應用程式的常見動作。 建立意圖篩選器,宣傳應用程式執行這項動作的能力。請參考下一節的資訊。

新增日曆活動

如要將新事件新增至使用者的日曆,請使用 ACTION_INSERT 動作,並使用 Events.CONTENT_URI 指定資料 URI。接著,您可以使用下列額外項目,指定各種活動詳細資料。

動作片
ACTION_INSERT
資料 URI
Events.CONTENT_URI
MIME 類型
"vnd.android.cursor.dir/event"
額外內容
EXTRA_EVENT_ALL_DAY
布林值,指定是否為全天事件。
EXTRA_EVENT_BEGIN_TIME
事件開始時間 (自 Epoch 紀元時間起算的毫秒數)。
EXTRA_EVENT_END_TIME
事件結束時間 (自 Epoch 紀元時間起算的毫秒數)。
TITLE
活動名稱。
DESCRIPTION
活動說明。
EVENT_LOCATION
活動地點。
EXTRA_EMAIL
以半形逗號分隔的電子郵件地址清單,用於指定邀請對象。

您可以使用 CalendarContract.EventsColumns 類別中定義的常數,指定更多事件詳細資料。

意圖範例:

Kotlin

fun addEvent(title: String, location: String, begin: Long, end: Long) {
    val intent = Intent(Intent.ACTION_INSERT).apply {
        data = Events.CONTENT_URI
        putExtra(Events.TITLE, title)
        putExtra(Events.EVENT_LOCATION, location)
        putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, begin)
        putExtra(CalendarContract.EXTRA_EVENT_END_TIME, end)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void addEvent(String title, String location, long begin, long end) {
    Intent intent = new Intent(Intent.ACTION_INSERT)
            .setData(Events.CONTENT_URI)
            .putExtra(Events.TITLE, title)
            .putExtra(Events.EVENT_LOCATION, location)
            .putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, begin)
            .putExtra(CalendarContract.EXTRA_EVENT_END_TIME, end);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

意圖篩選器範例:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.INSERT" />
        <data android:mimeType="vnd.android.cursor.dir/event" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

相機

以下是相機應用程式的常見動作,包括建立意圖篩選器來宣傳應用程式執行每項動作所需的資訊。

拍照或錄影並發還

如要開啟相機應用程式,並接收最終產生的相片或影片,請使用 ACTION_IMAGE_CAPTUREACTION_VIDEO_CAPTURE 動作。此外,請在 EXTRA_OUTPUT 額外項目中指定相機儲存相片或影片的 URI 位置。

動作片
ACTION_IMAGE_CAPTURE
ACTION_VIDEO_CAPTURE
資料 URI 配置
MIME 類型
額外內容
EXTRA_OUTPUT
相機應用程式儲存相片或影片檔案的 URI 位置 (以 Uri 物件形式)。

相機應用程式成功將焦點傳回至活動後 (也就是應用程式會收到 onActivityResult() 回呼),您就能透過使用 EXTRA_OUTPUT 值指定的 URI 存取相片或影片。

注意:使用 ACTION_IMAGE_CAPTURE 拍照時,相機可能也會在結果 Intent 中傳回縮減後的相片副本或縮圖,並以 Bitmap 的形式儲存在名為 "data" 的額外欄位中。

意圖範例:

Kotlin

const val REQUEST_IMAGE_CAPTURE = 1
val locationForPhotos: Uri = ...

fun capturePhoto(targetFilename: String) {
    val intent = Intent(MediaStore.ACTION_IMAGE_CAPTURE).apply {
        putExtra(MediaStore.EXTRA_OUTPUT, Uri.withAppendedPath(locationForPhotos, targetFilename))
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_CAPTURE)
    }
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    if (requestCode == REQUEST_IMAGE_CAPTURE && resultCode == Activity.RESULT_OK) {
        val thumbnail: Bitmap = data.getParcelableExtra("data")
        // Do other work with full size photo saved in locationForPhotos.
        ...
    }
}

Java

static final int REQUEST_IMAGE_CAPTURE = 1;
static final Uri locationForPhotos;

public void capturePhoto(String targetFilename) {
    Intent intent = new Intent(MediaStore.ACTION_IMAGE_CAPTURE);
    intent.putExtra(MediaStore.EXTRA_OUTPUT,
            Uri.withAppendedPath(locationForPhotos, targetFilename));
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_CAPTURE);
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_IMAGE_CAPTURE && resultCode == RESULT_OK) {
        Bitmap thumbnail = data.getParcelableExtra("data");
        // Do other work with full size photo saved in locationForPhotos.
        ...
    }
}

如要在 Android 12 (API 級別 31) 以上版本中執行這項操作,請參閱以下意圖範例。

意圖範例:

Kotlin

val REQUEST_IMAGE_CAPTURE = 1

private fun dispatchTakePictureIntent() {
    val takePictureIntent = Intent(MediaStore.ACTION_IMAGE_CAPTURE)
    try {
        startActivityForResult(takePictureIntent, REQUEST_IMAGE_CAPTURE)
    } catch (e: ActivityNotFoundException) {
        // Display error state to the user.
    }
}

Java

static final int REQUEST_IMAGE_CAPTURE = 1;

private void dispatchTakePictureIntent() {
    Intent takePictureIntent = new Intent(MediaStore.ACTION_IMAGE_CAPTURE);
    try {
        startActivityForResult(takePictureIntent, REQUEST_IMAGE_CAPTURE);
    } catch (ActivityNotFoundException e) {
        // Display error state to the user.
    }
}
</section></div>

如要進一步瞭解如何使用這個意圖拍照,包括如何為輸出位置建立適當的 Uri,請參閱「拍照」或「拍照」。

意圖篩選器範例:

<activity ...>
    <intent-filter>
        <action android:name="android.media.action.IMAGE_CAPTURE" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

處理此意圖時,讓活動檢查傳入 Intent 中的 EXTRA_OUTPUT 額外項目,然後將擷取的圖片或影片儲存在該額外項目指定的位置,並呼叫 setResult(),其中含有壓縮縮圖的 Intent (包含在名為 的額外名稱的 "data" 中)。

以靜止圖像模式啟動相機應用程式

Google 語音操作

  • 「拍照」

如要在靜態影像模式中開啟相機應用程式,請使用 INTENT_ACTION_STILL_IMAGE_CAMERA 動作。

動作片
INTENT_ACTION_STILL_IMAGE_CAMERA
資料 URI 配置
MIME 類型
額外內容

意圖範例:

Kotlin

private fun dispatchTakePictureIntent() {
    val takePictureIntent = Intent(MediaStore.ACTION_IMAGE_CAPTURE)
    try {
        startActivityForResult(takePictureIntent, REQUEST_IMAGE_CAPTURE)
    } catch (e: ActivityNotFoundException) {
        // Display error state to the user.
    }
}

Java

public void capturePhoto(String targetFilename) {
    Intent intent = new Intent(MediaStore.ACTION_IMAGE_CAPTURE);
    intent.putExtra(MediaStore.EXTRA_OUTPUT,
            Uri.withAppendedPath(locationForPhotos, targetFilename));
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_CAPTURE);
    }
}

意圖篩選器範例:

<activity ...>
    <intent-filter>
        <action android:name="android.media.action.STILL_IMAGE_CAMERA" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

在影片模式下啟動相機應用程式

Google 語音操作

  • 「錄影」

如要在影片模式中開啟相機應用程式,請使用 INTENT_ACTION_VIDEO_CAMERA 動作。

動作片
INTENT_ACTION_VIDEO_CAMERA
資料 URI 配置
MIME 類型
額外內容

意圖範例:

Kotlin

fun capturePhoto() {
    val intent = Intent(MediaStore.INTENT_ACTION_VIDEO_CAMERA)
    if (intent.resolveActivity(packageManager) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_CAPTURE)
    }
}

Java

public void capturePhoto() {
    Intent intent = new Intent(MediaStore.INTENT_ACTION_VIDEO_CAMERA);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_CAPTURE);
    }
}

意圖篩選器範例:

<activity ...>
    <intent-filter>
        <action android:name="android.media.action.VIDEO_CAMERA" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

聯絡人/使用者應用程式

以下是聯絡人管理應用程式的常見動作,包括建立意圖篩選器,以宣傳應用程式執行每個動作所需的資訊。

選取聯絡人

如要讓使用者選取聯絡人,並向應用程式提供所有聯絡資訊的存取權,請使用 ACTION_PICK 動作,並將 MIME 類型指定為 Contacts.CONTENT_TYPE

傳送至 onActivityResult() 回呼的結果 Intent 會包含指向所選聯絡人的 content: URI。該回應可使用 Contacts Provider API 授予應用程式暫時的讀取權限,即使應用程式未包含 READ_CONTACTS 權限也一樣。

提示:如果只需存取特定聯絡資訊,例如電話號碼或電子郵件地址,請改為參閱選取特定聯絡人資料的章節。

動作片
ACTION_PICK
資料 URI 配置
MIME 類型
Contacts.CONTENT_TYPE

意圖範例:

Kotlin

const val REQUEST_SELECT_CONTACT = 1

fun selectContact() {
    val intent = Intent(Intent.ACTION_PICK).apply {
        type = ContactsContract.Contacts.CONTENT_TYPE
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivityForResult(intent, REQUEST_SELECT_CONTACT)
    }
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    if (requestCode == REQUEST_SELECT_CONTACT && resultCode == RESULT_OK) {
        val contactUri: Uri = data.data
        // Do something with the selected contact at contactUri.
        //...
    }
}

Java

static final int REQUEST_SELECT_CONTACT = 1;

public void selectContact() {
    Intent intent = new Intent(Intent.ACTION_PICK);
    intent.setType(ContactsContract.Contacts.CONTENT_TYPE);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_SELECT_CONTACT);
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_SELECT_CONTACT && resultCode == RESULT_OK) {
        Uri contactUri = data.getData();
        // Do something with the selected contact at contactUri.
        ...
    }
}

如要瞭解如何取得聯絡人 URI 後的聯絡人詳細資料,請參閱擷取聯絡人的詳細資料

使用這個意圖擷取聯絡人 URI 時,通常不需要讀取該聯絡人基本詳細資料 (例如顯示名稱和聯絡人是否已加星號) 的 READ_CONTACTS 權限。不過,如果想要讀取特定聯絡人的特定資料 (例如電話號碼或電子郵件地址),您就需要 READ_CONTACTS 權限。

選取特定聯絡人資料

如要讓使用者選取聯絡人中的特定資訊,例如電話號碼、電子郵件地址或其他資料類型,請使用 ACTION_PICK 動作,並將 MIME 類型指定為下列其中一種內容類型 (例如 CommonDataKinds.Phone.CONTENT_TYPE) 以取得聯絡人的電話號碼。

注意: 在許多情況下,您的應用程式必須具備 READ_CONTACTS 權限,才能查看特定聯絡人的特定資訊。

如果只需要從聯絡人擷取一種類型的資料,則在 ContactsContract.CommonDataKinds 類別中使用 CONTENT_TYPE 的這項技巧,比使用 Contacts.CONTENT_TYPE 更有效率,如上一節所示。輸出結果可讓您直接存取所需資料,無須對 Contacts Provider 執行更複雜的查詢。

傳送至 onActivityResult() 回呼的結果 Intent 會包含指向所選聯絡人資料的 content: URI。回應會授予應用程式暫時讀取該聯絡人資料,即使應用程式未包含 READ_CONTACTS 權限也一樣。

動作片
ACTION_PICK
資料 URI 配置
MIME 類型
CommonDataKinds.Phone.CONTENT_TYPE
從有電話號碼的聯絡人中挑選。
CommonDataKinds.Email.CONTENT_TYPE
從有電子郵件地址的聯絡人中選擇。
CommonDataKinds.StructuredPostal.CONTENT_TYPE
從設有郵寄地址的聯絡人中選擇。

或是 ContactsContract 下的其他許多 CONTENT_TYPE 值。

意圖範例:

Kotlin

const val REQUEST_SELECT_PHONE_NUMBER = 1

fun selectContact() {
    // Start an activity for the user to pick a phone number from contacts.
    val intent = Intent(Intent.ACTION_PICK).apply {
        type = CommonDataKinds.Phone.CONTENT_TYPE
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivityForResult(intent, REQUEST_SELECT_PHONE_NUMBER)
    }
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    if (requestCode == REQUEST_SELECT_PHONE_NUMBER && resultCode == Activity.RESULT_OK) {
        // Get the URI and query the content provider for the phone number.
        val contactUri: Uri = data.data
        val projection: Array<String> = arrayOf(CommonDataKinds.Phone.NUMBER)
        contentResolver.query(contactUri, projection, null, null, null).use { cursor ->
            // If the cursor returned is valid, get the phone number.
            if (cursor.moveToFirst()) {
                val numberIndex = cursor.getColumnIndex(CommonDataKinds.Phone.NUMBER)
                val number = cursor.getString(numberIndex)
                // Do something with the phone number.
                ...
            }
        }
    }
}

Java

static final int REQUEST_SELECT_PHONE_NUMBER = 1;

public void selectContact() {
    // Start an activity for the user to pick a phone number from contacts.
    Intent intent = new Intent(Intent.ACTION_PICK);
    intent.setType(CommonDataKinds.Phone.CONTENT_TYPE);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_SELECT_PHONE_NUMBER);
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_SELECT_PHONE_NUMBER && resultCode == RESULT_OK) {
        // Get the URI and query the content provider for the phone number.
        Uri contactUri = data.getData();
        String[] projection = new String[]{CommonDataKinds.Phone.NUMBER};
        Cursor cursor = getContentResolver().query(contactUri, projection,
                null, null, null);
        // If the cursor returned is valid, get the phone number.
        if (cursor != null && cursor.moveToFirst()) {
            int numberIndex = cursor.getColumnIndex(CommonDataKinds.Phone.NUMBER);
            String number = cursor.getString(numberIndex);
            // Do something with the phone number.
            //...
        }
    }
}

查看聯絡人

如要顯示已知聯絡人的詳細資料,請使用 ACTION_VIEW 動作,並指定包含 content: URI 的聯絡人做為意圖資料。

最初擷取聯絡人 URI 的方式有兩種:

  • 使用上一節顯示的 ACTION_PICK 動作回傳的聯絡人 URI。這種做法不需要任何應用程式權限。
  • 直接存取所有聯絡人清單,如擷取聯絡人清單所述。這個方法需要 READ_CONTACTS 權限。
動作片
ACTION_VIEW
資料 URI 配置
content:<URI>
MIME 類型
無。類型是從聯絡人 URI 推測得出。

意圖範例:

Kotlin

fun viewContact(contactUri: Uri) {
    val intent = Intent(Intent.ACTION_VIEW, contactUri)
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void viewContact(Uri contactUri) {
    Intent intent = new Intent(Intent.ACTION_VIEW, contactUri);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

編輯現有聯絡人

如要編輯已知聯絡人,請使用 ACTION_EDIT 動作,並指定使用 content: URI 的聯絡人做為意圖資料,然後在 ContactsContract.Intents.Insert 中的常數指定的額外項目中加入任何已知的聯絡資訊。

最初擷取聯絡人 URI 的方式主要有兩種:

  • 使用上一節顯示的 ACTION_PICK 動作回傳的聯絡人 URI。這種做法不需要任何應用程式權限。
  • 直接存取所有聯絡人清單,如擷取聯絡人清單所述。這個方法需要 READ_CONTACTS 權限。
動作片
ACTION_EDIT
資料 URI 配置
content:<URI>
MIME 類型
類型是從聯絡人 URI 推測得出。
額外內容
ContactsContract.Intents.Insert 中定義的一或多個額外項目,以便填入聯絡人詳細資料的欄位。

意圖範例:

Kotlin

fun editContact(contactUri: Uri, email: String) {
    val intent = Intent(Intent.ACTION_EDIT).apply {
        data = contactUri
        putExtra(ContactsContract.Intents.Insert.EMAIL, email)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void editContact(Uri contactUri, String email) {
    Intent intent = new Intent(Intent.ACTION_EDIT);
    intent.setData(contactUri);
    intent.putExtra(Intents.Insert.EMAIL, email);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

如要進一步瞭解如何編輯聯絡人,請參閱「使用意圖修改聯絡人」。

插入聯絡人

如要插入新聯絡人,請使用 ACTION_INSERT 動作,將 Contacts.CONTENT_TYPE 指定為 MIME 類型,然後在 ContactsContract.Intents.Insert 中常數指定的額外項目中加入任何已知的聯絡資訊。

動作片
ACTION_INSERT
資料 URI 配置
MIME 類型
Contacts.CONTENT_TYPE
額外內容
ContactsContract.Intents.Insert 中定義的一或多個額外項目。

意圖範例:

Kotlin

fun insertContact(name: String, email: String) {
    val intent = Intent(Intent.ACTION_INSERT).apply {
        type = ContactsContract.Contacts.CONTENT_TYPE
        putExtra(ContactsContract.Intents.Insert.NAME, name)
        putExtra(ContactsContract.Intents.Insert.EMAIL, email)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void insertContact(String name, String email) {
    Intent intent = new Intent(Intent.ACTION_INSERT);
    intent.setType(Contacts.CONTENT_TYPE);
    intent.putExtra(Intents.Insert.NAME, name);
    intent.putExtra(Intents.Insert.EMAIL, email);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

如要進一步瞭解如何插入聯絡人,請參閱「使用意圖修改聯絡人」。

電子郵件

撰寫含有選用附件的電子郵件是電子郵件應用程式的常見動作。 建立意圖篩選器,宣傳應用程式執行這項動作的能力。請參考下一節的資訊。

撰寫含有選用附件的電子郵件

如要撰寫電子郵件,請根據是否要加入附件,執行下列其中一項操作,並使用列出的額外索引鍵加入電子郵件詳細資料 (例如收件者和主旨)。

動作片
ACTION_SENDTO (不附加附件) 或
ACTION_SEND (用於單一附件) 或
ACTION_SEND_MULTIPLE (用於多個附件)
資料 URI 配置
MIME 類型
"text/plain"
"*/*"
額外內容
Intent.EXTRA_EMAIL
所有「收件者」電子郵件地址的字串陣列。
Intent.EXTRA_CC
所有「副本」收件者電子郵件地址的字串陣列。
Intent.EXTRA_BCC
所有「BCC」收件者電子郵件地址的字串陣列。
Intent.EXTRA_SUBJECT
包含電子郵件主旨的字串。
Intent.EXTRA_TEXT
包含電子郵件內文的字串。
Intent.EXTRA_STREAM
指向附件的 Uri。如果使用 ACTION_SEND_MULTIPLE 動作,而是包含多個 Uri 物件的 ArrayList

意圖範例:

Kotlin

fun composeEmail(addresses: Array<String>, subject: String, attachment: Uri) {
    val intent = Intent(Intent.ACTION_SEND).apply {
        type = "*/*"
        putExtra(Intent.EXTRA_EMAIL, addresses)
        putExtra(Intent.EXTRA_SUBJECT, subject)
        putExtra(Intent.EXTRA_STREAM, attachment)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void composeEmail(String[] addresses, String subject, Uri attachment) {
    Intent intent = new Intent(Intent.ACTION_SEND);
    intent.setType("*/*");
    intent.putExtra(Intent.EXTRA_EMAIL, addresses);
    intent.putExtra(Intent.EXTRA_SUBJECT, subject);
    intent.putExtra(Intent.EXTRA_STREAM, attachment);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

如要確保意圖只由電子郵件應用程式處理,而非文字訊息或社交應用程式,請使用 ACTION_SENDTO 動作並加入 "mailto:" 資料配置,如以下範例所示:

Kotlin

fun composeEmail(addresses: Array<String>, subject: String) {
    val intent = Intent(Intent.ACTION_SENDTO).apply {
        data = Uri.parse("mailto:") // Only email apps handle this.
        putExtra(Intent.EXTRA_EMAIL, addresses)
        putExtra(Intent.EXTRA_SUBJECT, subject)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void composeEmail(String[] addresses, String subject) {
    Intent intent = new Intent(Intent.ACTION_SENDTO);
    intent.setData(Uri.parse("mailto:")); // Only email apps handle this.
    intent.putExtra(Intent.EXTRA_EMAIL, addresses);
    intent.putExtra(Intent.EXTRA_SUBJECT, subject);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

意圖篩選器範例:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <data android:type="*/*" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.SENDTO" />
        <data android:scheme="mailto" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

檔案儲存空間

以下是檔案儲存應用程式的常見動作,包括建立意圖篩選器來宣傳應用程式執行每個動作所需的資訊。

擷取特定類型的檔案

如要要求使用者選取文件或相片等檔案,並傳回應用程式的參照,請使用 ACTION_GET_CONTENT 動作並指定所需的 MIME 類型。返回應用程式的檔案參照只會存在活動目前的生命週期中,因此如要之後存取,必須匯入副本,以便稍後讀取。

這個意圖也可讓使用者在程序中建立新檔案。舉例來說,使用者不必選取現有相片,也可以使用相機拍攝新相片。

傳送至 onActivityResult() 方法的結果意圖會包括具有指向檔案 URI 的資料。URI 可以是任何內容,例如 http: URI、file: URI 或 content: URI。不過,如果您想限制可選取的檔案,僅限可透過內容供應器 (content: URI) 存取,且可用 openFileDescriptor() 做為檔案串流使用的檔案,請在意圖中加入 CATEGORY_OPENABLE 類別。

在 Android 4.3 (API 級別 18) 以上版本中,您也可以在意圖中加入 EXTRA_ALLOW_MULTIPLE,並設為 true,讓使用者選取多個檔案。接著,您可以在 getClipData() 傳回的 ClipData 物件中存取每個選取的檔案。

動作片
ACTION_GET_CONTENT
資料 URI 配置
MIME 類型
與使用者需要選取的檔案類型相對應的 MIME 類型。
額外內容
EXTRA_ALLOW_MULTIPLE
布林值,用來宣告使用者是否能一次選取多個檔案。
EXTRA_LOCAL_ONLY
這個布林值用於宣告回傳的檔案是否必須直接從裝置取得,而非要求遠端服務下載。
類別 (選填)
CATEGORY_OPENABLE
如要僅傳回可使用 openFileDescriptor() 以檔案串流表示的「可開啟」檔案。

取得相片的意圖範例:

Kotlin

const val REQUEST_IMAGE_GET = 1

fun selectImage() {
    val intent = Intent(Intent.ACTION_GET_CONTENT).apply {
        type = "image/*"
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_GET)
    }
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    if (requestCode == REQUEST_IMAGE_GET && resultCode == Activity.RESULT_OK) {
        val thumbnail: Bitmap = data.getParcelableExtra("data")
        val fullPhotoUri: Uri = data.data
        // Do work with photo saved at fullPhotoUri.
        ...
    }
}

Java

static final int REQUEST_IMAGE_GET = 1;

public void selectImage() {
    Intent intent = new Intent(Intent.ACTION_GET_CONTENT);
    intent.setType("image/*");
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_GET);
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_IMAGE_GET && resultCode == RESULT_OK) {
        Bitmap thumbnail = data.getParcelable("data");
        Uri fullPhotoUri = data.getData();
        // Do work with photo saved at fullPhotoUri.
        ...
    }
}

傳回相片的意圖篩選器範例:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.GET_CONTENT" />
        <data android:type="image/*" />
        <category android:name="android.intent.category.DEFAULT" />
        <!-- The OPENABLE category declares that the returned file is accessible
             from a content provider that supports OpenableColumns
             and ContentResolver.openFileDescriptor(). -->
        <category android:name="android.intent.category.OPENABLE" />
    </intent-filter>
</activity>

開啟特定類型的檔案

在 Android 4.4 以上版本中執行時,您可以使用 ACTION_GET_CONTENT 動作擷取必須匯入到應用程式中的檔案副本,而不需擷取該檔案副本,您可以使用 ACTION_OPEN_DOCUMENT 動作並指定 MIME 類型,要求「開啟」由其他應用程式管理的檔案。如要允許使用者建立應用程式可寫入的新文件,請改用 ACTION_CREATE_DOCUMENT 動作。

舉例來說,ACTION_CREATE_DOCUMENT 意圖可讓使用者自行選擇要建立新文件的位置,例如在管理文件儲存空間的其他應用程式中,直接選取需要建立新文件的位置,而不必從現有的 PDF 文件中選取。接著,您的應用程式會收到 URI 位置,該位置可以寫入新文件。

雖然從 ACTION_GET_CONTENT 動作傳送至 onActivityResult() 方法的意圖可能會傳回任何類型的 URI,而 ACTION_OPEN_DOCUMENTACTION_CREATE_DOCUMENT 的結果意圖一律會將所選檔案指定為由 DocumentsProvider 支援的 content: URI。您可以使用 openFileDescriptor() 開啟檔案,並使用 DocumentsContract.Document 中的資料欄查詢其詳細資料。

傳回的 URI 可將檔案的長期讀取權限授予應用程式,而該權限可能也擁有寫入權限。如果想讀取現有檔案而不建立副本,或想開啟現有的檔案並進行編輯,ACTION_OPEN_DOCUMENT 動作就特別實用。

您也可以把 EXTRA_ALLOW_MULTIPLE 新增至意圖 (設為 true),讓使用者選取多個檔案。如果使用者只選取一個項目,您可以從 getData() 擷取該項目。如果使用者選取多個項目,getData() 會傳回空值,因此您必須從 getClipData() 傳回的 ClipData 物件擷取每個項目。

注意:意圖必須指定 MIME 類型,且必須宣告 CATEGORY_OPENABLE 類別。如有需要,您可以使用 EXTRA_MIME_TYPES 額外項目新增 MIME 類型陣列,以指定多個 MIME 類型,如果同時這麼做,您必須將 setType() 中的主要 MIME 類型設為 "*/*"

動作片
ACTION_OPEN_DOCUMENT
ACTION_CREATE_DOCUMENT
資料 URI 配置
MIME 類型
與使用者需要選取的檔案類型相對應的 MIME 類型。
額外內容
EXTRA_MIME_TYPES
與應用程式要求檔案類型對應的 MIME 類型陣列。使用這項額外項目時,必須將 setType() 中的主要 MIME 類型設為 "*/*"
EXTRA_ALLOW_MULTIPLE
布林值,用來宣告使用者是否能一次選取多個檔案。
EXTRA_TITLE
ACTION_CREATE_DOCUMENT 搭配使用來指定初始檔案名稱。
EXTRA_LOCAL_ONLY
這個布林值用於宣告回傳的檔案是否必須直接從裝置取得,而非要求遠端服務下載。
類別
CATEGORY_OPENABLE
如要僅傳回可使用 openFileDescriptor() 以檔案串流表示的「可開啟」檔案。

取得相片的意圖範例:

Kotlin

const val REQUEST_IMAGE_OPEN = 1

fun selectImage2() {
    val intent = Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
        type = "image/*"
        addCategory(Intent.CATEGORY_OPENABLE)
    }
    // Only the system receives the ACTION_OPEN_DOCUMENT, so no need to test.
    startActivityForResult(intent, REQUEST_IMAGE_OPEN)
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    if (requestCode == REQUEST_IMAGE_OPEN && resultCode == Activity.RESULT_OK) {
        val fullPhotoUri: Uri = data.data
        // Do work with full size photo saved at fullPhotoUri.
        ...
    }
}

Java

static final int REQUEST_IMAGE_OPEN = 1;

public void selectImage() {
    Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
    intent.setType("image/*");
    intent.addCategory(Intent.CATEGORY_OPENABLE);
    // Only the system receives the ACTION_OPEN_DOCUMENT, so no need to test.
    startActivityForResult(intent, REQUEST_IMAGE_OPEN);
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_IMAGE_OPEN && resultCode == RESULT_OK) {
        Uri fullPhotoUri = data.getData();
        // Do work with full size photo saved at fullPhotoUri.
        ...
    }
}

第三方應用程式無法使用 ACTION_OPEN_DOCUMENT 動作回應意圖。而會接收此意圖,並在整合式使用者介面中顯示各種應用程式的可用檔案。

如要在這個使用者介面中提供應用程式檔案,並讓其他應用程式開啟檔案,您必須實作 DocumentsProvider,並為 PROVIDER_INTERFACE ("android.content.action.DOCUMENTS_PROVIDER") 加入意圖篩選器,如以下範例所示:

<provider ...
    android:grantUriPermissions="true"
    android:exported="true"
    android:permission="android.permission.MANAGE_DOCUMENTS">
    <intent-filter>
        <action android:name="android.content.action.DOCUMENTS_PROVIDER" />
    </intent-filter>
</provider>

如要進一步瞭解如何透過其他應用程式開啟由您的應用程式管理的檔案,請參閱「使用儲存空間存取架構開啟檔案」。

本地動作

撥打汽車是常見的本地動作,建立意圖篩選器,以便宣傳應用程式執行這項動作的能力,請參考下一節的資訊。

叫計程車

Google 語音操作

  • 「幫我叫計程車」
  • 「打電話給我」

(僅限 Wear OS)

如要叫計程車,請使用 ACTION_RESERVE_TAXI_RESERVATION 動作。

注意:應用程式必須先要求使用者確認,才能完成這項操作。

動作片
ACTION_RESERVE_TAXI_RESERVATION
資料 URI
MIME 類型
額外內容

意圖範例:

Kotlin

fun callCar() {
    val intent = Intent(ReserveIntents.ACTION_RESERVE_TAXI_RESERVATION)
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void callCar() {
    Intent intent = new Intent(ReserveIntents.ACTION_RESERVE_TAXI_RESERVATION);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

意圖篩選器範例:

<activity ...>
    <intent-filter>
        <action android:name="com.google.android.gms.actions.RESERVE_TAXI_RESERVATION" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Google 地圖

在地圖上顯示地點是地圖應用程式的常見動作。建立意圖篩選器,宣傳應用程式執行這項動作的能力。請參考下一節的資訊。

在地圖上顯示位置

如要開啟地圖,請使用 ACTION_VIEW 動作,並透過下列其中一種配置,在意圖資料中指定位置資訊。

動作片
ACTION_VIEW
資料 URI 配置
geo:latitude,longitude
在指定經緯度顯示地圖。

範例:"geo:47.6,-122.3"

geo:latitude,longitude?z=zoom
在特定縮放等級下,顯示指定經緯度的地圖。縮放等級 1 會顯示整個地球,並以指定 latlng 為中心點。最高 (最接近) 的縮放等級為 23。

範例:"geo:47.6,-122.3?z=11"

geo:0,0?q=lat,lng(label)
在指定經緯度顯示地圖,並使用字串標籤。

範例:"geo:0,0?q=34.99,-106.61(Treasure)"

geo:0,0?q=my+street+address
顯示「我的街道地址」的位置,可以是特定地址或位置查詢。

範例:"geo:0,0?q=1600+Amphitheatre+Parkway%2C+CA"

注意事項:geo URI 中傳遞的所有字串都必須經過編碼。舉例來說,1st & Pike, Seattle 字串會變為 1st%20%26%20Pike%2C%20Seattle。字串中的空格會以 %20 編碼,或以加號 (+) 取代。

MIME 類型

意圖範例:

Kotlin

fun showMap(geoLocation: Uri) {
    val intent = Intent(Intent.ACTION_VIEW).apply {
        data = geoLocation
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void showMap(Uri geoLocation) {
    Intent intent = new Intent(Intent.ACTION_VIEW);
    intent.setData(geoLocation);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

意圖篩選器範例:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="geo" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

音樂或影片

以下是音樂和影片應用程式的常見動作,包括建立意圖篩選器來宣傳應用程式執行每個動作所需的資訊。

播放媒體檔案

如要播放音樂檔案,請使用 ACTION_VIEW 動作,並在意圖資料中指定檔案的 URI 位置。

動作片
ACTION_VIEW
資料 URI 配置
file:<URI>
content:<URI>
http:<URL>
MIME 類型
"audio/*"
"application/ogg"
"application/x-ogg"
"application/itunes"
應用程式所需的任何其他項目。

意圖範例:

Kotlin

fun playMedia(file: Uri) {
    val intent = Intent(Intent.ACTION_VIEW).apply {
        data = file
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void playMedia(Uri file) {
    Intent intent = new Intent(Intent.ACTION_VIEW);
    intent.setData(file);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

意圖篩選器範例:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <data android:type="audio/*" />
        <data android:type="application/ogg" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

依據搜尋查詢播放音樂

Google 語音操作

  • 「播放 michael jackson Billingie jean」

如要根據搜尋查詢播放音樂,請使用 INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH 意圖。應用程式可能會回應使用者的語音指令來播放音樂,藉此觸發這個意圖。此意圖的接收應用程式會在其廣告空間中執行搜尋,藉此比對現有內容與指定的查詢,並開始播放該內容。

在這個意圖中加入 EXTRA_MEDIA_FOCUS 字串額外項目,用來指定預期的搜尋模式。舉例來說,搜尋模式可以指定搜尋是要搜尋演出者名稱或歌曲名稱。

動作片
INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH
資料 URI 配置
MIME 類型
額外內容
MediaStore.EXTRA_MEDIA_FOCUS (必填)

指出搜尋模式:使用者是否正在搜尋特定藝人、專輯、歌曲或播放清單。大部分的搜尋模式會額外提供額外功能。舉例來說,如果使用者有興趣收聽特定歌曲,則意圖可能會額外提供三個額外項目:歌名、藝人和專輯。這項意圖支援下列每個 EXTRA_MEDIA_FOCUS 值的搜尋模式:

不限 - "vnd.android.cursor.item/*"

可播放任何音樂。接收端應用程式會根據智慧選項播放部分音樂,例如使用者上次聆聽的播放清單。

其他額外內容:

  • QUERY (必要):空白字串。為顧及回溯相容性,系統一律會提供這項額外項目。現有應用程式如不知道搜尋模式,可將這項意圖視為非結構化搜尋。

非結構化 - "vnd.android.cursor.item/*"

透過非結構化搜尋查詢播放特定歌曲、專輯或類型。如果應用程式無法識別使用者要收聽的內容類型,就能利用這個搜尋模式產生意圖。請盡可能使用更明確的搜尋模式。

其他額外內容:

  • QUERY (必要):包含演出者、專輯、歌曲名稱或類型的任意組合的字串。

類型 - Audio.Genres.ENTRY_CONTENT_TYPE

播放特定類型的音樂。

其他額外內容:

  • "android.intent.extra.genre" (必要):類型。
  • QUERY (必要):類型。為顧及回溯相容性,系統一律會提供這項額外項目。現有應用程式如不知道搜尋模式,可將這項意圖視為非結構化搜尋。

藝人 - Audio.Artists.ENTRY_CONTENT_TYPE

播放特定藝人的音樂。

其他額外內容:

  • EXTRA_MEDIA_ARTIST (必要):藝人。
  • "android.intent.extra.genre":類型。
  • QUERY (必要):包含演出者或類型組合的任意字串。為顧及回溯相容性,系統一律會提供這項額外項目。現有應用程式如不知道搜尋模式,可將這項意圖視為非結構化搜尋。

專輯 - Audio.Albums.ENTRY_CONTENT_TYPE

播放特定專輯中的音樂。

其他額外內容:

  • EXTRA_MEDIA_ALBUM (必要):相簿。
  • EXTRA_MEDIA_ARTIST:藝人。
  • "android.intent.extra.genre":類型。
  • QUERY (必要):包含專輯或演出者任意組合的字串。為顧及回溯相容性,系統一律會提供這項額外項目。現有應用程式如不知道搜尋模式,可將這項意圖視為非結構化搜尋。

歌曲 - "vnd.android.cursor.item/audio"

播放特定歌曲。

其他額外內容:

  • EXTRA_MEDIA_ALBUM:相簿。
  • EXTRA_MEDIA_ARTIST:藝人。
  • "android.intent.extra.genre":類型。
  • EXTRA_MEDIA_TITLE (必要):歌名。
  • QUERY (必要):包含專輯、演出者、類型或標題的任意組合的字串。為顧及回溯相容性,系統一律會提供這項額外項目。現有應用程式如不知道搜尋模式,可將這項意圖視為非結構化搜尋。

播放清單 - Audio.Playlists.ENTRY_CONTENT_TYPE

播放符合額外額外條件指定條件的特定播放清單或播放清單。

其他額外內容:

  • EXTRA_MEDIA_ALBUM:相簿。
  • EXTRA_MEDIA_ARTIST:藝人。
  • "android.intent.extra.genre":類型。
  • "android.intent.extra.playlist":播放清單。
  • EXTRA_MEDIA_TITLE:播放清單根據的歌曲名稱。
  • QUERY (必要):包含專輯、演出者、類型、播放清單或標題的任意組合的字串。為顧及回溯相容性,系統一律會提供這項額外項目。現有應用程式如不知道搜尋模式,可將這項意圖視為非結構化搜尋。

意圖範例:

如果使用者想收聽特定藝人的音樂,搜尋應用程式可能會產生下列意圖:

Kotlin

fun playSearchArtist(artist: String) {
    val intent = Intent(MediaStore.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH).apply {
        putExtra(MediaStore.EXTRA_MEDIA_FOCUS, MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE)
        putExtra(MediaStore.EXTRA_MEDIA_ARTIST, artist)
        putExtra(SearchManager.QUERY, artist)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void playSearchArtist(String artist) {
    Intent intent = new Intent(MediaStore.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH);
    intent.putExtra(MediaStore.EXTRA_MEDIA_FOCUS,
                    MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE);
    intent.putExtra(MediaStore.EXTRA_MEDIA_ARTIST, artist);
    intent.putExtra(SearchManager.QUERY, artist);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

意圖篩選器範例:

<activity ...>
    <intent-filter>
        <action android:name="android.media.action.MEDIA_PLAY_FROM_SEARCH" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

在活動中處理此意圖時,請檢查傳入的 Intent 中的 EXTRA_MEDIA_FOCUS 額外值,以判斷搜尋模式。活動識別出搜尋模式後,請讀取該搜尋模式的額外值。透過這項資訊,您的應用程式就可以在其廣告空間中執行搜尋,播放與搜尋查詢相符的內容。如以下範例所示。

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    ...
    if (intent.action.compareTo(MediaStore.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH) == 0) {

        val mediaFocus: String? = intent.getStringExtra(MediaStore.EXTRA_MEDIA_FOCUS)
        val query: String? = intent.getStringExtra(SearchManager.QUERY)

        // Some of these extras might not be available depending on the search mode.
        val album: String? = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ALBUM)
        val artist: String? = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ARTIST)
        val genre: String? = intent.getStringExtra("android.intent.extra.genre")
        val playlist: String? = intent.getStringExtra("android.intent.extra.playlist")
        val title: String? = intent.getStringExtra(MediaStore.EXTRA_MEDIA_TITLE)

        // Determine the search mode and use the corresponding extras.
        when {
            mediaFocus == null -> {
                // 'Unstructured' search mode (backward compatible)
                playUnstructuredSearch(query)
            }
            mediaFocus.compareTo("vnd.android.cursor.item/*") == 0 -> {
                if (query?.isNotEmpty() == true) {
                    // 'Unstructured' search mode.
                    playUnstructuredSearch(query)
                } else {
                    // 'Any' search mode.
                    playResumeLastPlaylist()
                }
            }
            mediaFocus.compareTo(MediaStore.Audio.Genres.ENTRY_CONTENT_TYPE) == 0 -> {
                // 'Genre' search mode.
                playGenre(genre)
            }
            mediaFocus.compareTo(MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE) == 0 -> {
                // 'Artist' search mode.
                playArtist(artist, genre)
            }
            mediaFocus.compareTo(MediaStore.Audio.Albums.ENTRY_CONTENT_TYPE) == 0 -> {
                // 'Album' search mode.
                playAlbum(album, artist)
            }
            mediaFocus.compareTo("vnd.android.cursor.item/audio") == 0 -> {
                // 'Song' search mode.
                playSong(album, artist, genre, title)
            }
            mediaFocus.compareTo(MediaStore.Audio.Playlists.ENTRY_CONTENT_TYPE) == 0 -> {
                // 'Playlist' search mode.
                playPlaylist(album, artist, genre, playlist, title)
            }
        }
    }
}

Java

protected void onCreate(Bundle savedInstanceState) {
    //...
    Intent intent = this.getIntent();
    if (intent.getAction().compareTo(MediaStore.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH) == 0) {

        String mediaFocus = intent.getStringExtra(MediaStore.EXTRA_MEDIA_FOCUS);
        String query = intent.getStringExtra(SearchManager.QUERY);

        // Some of these extras might not be available depending on the search mode.
        String album = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ALBUM);
        String artist = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ARTIST);
        String genre = intent.getStringExtra("android.intent.extra.genre");
        String playlist = intent.getStringExtra("android.intent.extra.playlist");
        String title = intent.getStringExtra(MediaStore.EXTRA_MEDIA_TITLE);

        // Determine the search mode and use the corresponding extras.
        if (mediaFocus == null) {
            // 'Unstructured' search mode (backward compatible).
            playUnstructuredSearch(query);

        } else if (mediaFocus.compareTo("vnd.android.cursor.item/*") == 0) {
            if (query.isEmpty()) {
                // 'Any' search mode.
                playResumeLastPlaylist();
            } else {
                // 'Unstructured' search mode.
                playUnstructuredSearch(query);
            }

        } else if (mediaFocus.compareTo(MediaStore.Audio.Genres.ENTRY_CONTENT_TYPE) == 0) {
            // 'Genre' search mode.
            playGenre(genre);

        } else if (mediaFocus.compareTo(MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE) == 0) {
            // 'Artist' search mode.
            playArtist(artist, genre);

        } else if (mediaFocus.compareTo(MediaStore.Audio.Albums.ENTRY_CONTENT_TYPE) == 0) {
            // 'Album' search mode.
            playAlbum(album, artist);

        } else if (mediaFocus.compareTo("vnd.android.cursor.item/audio") == 0) {
            // 'Song' search mode.
            playSong(album, artist, genre, title);

        } else if (mediaFocus.compareTo(MediaStore.Audio.Playlists.ENTRY_CONTENT_TYPE) == 0) {
            // 'Playlist' search mode.
            playPlaylist(album, artist, genre, playlist, title);
        }
    }
}

新記事

建立記事是筆記應用程式的常見動作。建立意圖篩選器,宣傳應用程式執行這項動作的能力。請參考下一節的資訊。

建立記事

如要建立新筆記,請使用 ACTION_CREATE_NOTE 動作,並透過下列額外項目指定主旨和文字等附註詳細資料。

注意:應用程式必須先要求使用者確認,才能完成這項操作。

動作片
ACTION_CREATE_NOTE
資料 URI 配置
MIME 類型
PLAIN_TEXT_TYPE
"*/*"
額外內容
EXTRA_NAME
用於表示記事標題或主旨的字串。
EXTRA_TEXT
指出附註文字的字串。

意圖範例:

Kotlin

fun createNote(subject: String, text: String) {
    val intent = Intent(NoteIntents.ACTION_CREATE_NOTE).apply {
        putExtra(NoteIntents.EXTRA_NAME, subject)
        putExtra(NoteIntents.EXTRA_TEXT, text)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void createNote(String subject, String text) {
    Intent intent = new Intent(NoteIntents.ACTION_CREATE_NOTE)
            .putExtra(NoteIntents.EXTRA_NAME, subject)
            .putExtra(NoteIntents.EXTRA_TEXT, text);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

意圖篩選器範例:

<activity ...>
    <intent-filter>
        <action android:name="com.google.android.gms.actions.CREATE_NOTE" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="*/*" />
    </intent-filter>
</activity>

電話

撥打電話是手機應用程式的常見動作。建立意圖篩選器,宣傳應用程式執行這項動作的能力。請參考下一節的資訊。

撥打電話

如要開啟電話應用程式並撥打電話號碼,請使用 ACTION_DIAL 動作,並使用以下 URI 配置指定電話號碼。手機應用程式開啟後,會顯示電話號碼,而使用者須輕觸「Call」按鈕才能撥打電話。

Google 語音操作

  • 「撥打 555-5555」
  • "打電話老闆"
  • 「撥打語音信箱」

如要直接撥打電話,請使用 ACTION_CALL 動作,並使用以下 URI 配置指定電話號碼。手機應用程式開啟後,就會開始進行通話。使用者不需要輕觸「通話」按鈕。

ACTION_CALL 動作會要求您在資訊清單檔案中新增 CALL_PHONE 權限:

<uses-permission android:name="android.permission.CALL_PHONE" />
動作片
  • ACTION_DIAL - 開啟撥號應用程式或電話應用程式。
  • ACTION_CALL - 撥打電話 (需要 CALL_PHONE 權限)
資料 URI 配置
  • tel:<phone-number>
  • voicemail:<phone-number>
MIME 類型

有效的電話號碼請參閱 IETF RFC 3966 中的定義。有效的範例如下:

  • tel:2125551212
  • tel:(212) 555 1212

「電話」應用程式的撥號程式非常適合用於正規化配置,例如電話號碼。因此,Uri.parse() 方法中的說明並非絕對必要的。不過,如果您尚未嘗試或不確定能否處理配置,請改用 Uri.fromParts() 方法。

意圖範例:

Kotlin

fun dialPhoneNumber(phoneNumber: String) {
    val intent = Intent(Intent.ACTION_DIAL).apply {
        data = Uri.parse("tel:$phoneNumber")
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void dialPhoneNumber(String phoneNumber) {
    Intent intent = new Intent(Intent.ACTION_DIAL);
    intent.setData(Uri.parse("tel:" + phoneNumber));
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

以下是搜尋應用程式的常見動作,包括建立意圖篩選器來宣傳應用程式執行每個動作所需的資訊。

使用特定應用程式進行搜尋

Google 語音操作

  • 「在 myvideoapp 中搜尋貓咪影片」

如要在應用程式的結構定義中支援搜尋功能,請使用 SEARCH_ACTION 動作在應用程式中宣告意圖篩選器,如以下意圖篩選器範例所示。

注意:我們不建議使用 SEARCH_ACTION 進行應用程式搜尋。相反地,您必須實作 GET_THING 動作,以便利用 Google 助理內建的應用程式內搜尋功能支援。詳情請參閱 Google 助理的應用程式動作說明文件。

動作片
"com.google.android.gms.actions.SEARCH_ACTION"
支援透過 Google 語音操作的搜尋查詢。
額外內容
QUERY
包含搜尋查詢的字串。

意圖篩選器範例:

<activity android:name=".SearchActivity">
    <intent-filter>
        <action android:name="com.google.android.gms.actions.SEARCH_ACTION"/>
        <category android:name="android.intent.category.DEFAULT"/>
    </intent-filter>
</activity>

執行網頁搜尋

如要啟動網頁搜尋,請使用 ACTION_WEB_SEARCH 動作,並在 SearchManager.QUERY 額外項目中指定搜尋字串。

動作片
ACTION_WEB_SEARCH
資料 URI 配置
MIME 類型
額外內容
SearchManager.QUERY
搜尋字串。

意圖範例:

Kotlin

fun searchWeb(query: String) {
    val intent = Intent(Intent.ACTION_WEB_SEARCH).apply {
        putExtra(SearchManager.QUERY, query)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void searchWeb(String query) {
    Intent intent = new Intent(Intent.ACTION_WEB_SEARCH);
    intent.putExtra(SearchManager.QUERY, query);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

設定

當應用程式需要使用者進行變更時,如要在系統設定應用程式中開啟畫面,請使用下列其中一項意圖動作:

動作片
ACTION_SETTINGS
ACTION_WIRELESS_SETTINGS
ACTION_AIRPLANE_MODE_SETTINGS
ACTION_WIFI_SETTINGS
ACTION_APN_SETTINGS
ACTION_BLUETOOTH_SETTINGS
ACTION_DATE_SETTINGS
ACTION_LOCALE_SETTINGS
ACTION_INPUT_METHOD_SETTINGS
ACTION_DISPLAY_SETTINGS
ACTION_SECURITY_SETTINGS
ACTION_LOCATION_SOURCE_SETTINGS
ACTION_INTERNAL_STORAGE_SETTINGS
ACTION_MEMORY_CARD_SETTINGS

如需瞭解其他可用的設定畫面,請參閱 Settings 說明文件。

資料 URI 配置
MIME 類型

意圖範例:

Kotlin

fun openWifiSettings() {
    val intent = Intent(Settings.ACTION_WIFI_SETTINGS)
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void openWifiSettings() {
    Intent intent = new Intent(Settings.ACTION_WIFI_SETTINGS);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

發送簡訊

使用簡訊應用程式撰寫簡訊/多媒體訊息是常見的做法。 建立意圖篩選器,宣傳應用程式執行這項動作的能力。請參考下一節的資訊。

撰寫含有附件的簡訊/多媒體訊息

如要傳送簡訊或多媒體訊息,請使用下列其中一項意圖動作,並使用下列額外索引鍵指定訊息詳細資料,例如電話號碼、主旨和訊息內文。

動作片
ACTION_SENDTO
ACTION_SEND
ACTION_SEND_MULTIPLE
資料 URI 配置
sms:<phone_number>
smsto:<phone_number>
mms:<phone_number>
mmsto:<phone_number>

這些配置的處理方式都相同。

MIME 類型
"text/plain"
"image/*"
"video/*"
額外內容
"subject"
訊息主旨字串 (通常僅適用於多媒體訊息)。
"sms_body"
簡訊字串。
EXTRA_STREAM
Uri,指向要附加的圖片或影片。如果使用 ACTION_SEND_MULTIPLE 動作,這項額外項目就會是 Uri 物件的 ArrayList,指向要附加的圖片或影片。

意圖範例:

Kotlin

fun composeMmsMessage(message: String, attachment: Uri) {
    val intent = Intent(Intent.ACTION_SENDTO).apply {
        type = HTTP.PLAIN_TEXT_TYPE
        putExtra("sms_body", message)
        putExtra(Intent.EXTRA_STREAM, attachment)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void composeMmsMessage(String message, Uri attachment) {
    Intent intent = new Intent(Intent.ACTION_SENDTO);
    intent.setType(HTTP.PLAIN_TEXT_TYPE);
    intent.putExtra("sms_body", message);
    intent.putExtra(Intent.EXTRA_STREAM, attachment);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

如要確保意圖只由文字訊息應用程式處理,而非其他電子郵件或社交應用程式,請使用 ACTION_SENDTO 動作並加入 "smsto:" 資料配置,如以下範例所示:

Kotlin

fun composeMmsMessage(message: String, attachment: Uri) {
    val intent = Intent(Intent.ACTION_SEND).apply {
        data = Uri.parse("smsto:")  // Only SMS apps respond to this.
        putExtra("sms_body", message)
        putExtra(Intent.EXTRA_STREAM, attachment)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void composeMmsMessage(String message, Uri attachment) {
    Intent intent = new Intent(Intent.ACTION_SEND);
    intent.setData(Uri.parse("smsto:"));  // Only SMS apps respond to this.
    intent.putExtra("sms_body", message);
    intent.putExtra(Intent.EXTRA_STREAM, attachment);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

意圖篩選器範例:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <data android:type="text/plain" />
        <data android:type="image/*" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

注意:如果您開發的是簡訊/多媒體訊息應用程式,則必須針對其他動作實作意圖篩選器,以做為 Android 4.4 以上版本的預設簡訊應用程式使用。詳情請參閱 Telephony 的說明文件。

網路瀏覽器

載入網址是網路瀏覽器應用程式的常見動作。 建立意圖篩選器,宣傳應用程式執行這項動作的能力。請參考下一節的資訊。

載入網址

Google 語音操作

  • 「開啟 example.com」

如要開啟網頁,請使用 ACTION_VIEW 動作,並在意圖資料中指定網址。

動作片
ACTION_VIEW
資料 URI 配置
http:<URL>
https:<URL>
MIME 類型
"text/plain"
"text/html"
"application/xhtml+xml"
"application/vnd.wap.xhtml+xml"

意圖範例:

Kotlin

fun openWebPage(url: String) {
    val webpage: Uri = Uri.parse(url)
    val intent = Intent(Intent.ACTION_VIEW, webpage)
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void openWebPage(String url) {
    Uri webpage = Uri.parse(url);
    Intent intent = new Intent(Intent.ACTION_VIEW, webpage);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

意圖篩選器範例:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <!-- Include the host attribute if you want your app to respond
             only to URLs with your app's domain. -->
        <data android:scheme="http" android:host="www.example.com" />
        <category android:name="android.intent.category.DEFAULT" />
        <!-- The BROWSABLE category is required to get links from web pages. -->
        <category android:name="android.intent.category.BROWSABLE" />
    </intent-filter>
</activity>

提示:如果您的 Android 應用程式提供與網站類似的功能,請針對指向您網站的網址加入意圖篩選器。接著,如果使用者已安裝您的應用程式,他們透過電子郵件或其他指向您網站的網頁的連結都會開啟您的 Android 應用程式,而不是網頁。詳情請參閱「處理 Android 應用程式連結」一文。

從 Android 12 (API 級別 31) 開始,只有在應用程式獲準用於該網路意圖中的特定網域時,一般網路意圖才會解析為應用程式中的活動。如果您的應用程式未獲準使用網域,網路意圖會改為解析使用者的預設瀏覽器應用程式。

使用 Android Debug Bridge 驗證意圖

如要驗證應用程式是否回應您要支援的意圖,可以使用 adb 工具,按照以下步驟觸發特定意圖:

  1. 設定要開發的 Android 裝置,或使用虛擬裝置
  2. 安裝可處理所需意圖的應用程式版本。
  3. 使用 adb 觸發意圖:
    adb shell am start -a <ACTION> -t <MIME_TYPE> -d <DATA> \
      -e <EXTRA_NAME> <EXTRA_VALUE> -n <ACTIVITY>
    

    例如:

    adb shell am start -a android.intent.action.DIAL \
      -d tel:555-5555 -n org.example.MyApp/.MyActivity
    
  4. 如果您定義了所需的意圖篩選器,請處理意圖。

詳情請參閱「問題殼層指令」一文。