常见 intent

借助 intent,您可以通过在 Intent 对象中描述您想执行的操作(如“查看地图”或“拍摄照片”)来启动另一个应用中的 activity。这种 intent 称作隐式 intent,因为它并不指定要启动的应用组件,而是指定一项操作并提供执行该操作所需的一些数据

当您调用 startActivity()startActivityForResult() 并向其传递隐式 intent 时,系统会将 intent 解析为可处理该 intent 的应用,并启动其对应的 Activity。如果有多个应用可处理 intent,系统会为用户显示一个对话框,供其选择要使用的应用。

本页介绍了几种可用于执行常见操作的隐式 intent,按处理 intent 的应用类型分成不同部分。此外,每个部分还介绍了如何创建 intent 过滤器来公布您的应用执行相应操作的能力。

注意:如果设备上没有可接收隐式 intent 的应用,应用在调用 startActivity() 时会崩溃。如需首先验证是否存在可接收 intent 的应用,请对 Intent 对象调用 resolveActivity()。如果结果为非 null,则至少有一个应用能够处理该 intent,可以安全调用 startActivity()。如果结果为 null,请勿使用该 intent,并尽可能停用调用该 intent 的功能。

如果您不熟悉如何创建 intent 或 intent 过滤器,请先阅读 intent 和 intent 过滤器

如需了解如何从开发主机触发本页面上所列的 intent,请参阅使用 Android 调试桥验证 intent 部分。

Google Voice Actions

Google 语音操作会触发本页面上所列的一些 Intent 来响应语音指令。如需了解详情,请参阅 系统语音指令使用入门

闹钟

以下是闹钟应用的常见操作,包括创建 intent 过滤器以公布应用执行每项操作的能力所需的信息。

创建闹铃

Google 语音操作

  • “设置一个早上 7 点的闹钟”

如需创建新的闹钟,请使用 ACTION_SET_ALARM 操作,并使用以下 extra 指定闹钟详细信息(如时间和消息)。

注意:搭载 Android 2.3(API 级别 9)及更低版本的设备只提供小时、分钟和内容 extra。其他 extra 可在更高版本的平台上使用。

操作
ACTION_SET_ALARM
数据 URI
MIME 类型
Extra
EXTRA_HOUR
闹钟的小时。
EXTRA_MINUTES
闹钟的分钟数。
EXTRA_MESSAGE
用于标识闹钟的自定义消息。
EXTRA_DAYS
一个 ArrayList,包含此闹钟会在每周的哪几天重复。每一天都必须使用 Calendar 类中的某个整型值(如 MONDAY)进行声明。

对于一次性闹钟,无需指定此 extra。

EXTRA_RINGTONE
一个 content: URI,用于指定闹铃使用的铃声,也可指定 VALUE_RINGTONE_SILENT 以不使用铃声。

如需使用默认铃声,请勿指定此 extra。

EXTRA_VIBRATE
一个布尔值,用于指定此闹钟是否振动。
EXTRA_SKIP_UI
一个布尔值,用于指定响应闹铃的应用在设置闹铃时是否必须跳过其界面。 如果为 true,则应用必须跳过任何确认界面并设置指定的闹钟。

intent 示例

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 intent,您的应用必须具有 SET_ALARM 权限:

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

intent 过滤器示例

<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 操作并使用以下 extra 指定持续时间等计时器详细信息。

注意:此 intent 在 Android 4.4(API 级别 19)及更高版本中提供。

操作
ACTION_SET_TIMER
数据 URI
MIME 类型
Extra
EXTRA_LENGTH
计时器的时长(以秒为单位)。
EXTRA_MESSAGE
用于标识计时器的自定义消息。
EXTRA_SKIP_UI
一个布尔值,用于指定响应计时器的应用在设置计时器时是否必须跳过其界面。 如果为 true,则应用必须跳过任何确认界面并启动指定的计时器。

示例 intent

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 intent,您的应用必须具有 SET_ALARM 权限:

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

intent 过滤器示例

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

显示所有闹钟

要显示闹钟列表,请使用 ACTION_SHOW_ALARMS 操作。

尽管调用此 intent 的应用并不多(使用它的主要是系统应用),但任何充当闹钟的应用都可以实现此 intent 过滤器,并通过显示现有闹铃列表作出响应。

