意圖可讓您在 Intent
物件中描述要執行的動作,例如「查看地圖」或「拍照」,以便在其他應用程式中啟動活動。這類意圖稱為「隱式」意圖,因為它不會指定要啟動的應用程式元件,而是指定「動作」並提供執行動作的「資料」。
當您呼叫 startActivity()
或 startActivityForResult()
並傳遞隱含意圖時,系統會將意圖解析至可處理意圖的應用程式,並啟動對應的 Activity
。如果有多個應用程式可處理意圖,系統會向使用者顯示對話方塊,讓使用者選擇要使用的應用程式。
本頁說明幾個隱含意圖,方便您執行常用動作,並按照處理意圖的應用程式類型排列。每個部分也會說明如何建立意圖篩選器,宣傳應用程式執行動作的能力。
注意:如果裝置上沒有可接收隱含意圖的應用程式,應用程式在呼叫 startActivity()
時會當機。如要先確認有應用程式可接收意圖,請對 Intent
物件呼叫 resolveActivity()
。如果結果不是空值,至少會有一個應用程式可處理意圖,因此可以放心呼叫 startActivity()
。如果結果為空值,請不要使用意圖,並盡可能停用叫用意圖的功能。
如果您不熟悉如何建立意圖或意圖篩選器,請先參閱「意圖和意圖篩選器」。
如要瞭解如何從開發主機觸發本頁所列的意圖,請參閱「使用 Android Debug Bridge 驗證意圖」一節。
Google 語音操作
Google 語音指令會根據語音指令觸發此頁面所列的部分意圖。詳情請參閱「 開始使用系統語音動作」。
鬧鐘
以下是鬧鐘應用程式的常見動作,包括建立意圖篩選器所需的資訊,以便宣傳應用程式執行各項動作的能力。
建立鬧鐘
如要建立新的鬧鐘,請使用 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
- 此佈林值用於指定回應應用程式是否必須在設定鬧鐘時略過使用者介面。如果為 true,應用程式必須略過任何確認使用者介面,並設定指定的鬧鐘。
意圖範例:
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>
建立計時器
如要建立倒數計時器,請使用 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
- 事件的結束時間 (自紀元時間算起的毫秒數)。
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_CAPTURE
或 ACTION_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
中傳回縮小版本 (或縮圖),並以 "data"
命名的額外欄位儲存為 Bitmap
。
意圖範例:
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
額外項目,然後將擷取的圖片或影片儲存在該額外項目指定的位置,並使用 Intent
呼叫 setResult()
,該額外項目在名為 "data"
的額外項目中包含壓縮的縮圖。
在靜態影像模式下啟動相機應用程式
如要在靜態影像模式下開啟相機應用程式,請使用 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>
在影片模式下啟動相機應用程式
如要在影片模式下開啟相機應用程式,請使用 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。即使應用程式未包含 READ_CONTACTS
權限,回應也會授予應用程式臨時權限,讓應用程式可透過 Contacts Provider API 讀取該聯絡人。
提示:如果您只需要存取特定的聯絡資訊 (例如電話號碼或電子郵件地址),請參閱下一節,瞭解如何選取特定聯絡資料。
- 動態
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
更有效率,如前一個章節所示。您可以直接存取所需資料,而不需要對聯絡人供應商執行更複雜的查詢。
傳送至 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
- 所有「密件副本」收件者電子郵件地址的字串陣列。
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 supportsOpenableColumns
andContentResolver.openFileDescriptor()
. --> <category android:name="android.intent.category.OPENABLE" /> </intent-filter> </activity>
開啟特定類型的檔案
在 Android 4.4 以上版本上執行時,您可以使用 ACTION_OPEN_DOCUMENT
動作並指定 MIME 類型,要求開啟由其他應用程式管理的檔案,而非使用 ACTION_GET_CONTENT
動作擷取您必須匯入應用程式的檔案副本。如果您也想讓使用者建立可供應用程式寫入的新文件,請改用 ACTION_CREATE_DOCUMENT
動作。
舉例來說,ACTION_CREATE_DOCUMENT
意圖可讓使用者選取要建立新文件的位置,例如在管理文件儲存空間的其他應用程式中,而非選取現有的 PDF 文件。接著,應用程式會收到可寫入新文件的 URI 位置。
雖然從 ACTION_GET_CONTENT
動作傳送至 onActivityResult()
方法的意圖可能會傳回任何類型的 URI,但 ACTION_OPEN_DOCUMENT
和 ACTION_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
動作的意圖。而是會接收此意圖,並以整合式使用者介面顯示各個應用程式提供的所有檔案。
如要在這個 UI 中提供應用程式檔案,並讓其他應用程式開啟這些檔案,您必須實作 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>
如要進一步瞭解如何讓應用程式管理的檔案可透過其他應用程式開啟,請參閱「使用儲存空間存取架構開啟檔案」。
本地動作
叫車是常見的本地動作。使用下一節的資訊,建立意圖篩選器,通告應用程式能否執行這項動作。
叫計程車
如要叫車,請使用 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>
對應
在地圖上顯示位置是地圖應用程式常見的動作。請使用下列章節中的資訊建立意圖篩選器,宣告應用程式執行這項動作的能力。
在地圖上顯示位置
如要開啟地圖,請使用 ACTION_VIEW
動作,並使用下列任一配置,在意圖資料中指定位置資訊。
- 動態
ACTION_VIEW
- 資料 URI 配置
-
geo:latitude,longitude
- 以指定的經緯度顯示地圖。
示例:
"geo:47.6,-122.3"
geo:latitude,longitude?z=zoom
- 在特定縮放等級下,顯示指定經緯度的地圖。縮放等級為 1 時,系統會以指定的 lat、lng 為中心,顯示整個地球。最高 (最接近) 的縮放等級為 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>
根據搜尋查詢播放音樂
如要根據搜尋查詢播放音樂,請使用 INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH
意圖。應用程式可能會根據使用者的語音指令 (播放音樂) 觸發此意圖。接收此意圖的應用程式會在其廣告空間中執行搜尋作業,將現有內容與指定的查詢相符,然後開始播放該內容。
在這個意圖中,請加入 EXTRA_MEDIA_FOCUS
字串額外項目,指定所需搜尋模式。例如,搜尋模式可以指定搜尋要搜尋的是藝人名稱或歌曲名稱。
- 動態
INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH
- 資料 URI 配置
- 無
- MIME 類型
- 無
- 額外內容
-
MediaStore.EXTRA_MEDIA_FOCUS
(必填)-
指出搜尋模式:使用者是否正在尋找特定藝人、專輯、歌曲或播放清單。大部分的搜尋模式都會提供額外額外項目。舉例來說,如果使用者有意聆聽特定歌曲,該意圖可能會提供另外三種額外項目:歌名、藝人和專輯。這個意圖支援下列搜尋模式,適用於
EXTRA_MEDIA_FOCUS
的每個值:Any -
"vnd.android.cursor.item/*"
-
播放任何音樂。接收應用程式會根據智慧選擇播放部分音樂,例如使用者上次聆聽的播放清單。
其他額外福利:
QUERY
(必填):空字串。系統為了顧及回溯相容性,一律提供這個額外項目。現有的應用程式如果不瞭解搜尋模式,可以將此意圖視為非結構化搜尋來處理。
非結構化 -
"vnd.android.cursor.item/*"
-
從非結構化的搜尋查詢中播放特定歌曲、專輯或類型。如果應用程式無法識別使用者想聆聽的內容類型,就會使用這個搜尋模式產生意圖。盡可能使用更明確的搜尋模式。
其他額外項目:
QUERY
(必要):包含藝人、專輯、歌曲名稱或類型的任意組合字串。
-
播放特定類型的音樂。
其他額外項目:
"android.intent.extra.genre"
(必填) - 類型。QUERY
(必填):類型,為了回溯相容性,這個額外項目一律會提供。現有的應用程式如果不瞭解搜尋模式,可以將此意圖視為非結構化搜尋來處理。
-
播放特定藝人的音樂。
其他額外福利:
EXTRA_MEDIA_ARTIST
(必填):藝人。"android.intent.extra.genre"
:類型。QUERY
(必填):包含藝人或類型的任意組合字串。為了回溯相容性,這個額外項目一律會提供。現有的應用程式如果不瞭解搜尋模式,可以將此意圖視為非結構化搜尋來處理。
-
播放特定專輯中的音樂。
其他額外項目:
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
(必要):包含專輯、演出者、類型或標題的任意組合字串。為了回溯相容性,這個額外項目一律會提供。現有的應用程式如果不瞭解搜尋模式,可以將這個意圖視為非結構化搜尋來處理。
-
播放特定播放清單,或符合額外額外項目指定的某些條件的播放清單。
其他額外項目:
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
- 表示筆記文字的字串。
-
- 動態
-
ACTION_DIAL
:開啟撥號或電話應用程式。ACTION_CALL
- 撥打電話 (需要CALL_PHONE
權限)
- 資料 URI 配置
-
tel:<phone-number>
voicemail:<phone-number>
- MIME 類型
- 無
tel:2125551212
tel:(212) 555 1212
- 動態
-
"com.google.android.gms.actions.SEARCH_ACTION"
- 支援來自 Google Voice Actions 的搜尋查詢。
- 額外內容
-
QUERY
- 包含搜尋查詢的字串。
- 動態
ACTION_WEB_SEARCH
- 資料 URI 配置
- 無
- MIME 類型
- 無
- 額外內容
-
SearchManager.QUERY
- 搜尋字串。
- 動態
-
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 類型
- 無
- 動態
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
,指向要附加的圖片或影片。
- 動態
ACTION_VIEW
- 資料 URI 配置
http:<URL>
https:<URL>
- MIME 類型
-
"text/plain"
"text/html"
"application/xhtml+xml"
"application/vnd.wap.xhtml+xml"
- 設定用於開發的 Android 裝置,或使用虛擬裝置。
- 安裝可處理您要支援的意圖的應用程式版本。
- 使用
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
- 如果您已定義必要的意圖篩選器,請處理意圖。
意圖範例:
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」按鈕才能開始通話。
如要直接撥打電話,請使用 ACTION_CALL
動作,並使用下列 URI 配置指定電話號碼。開啟電話應用程式後,系統就會開始撥打電話。使用者不必輕觸「Call」按鈕。
ACTION_CALL
動作需要在資訊清單檔案中加入 CALL_PHONE
權限:
<uses-permission android:name="android.permission.CALL_PHONE" />
有效的電話號碼是指 IETF RFC 3966 中定義的電話號碼。有效範例包括:
電話應用程式的撥號程式擅長處理電話號碼等標準化方案。因此,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); } }
搜尋
以下是搜尋應用程式的常見動作,包括建立意圖篩選器所需的資訊,以便宣傳應用程式執行各項動作的能力。
使用特定應用程式搜尋
如要在應用程式內容中支援搜尋功能,請使用 SEARCH_ACTION
動作在應用程式中宣告意圖篩選器,如以下意圖篩選器範例所示。
注意:我們不建議使用 SEARCH_ACTION
進行應用程式搜尋。請改為實作 GET_THING
動作,運用 Google 助理內建的應用程式內搜尋功能。詳情請參閱 Google 助理的 應用程式動作說明文件。
意圖篩選器範例:
<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
額外資料中指定搜尋字串。
意圖範例:
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); } }
設定
如要在應用程式要求使用者變更某些內容時,在系統「設定」應用程式中開啟畫面,請使用下列其中一個意圖動作:
意圖範例:
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); } }
發送簡訊
撰寫含有附件的簡訊/多媒體訊息,是簡訊應用程式常見的動作。使用下一節的資訊,建立意圖篩選器,通告應用程式執行這項動作的能力。
撰寫含有附件的簡訊/多媒體訊息
如要啟動簡訊或多媒體訊息,請使用下列任一意圖動作,並使用下列額外鍵指定訊息詳細資料,例如電話號碼、主旨和訊息內文。
意圖範例:
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
的說明文件。
網路瀏覽器
載入網頁網址是網頁瀏覽器應用程式的常見動作。請使用下列章節中的資訊建立意圖篩選器,宣告應用程式執行這項動作的能力。
載入網址
如要開啟網頁,請使用 ACTION_VIEW
動作,並在意圖資料中指定網址。
意圖範例:
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
工具觸發特定意圖,方法如下:
詳情請參閱「發出殼層指令」。