注意:此 intent 在 Android 4.4(API 级别 19)及更高版本中提供。

操作
ACTION_SHOW_ALARMS
数据 URI
MIME 类型

intent 过滤器示例

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

日历

添加活动是日历应用的一项常见操作。使用下一部分中的信息创建 intent 过滤器,以便声明您的应用能够执行此操作。

添加日历活动

如需向用户的日历添加新事件,请使用 ACTION_INSERT 操作并使用 Events.CONTENT_URI 指定数据 URI。然后,您就可以使用以下 extra 指定事件的各类详细信息。

操作
ACTION_INSERT
数据 URI
Events.CONTENT_URI
MIME 类型
"vnd.android.cursor.dir/event"
Extra
EXTRA_EVENT_ALL_DAY
一个布尔型值,指定此事件是否为全天事件。
EXTRA_EVENT_BEGIN_TIME
事件的开始时间(从公元纪年开始计算的毫秒数)。
EXTRA_EVENT_END_TIME
事件的结束时间(从公元纪年开始计算的毫秒数)。
TITLE
活动标题。
DESCRIPTION
事件说明。
EVENT_LOCATION
活动地点。
EXTRA_EMAIL
以逗号分隔的受邀者电子邮件地址列表。

可使用 CalendarContract.EventsColumns 类中定义的常量指定许多其他事件详细信息。

intent 示例

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

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>

相机

以下是相机应用的常见操作,包括创建 intent 过滤器以公布应用执行每项操作的能力所需的信息。

拍摄照片或视频并将其返回给相关应用

如需打开相机应用并接收拍摄的照片或视频,请使用 ACTION_IMAGE_CAPTUREACTION_VIDEO_CAPTURE 操作。此外,还可在 EXTRA_OUTPUT extra 中指定您希望相机将照片或视频保存到的 URI 位置。

操作
ACTION_IMAGE_CAPTURE
ACTION_VIDEO_CAPTURE
数据 URI 架构
MIME 类型
Extra
EXTRA_OUTPUT
相机应用保存照片或视频文件的 URI 位置(以 Uri 对象形式)。

当相机应用成功将焦点返回到您的 activity 时(换句话说,您的应用收到 onActivityResult() 回调),您可以通过使用 EXTRA_OUTPUT 值指定的 URI 访问照片或视频。

注意:当您使用 ACTION_IMAGE_CAPTURE 拍照时,相机可能还会在结果 Intent 中返回缩小后的照片副本(即缩略图),并将其保存为 Bitmap 并保存到名为 "data" 的 extra 字段中。

intent 示例

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)或更高版本中执行此操作,请参阅以下 intent 示例。

示例 intent

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>

如需详细了解如何使用此 intent 拍摄照片,包括如何为输出位置创建适当的 Uri,请参阅拍摄照片拍摄视频

intent 过滤器示例

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

处理此 intent 时,请让 activity 检查传入 Intent 中有无 EXTRA_OUTPUT extra,然后将拍摄的图片或视频保存在该 extra 指定的位置,并调用带 IntentsetResult(),该 Intent 将经过压缩的缩略图包含在名为 "data" 的 extra 中。

以静态图像模式启动相机应用

Google 语音操作

  • “拍摄照片”

要以静态图像模式打开相机应用,请使用 INTENT_ACTION_STILL_IMAGE_CAMERA 操作。

操作
INTENT_ACTION_STILL_IMAGE_CAMERA
数据 URI 架构
MIME 类型
Extra

intent 示例

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

intent 过滤器示例

<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 类型
Extra

intent 示例

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

intent 过滤器示例

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

“通讯录/人员”应用

以下是联系人管理应用的常见操作,包括创建 intent 过滤器以宣传应用能够执行每项操作所需的信息。

选择联系人

如需让用户选择联系人和为您的应用提供对所有联系人信息的访问权限,请使用 ACTION_PICK 操作,并将 MIME 类型指定为 Contacts.CONTENT_TYPE

传送至您的 onActivityResult() 回调的结果 Intent 包含指向所选联系人的 content: URI。响应会利用 Contacts Provider API 向您的应用授予读取该联系人的临时权限,即使您的应用不具备 READ_CONTACTS 权限也是如此。

提示:如果您只需要访问某一条联系人信息(如电话号码或电子邮件地址),请改为参见下一节中如何选择特定联系人数据的内容。

操作
ACTION_PICK
数据 URI 架构
MIME 类型
Contacts.CONTENT_TYPE

示例 intent

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 后检索联系人详情,请参阅检索联系人详情

使用此 intent 检索联系人 URI 时,您通常不需要 READ_CONTACTS 权限即可读取该联系人的基本详细信息,例如显示名称和联系人是否已加星标。但是,如果您尝试读取指定联系人的更多具体数据(例如其电话号码或电子邮件地址),则需要 READ_CONTACTS 权限。

选择特定联系人数据

如需让用户从某位联系人选择某条特定信息(例如电话号码、电子邮件地址或其他数据类型),请使用 ACTION_PICK 操作并将 MIME 类型指定为以下内容类型之一(例如,使用 CommonDataKinds.Phone.CONTENT_TYPE 来获取联系人的电话号码)。

注意 :在许多情况下,您的应用需要具有 READ_CONTACTS 权限才能查看特定联系人的具体信息。

如果您只需从联系人中检索一种类型的数据,那么与使用 Contacts.CONTENT_TYPE 相比,使用 ContactsContract.CommonDataKinds 类中的 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 值中的一个。

intent 示例

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 作为 intent 数据指定联系人。

初次检索联系人 URI 的方法有两种:

  • 使用上一部分中所示的 ACTION_PICK 操作返回的联系人 URI。此方法不需要任何应用权限。
  • 直接访问所有联系人的列表,如检索联系人列表中所述。此方法需要 READ_CONTACTS 权限。
操作
ACTION_VIEW
数据 URI 架构
content:<URI>
MIME 类型
无。该类型是从联系人 URI 推断得出。

示例 intent

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 作为 intent 数据指定联系人,并将 extra 中由 ContactsContract.Intents.Insert 中的常量指定的任何已知联系人信息包括在内。

初次检索联系人 URI 的方法主要有两种:

  • 使用上一部分中显示的 ACTION_PICK 操作返回的联系人 URI。此方法不需要任何应用权限。
  • 直接访问所有联系人的列表,如检索联系人列表中所述。此方法需要 READ_CONTACTS 权限。
操作
ACTION_EDIT
数据 URI 架构
content:<URI>
MIME 类型
该类型是从联系人 URI 推断得出。
Extra
ContactsContract.Intents.Insert 中定义的一个或多个 extra,用于填充联系人详细信息的字段。

intent 示例

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

如需详细了解如何修改联系人,请参阅使用 intent 修改联系人

插入联系人

如需插入新联系人,请使用 ACTION_INSERT 操作,将 Contacts.CONTENT_TYPE 指定为 MIME 类型,并将 extra 中由 ContactsContract.Intents.Insert 中的常量指定的任何已知联系人信息包括在内。

操作
ACTION_INSERT
数据 URI 架构
MIME 类型
Contacts.CONTENT_TYPE
Extra
ContactsContract.Intents.Insert 中定义的一个或多个 extra。

intent 示例

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

如需详细了解如何插入联系人,请参阅使用 intent 修改联系人

电子邮件

撰写包含可选附件的电子邮件是电子邮件应用的常见操作。使用下一部分中的信息创建 intent 过滤器,以便声明您的应用能够执行此操作。

撰写带有可选附件的电子邮件

如需撰写电子邮件,请根据其是否包括附件使用以下其中一项操作,并使用下列 extra 键加入收件人和主题等电子邮件详情。

操作
ACTION_SENDTO(不带附件)或
ACTION_SEND(一个附件)或
ACTION_SEND_MULTIPLE(多个附件)
数据 URI 架构
MIME 类型
"text/plain"
"*/*"
Extra
Intent.EXTRA_EMAIL
包含所有“收件人”收件人电子邮件地址的字符串数组。
Intent.EXTRA_CC
包含所有“抄送”收件人电子邮件地址的字符串数组。
Intent.EXTRA_BCC
包含所有“密送”收件人电子邮件地址的字符串数组。
Intent.EXTRA_SUBJECT
包含电子邮件主题的字符串。
Intent.EXTRA_TEXT
包含电子邮件正文的字符串。
Intent.EXTRA_STREAM
指向附件的 Uri。 如果使用的是 ACTION_SEND_MULTIPLE 操作,则应将其改为包含多个 Uri 对象的 ArrayList

intent 示例

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

如果您想确保 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);
    }
}

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>

文件存储空间

以下是文件存储应用的常见操作,包括创建 intent 过滤器以通告应用执行各项操作的能力所需的信息。

检索特定类型的文件

要请求用户选择文档或照片等文件并向您的应用返回引用,请使用 ACTION_GET_CONTENT 操作并指定所需的 MIME 类型。返回给应用的文件引用对 Activity 当前生命周期而言是临时引用,因此如果您之后想访问该文件,则必须导入可之后读取的副本。

用户还可利用此 intent 在进程中创建新文件。例如,用户可以不选择现有照片,而是用相机拍摄新照片。

传送至您的 onActivityResult() 方法的结果 intent 包括的数据具有指向该文件的 URI。该 URI 可以是任何类型,如 http: URI、file: URI 或 content: URI。不过,如果您想将可选择的文件限定为可从内容提供程序 (content: URI) 访问的文件,以及通过 openFileDescriptor() 以文件流形式提供的文件,请为 intent 添加 CATEGORY_OPENABLE 类别。

在 Android 4.3(API 级别 18)及更高版本上,您还可以通过为 intent 添加 EXTRA_ALLOW_MULTIPLE 并将其设置为 true,允许用户选择多个文件。然后,您就可以在 getClipData() 返回的 ClipData 对象中访问每一个选定的文件。

操作
ACTION_GET_CONTENT
数据 URI 架构
MIME 类型
与用户需要选择的文件类型对应的 MIME 类型。
Extra
EXTRA_ALLOW_MULTIPLE
一个布尔值,声明用户是否可以一次选择多个文件。
EXTRA_LOCAL_ONLY
一个布尔型值,声明是否返回的文件必须直接存在于设备上,而不是需要从远程服务下载。
类别(可选)
CATEGORY_OPENABLE
仅返回可通过 openFileDescriptor() 以文件流形式表示的“可打开”文件。

用于获取照片的示例 intent

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

用于返回照片的示例 intent 过滤器

<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 intent 允许用户选择他们想在哪里创建新 PDF 文档(例如在另一个管理文档存储的应用内),而不是从现有文档中进行选择。然后,应用会收到它可以写入新文档的 URI 位置。

虽然从 ACTION_GET_CONTENT 操作传递给 onActivityResult() 方法的 intent 可能会返回任何类型的 URI,但来自 ACTION_OPEN_DOCUMENTACTION_CREATE_DOCUMENT 的结果 intent 始终将所选文件指定为 DocumentsProvider 支持的 content: URI。您可以使用 openFileDescriptor() 打开该文件,并使用 DocumentsContract.Document 中的列查询其详细信息。

返回的 URI 会为您的应用授予对文件的长期读取权限,还可能会授予写入权限。如果您想读取现有文件而不将其副本导入您的应用,或者您想就地打开和编辑文件,ACTION_OPEN_DOCUMENT 操作特别适用。

您还可以通过向 intent 添加 EXTRA_ALLOW_MULTIPLE 并将其设置为 true 来允许用户选择多个文件。如果用户只选择一项,您就可以从 getData() 检索该项目。如果用户选择多项,getData() 会返回 null,而您必须改为从 getClipData() 返回的 ClipData 对象中检索各项。

注意:您的 intent 必须指定 MIME 类型,并且必须声明 CATEGORY_OPENABLE 类别。必要时,您可以使用 EXTRA_MIME_TYPES extra 添加一个 MIME 类型数组来指定多个 MIME 类型;如果您这样做,必须将 setType() 中的主 MIME 类型设置为 "*/*"

操作
ACTION_OPEN_DOCUMENT
ACTION_CREATE_DOCUMENT
数据 URI 架构
MIME 类型
与用户需要选择的文件类型对应的 MIME 类型。
Extra
EXTRA_MIME_TYPES
与您的应用请求的文件类型对应的 MIME 类型数组。使用此 extra 时,必须将 setType() 中的主要 MIME 类型设置为 "*/*"
EXTRA_ALLOW_MULTIPLE
一个布尔值,声明用户是否可以一次选择多个文件。
EXTRA_TITLE
供与 ACTION_CREATE_DOCUMENT 配合使用,用于指定初始文件名。
EXTRA_LOCAL_ONLY
一个布尔型值,声明是否返回的文件必须直接存在于设备上,而不是需要从远程服务下载。
类别
CATEGORY_OPENABLE
仅返回可通过 openFileDescriptor() 以文件流形式表示的“可打开”文件。

用于获取照片的示例 intent

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 操作响应 intent。而是由系统接收此 Intent,并在统一界面中显示各类应用提供的所有文件。

如需在该界面中提供应用的文件,并允许其他应用打开这些文件,您必须实现 DocumentsProvider 并加入一个 PROVIDER_INTERFACE intent 过滤器 ("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>

如需详细了解如何实现从其他应用打开您的应用管理的文件,请参阅使用存储访问框架打开文件

本地操作

叫车是一项常见的本地操作。使用下一部分中的信息创建 intent 过滤器,以便声明您的应用能够执行此操作。

叫车

Google 语音操作

  • “给我叫辆出租车”
  • “给我叫辆车”

(仅适用于 Wear OS)

如需叫一台出租车,请使用 ACTION_RESERVE_TAXI_RESERVATION 操作。

注意:应用必须请求用户确认,然后才能执行此操作。

操作
ACTION_RESERVE_TAXI_RESERVATION
数据 URI
MIME 类型
Extra

intent 示例

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

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 地图

在地图上显示位置是地图应用的常见操作。 使用下一部分中的信息创建 intent 过滤器,以便声明您的应用能够执行此操作。

显示地图上的位置

如需打开地图,请使用 ACTION_VIEW 操作,并通过以下一种方案在 intent 数据中指定位置信息。

操作
ACTION_VIEW
数据 URI 架构
geo:latitude,longitude
显示给定经度和纬度处的地图。

示例:"geo:47.6,-122.3"

geo:latitude,longitude?z=zoom
按特定缩放级别显示给定经度和纬度处的地图。缩放级别为 1 时显示以指定纬度、经度为中心的全球地图。最高(最精确)缩放级别为 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 类型

intent 示例

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

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>

音乐或视频

以下是音乐和视频应用的常见操作,包括创建 intent 过滤器以通告应用执行每项操作的能力所需的信息。

播放媒体文件

要播放音乐文件,请使用 ACTION_VIEW 操作,并在 Intent 数据中指定文件的 URI 位置。

操作
ACTION_VIEW
数据 URI 架构
file:<URI>
content:<URI>
http:<URL>
MIME 类型
"audio/*"
"application/ogg"
"application/x-ogg"
"application/itunes"
或者您的应用需要的任何其他类型。

intent 示例

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

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 的《billie jean》”

要根据搜索查询播放音乐,请使用 INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH Intent。应用可能会触发此 intent 来响应用户的音乐播放语音命令。接收此 Intent 的应用会在其音乐库内搜索与指定查询匹配的现有内容,并在找到后开始播放该内容。

在此 intent 中,添加 EXTRA_MEDIA_FOCUS 字符串 extra,以指定预期的搜索模式。例如,搜索模式可指定搜索的是音乐人姓名还是歌曲名称。

操作
INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH
数据 URI 架构
MIME 类型
Extra
MediaStore.EXTRA_MEDIA_FOCUS(必需)

表示搜索模式:用户是否在寻找特定音乐人、专辑、歌曲或播放列表。大多数搜索模式都需要用到其他 extra。例如,如果用户想要收听某一首特定的歌曲,Intent 可能需要用到另外三个 extra:歌曲名称、音乐人和专辑。对于 EXTRA_MEDIA_FOCUS 的每个值,此 Intent 都支持下列搜索模式:

任意 - "vnd.android.cursor.item/*"

随机播放音乐。接收 intent 的应用会根据智能选择(如用户最后收听的播放列表)播放音乐。

其他 extra:

  • QUERY(必需):一个空字符串。始终提供此 extra,以实现向后兼容性。不了解搜索模式的现有应用可将此 intent 处理为非结构化搜索。

非结构化 - "vnd.android.cursor.item/*"

播放通过非结构化搜索查询找到的特定歌曲、专辑或类型。当应用无法识别用户想要收听的内容类型时,可以生成一个具有此搜索模式的 intent。尽可能使用更确切的搜索模式。

其他 extra:

  • QUERY(必需):一个包含艺术家、专辑、歌曲名称或类型任意组合的字符串。

类型 - Audio.Genres.ENTRY_CONTENT_TYPE

播放特定类型的音乐。

其他 extra:

  • "android.intent.extra.genre"(必需)- 类型。
  • QUERY(必需):类型。始终提供此 extra,以实现向后兼容性。不了解搜索模式的现有应用可将此 intent 作为非结构化搜索进行处理。

音乐人 - Audio.Artists.ENTRY_CONTENT_TYPE

播放特定艺术家的音乐。

其他 extra:

  • EXTRA_MEDIA_ARTIST(必填):音乐人。
  • "android.intent.extra.genre":类型。
  • QUERY(必需):一个包含艺术家或类型任意组合的字符串。始终提供此 extra,以实现向后兼容性。 不了解搜索模式的现有应用可将此 intent 作为非结构化搜索进行处理。

专辑 - Audio.Albums.ENTRY_CONTENT_TYPE

播放特定专辑的音乐。

其他 extra:

  • EXTRA_MEDIA_ALBUM(必需):影集。
  • EXTRA_MEDIA_ARTIST:音乐人。
  • "android.intent.extra.genre":类型。
  • QUERY(必需):包含专辑或音乐人的任意组合的字符串。始终提供此 extra,以实现向后兼容性。不了解搜索模式的现有应用可将此 intent 作为非结构化搜索进行处理。

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

播放特定歌曲。

其他 extra:

  • EXTRA_MEDIA_ALBUM:相册。
  • EXTRA_MEDIA_ARTIST:音乐人。
  • "android.intent.extra.genre":类型。
  • EXTRA_MEDIA_TITLE(必需):歌曲名称。
  • QUERY(必需):一个包含专辑、艺术家、类型或名称任意组合的字符串。始终提供此 extra,以实现向后兼容性。不了解搜索模式的现有应用可将此 intent 作为非结构化搜索进行处理。

播放列表 - Audio.Playlists.ENTRY_CONTENT_TYPE

播放特定播放列表或符合其他 extra 指定的某些条件的播放列表。

其他 extra:

  • EXTRA_MEDIA_ALBUM:相册。
  • EXTRA_MEDIA_ARTIST:音乐人。
  • "android.intent.extra.genre":类型。
  • "android.intent.extra.playlist":播放列表。
  • EXTRA_MEDIA_TITLE:播放列表所基于的歌曲名称。
  • QUERY(必需):一个包含专辑、艺术家、类型、播放列表或名称任意组合的字符串。始终提供此 extra,以实现向后兼容性。不了解搜索模式的现有应用可将此 intent 作为非结构化搜索进行处理。

intent 示例

如果用户想收听特定音乐人的音乐,搜索应用可生成以下 intent:

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

intent 过滤器示例

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

在您的 activity 中处理此 intent 时,请检查传入的 IntentEXTRA_MEDIA_FOCUS extra 的值以确定搜索模式。您的 activity 识别出搜索模式后,读取该特定搜索模式的其他 extra 的值。您的应用随后便可利用这些信息在其库存音乐内进行搜索,以播放与搜索查询匹配的内容。具体可见以下示例。

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

新建记事

创建记事是记事应用的常见操作。使用下一部分中的信息创建 intent 过滤器,以通告您的应用执行此操作的能力。

创建记事

如需创建新记事,请使用 ACTION_CREATE_NOTE 操作,并使用以下 extra 指定记事详细信息(如主题和正文)。

注意:应用必须请求用户确认,然后才能执行此操作。

操作
ACTION_CREATE_NOTE
数据 URI 架构
MIME 类型
PLAIN_TEXT_TYPE
"*/*"
Extra
EXTRA_NAME
一个表示笔记标题或主题的字符串。
EXTRA_TEXT
一个表示笔记正文的字符串。

intent 示例

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

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>

电话

发起通话是手机应用的常见操作。使用下一部分中的信息创建 intent 过滤器,以便声明您的应用能够执行此操作。

拨打电话

如需打开电话应用并拨打电话号码,请使用 ACTION_DIAL 操作,并使用以下 URI 架构指定电话号码。电话应用打开时会显示电话号码,用户必须点按拨打电话按钮才能开始通话。

Google 语音操作

  • “拨打 555-5555”
  • “打电话给 bob”
  • “发语音邮件”

如需直接拨打电话,请使用 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() 方法。

intent 示例

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

以下是搜索应用的常见操作,包括创建 intent 过滤器来宣传应用执行每项操作的能力所需的信息。

使用特定应用搜索

Google 语音操作

  • “在我的视频应用中搜索有关猫的视频”

如需支持在您的应用环境内进行搜索,请使用 SEARCH_ACTION 操作在您的应用中声明一个 intent 过滤器,如下文 intent 过滤器示例所示。

注意:我们不建议将 SEARCH_ACTION 用于应用搜索。 而是实现 GET_THING 操作,以便利用 Google 助理对应用内搜索的内置支持。如需了解详情,请参阅 Google 助理 App Actions 文档。

操作
"com.google.android.gms.actions.SEARCH_ACTION"
支持来自 Google 语音操作的搜索查询。
Extra
QUERY
包含搜索查询的字符串。

intent 过滤器示例

<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 extra 中指定搜索字符串。

操作
ACTION_WEB_SEARCH
数据 URI 架构
MIME 类型
Extra
SearchManager.QUERY
搜索字符串。

intent 示例

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

设置

如需在您的应用要求用户更改内容时打开系统“设置”应用中的某个界面,请使用以下某个 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 类型

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

在线聊天

撰写带附件的短信/彩信是短信应用的常见操作。 使用下一部分中的信息创建 intent 过滤器,以通告您的应用执行此操作的能力。

撰写带附件的短信/彩信

如需发起短信或彩信,请使用以下其中一个 intent 操作,并使用以下 extra 键指定电话号码、主题和消息正文等消息详情。

操作
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/*"
Extra
"subject"
表示消息主题的字符串(通常只适用于彩信)。
"sms_body"
表示消息正文的字符串。
EXTRA_STREAM
指向要附加的图片或视频的 Uri。如果使用 ACTION_SEND_MULTIPLE 操作,此 extra 是由 Uri 对象组成的 ArrayList,指向要附加的图片或视频。

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

如果您想确保 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);
    }
}

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>

注意:如果您要开发短信/彩信应用,必须为几项额外操作实现 intent 过滤器,才能在 Android 4.4 及更高版本上作为默认短信应用提供。如需了解详情,请参阅 Telephony 中的文档。

网络浏览器

加载网址是网络浏览器应用的常见操作。使用下一部分中的信息创建 intent 过滤器,以通告您的应用执行此操作的能力。

加载网址

Google 语音操作

  • “打开 example.com”

要打开网页,请使用 ACTION_VIEW 操作,并在 Intent 数据中指定网址。

操作
ACTION_VIEW
数据 URI 架构
http:<URL>
https:<URL>
MIME 类型
"text/plain"
"text/html"
"application/xhtml+xml"
"application/vnd.wap.xhtml+xml"

示例 intent

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

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 应用提供与您的网站相似的功能,请为指向您网站的网址添加一个 Intent 过滤器。之后,如果用户安装了您的应用,点击电子邮件或其他网页中指向您的网站的链接时,将会打开您的 Android 应用而不是您的网页。如需了解详情,请参阅处理 Android App Links

从 Android 12(API 级别 31)开始,仅当您的应用获准处理某个通用网络 intent 中包含的特定网域时,该网络 intent 才会解析为应用中的 activity。如果您的应用未获准用于该网域,该网络 intent 会解析为用户的默认浏览器应用。

使用 Android 调试桥验证 intent

如需验证应用是否会响应您想支持的 intent,您可以使用 adb 工具触发特定 intent,具体操作步骤如下:

  1. 设置一台用于开发的 Android 设备,或使用一台虚拟设备
  2. 安装一个处理您想支持的 Intent 的应用版本。
  3. 使用 adb 触发 intent:
    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. 如果您定义了必需的 intent 过滤器,请处理 intent。

如需了解详情,请参阅发出 shell 命令