Android

Android ShortcutManager 使用指南

QuibblerQuibbler 2026-03-06 约 18 分钟 570 次阅读

Android ShortcutManager 使用指南

ShortcutManager 是 Android 7.1+ 系统中提供的快捷方式管理工具，允许应用创建和管理三种类型的快捷方式：静态快捷方式、动态快捷方式和固定快捷方式。这些快捷方式可以显著提升用户体验，让用户快速访问应用的核心功能。

1、ShortcutManager 概述


1.1、三种快捷方式类型

静态快捷方式：在 XML 文件中定义，随 APK 发布，应用更新后才能修改。适用于应用的核心功能，如"新建消息"、"搜索"等。

动态快捷方式：由应用在运行时通过代码发布，可以动态添加、更新或删除。适用于"最近联系人"、"常用功能"等需要实时更新的场景。

固定快捷方式：用户手动确认后，"钉"在主屏幕上的图标，类似于桌面图标。用户可以自由添加或删除。


1.2、添加依赖

ShortcutManager 包含在 AndroidX Core 库中，通常新建项目时已默认包含。在模块级的 build.gradle 文件中加入以下代码：

dependencies {
    // ShortcutManager 包含在 AndroidX Core 库中
    implementation "androidx.core:core:1.15.0"
}


2、静态快捷方式


2.1、创建快捷方式配置文件

在 res/xml 目录下新建 shortcuts.xml 文件，定义静态快捷方式：

<?xml version="1.0" encoding="utf-8"?>
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
    <shortcut
        android:shortcutId="static_new_message"
        android:enabled="true"
        android:icon="@drawable/ic_new_message"
        android:shortcutShortLabel="@string/new_message_short"
        android:shortcutLongLabel="@string/new_message_long">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.example.app"
            android:targetClass="com.example.app.NewMessageActivity" />
        <categories android:name="android.shortcut.conversation" />
    </shortcut>

    <shortcut
        android:shortcutId="static_search"
        android:enabled="true"
        android:icon="@drawable/ic_search"
        android:shortcutShortLabel="@string/search_short"
        android:shortcutLongLabel="@string/search_long">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.example.app"
            android:targetClass="com.example.app.SearchActivity" />
        <categories android:name="android.shortcut.search" />
    </shortcut>
</shortcuts>


2.2、在 AndroidManifest 中注册

在 <activity> 标签内添加 <meta-data> 标签，引用快捷方式配置文件：

<activity
    android:name=".MainActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>

    <meta-data
        android:name="android.app.shortcuts"
        android:resource="@xml/shortcuts" />
</activity>


2.3、静态快捷方式属性说明

shortcutId：快捷方式的唯一标识符 enabled：快捷方式是否启用 icon：快捷方式图标 shortcutShortLabel：简短标签，限制在 10 个字符以内 shortcutLongLabel：长标签，限制在 25 个字符以内 intent：点击快捷方式后跳转的目标 Activity categories：快捷方式分类，用于系统分组


3、动态快捷方式


3.1、创建动态快捷方式

使用 ShortcutManager 的 setDynamicShortcuts() 方法创建动态快捷方式：

fun createDynamicShortcuts(context: Context) {
    val shortcutManager = context.getSystemService(ShortcutManager::class.java)

    val shortcut = ShortcutInfo.Builder(context, "dynamic_recent_contact")
        .setShortLabel("张三")
        .setLongLabel("联系张三")
        .setIcon(Icon.createWithResource(context, R.drawable.ic_contact))
        .setIntent(
            Intent(context, ChatActivity::class.java).apply {
                action = Intent.ACTION_VIEW
                putExtra("contact_id", "123")
            }
        )
        .build()

    shortcutManager?.setDynamicShortcuts(listOf(shortcut))
}


3.2、更新动态快捷方式

使用 updateShortcuts() 方法更新已存在的动态快捷方式：

fun updateDynamicShortcut(context: Context) {
    val shortcutManager = context.getSystemService(ShortcutManager::class.java)

    val updatedShortcut = ShortcutInfo.Builder(context, "dynamic_recent_contact")
        .setShortLabel("李四")
        .setLongLabel("联系李四")
        .setIcon(Icon.createWithResource(context, R.drawable.ic_contact))
        .setIntent(
            Intent(context, ChatActivity::class.java).apply {
                action = Intent.ACTION_VIEW
                putExtra("contact_id", "456")
            }
        )
        .build()

    shortcutManager?.updateShortcuts(listOf(updatedShortcut))
}


3.3、删除动态快捷方式

使用 removeDynamicShortcuts() 方法删除动态快捷方式：

fun removeDynamicShortcut(context: Context) {
    val shortcutManager = context.getSystemService(ShortcutManager::class.java)
    shortcutManager?.removeDynamicShortcuts(listOf("dynamic_recent_contact"))
}


3.4、获取动态快捷方式列表

使用 getDynamicShortcuts() 方法获取当前所有动态快捷方式：

fun getDynamicShortcuts(context: Context): List<ShortcutInfo> {
    val shortcutManager = context.getSystemService(ShortcutManager::class.java)
    return shortcutManager?.dynamicShortcuts ?: emptyList()
}


3.5、动态快捷方式数量限制

动态快捷方式有数量限制，不同 Android 版本限制不同：

  • Android 8.0+：最多 5 个

  • Android 7.1：最多 4 个

可以使用 getMaxDynamicShortcutCount() 方法获取当前设备的最大数量：

fun getMaxDynamicShortcutCount(context: Context): Int {
    val shortcutManager = context.getSystemService(ShortcutManager::class.java)
    return shortcutManager?.maxDynamicShortcutCount ?: 0
}


4、固定快捷方式


4.1、创建固定快捷方式

使用 requestPinShortcut() 方法创建固定快捷方式，需要用户手动确认：

fun createPinnedShortcut(context: Context) {
    val shortcutManager = context.getSystemService(ShortcutManager::class.java)

    if (shortcutManager?.isRequestPinShortcutSupported == true) {
        val shortcut = ShortcutInfo.Builder(context, "pinned_favorite")
            .setShortLabel("收藏")
            .setLongLabel("我的收藏")
            .setIcon(Icon.createWithResource(context, R.drawable.ic_favorite))
            .setIntent(
                Intent(context, FavoriteActivity::class.java).apply {
                    action = Intent.ACTION_VIEW
                }
            )
            .build()

        val pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(shortcut)

        val successReceiver = PendingIntent.getBroadcast(
            context,
            0,
            pinnedShortcutCallbackIntent,
            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
        )

        shortcutManager.requestPinShortcut(shortcut, successReceiver.intentSender)
    }
}


4.2、监听固定快捷方式结果

创建 BroadcastReceiver 监听固定快捷方式的结果：

class PinnedShortcutReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        if (intent.hasExtra(ShortcutManager.EXTRA_SHORTCUT_ID)) {
            val shortcutId = intent.getStringExtra(ShortcutManager.EXTRA_SHORTCUT_ID)
            if (shortcutId == "pinned_favorite") {
                Toast.makeText(context, "快捷方式已固定到主屏幕", Toast.LENGTH_SHORT).show()
            }
        }
    }
}

在 AndroidManifest 中注册 Receiver：

<receiver
    android:name=".PinnedShortcutReceiver"
    android:exported="true">
    <intent-filter>
        <action android:name="android.content.action.SHORTCUT_ADDED" />
    </intent-filter>
</receiver>


4.3、检查固定快捷方式支持

在创建固定快捷方式之前，需要检查设备是否支持：

fun isPinnedShortcutSupported(context: Context): Boolean {
    val shortcutManager = context.getSystemService(ShortcutManager::class.java)
    return shortcutManager?.isRequestPinShortcutSupported == true
}


ShortcutManager 提供了三种快捷方式类型，分别适用于不同的使用场景：

静态快捷方式：适合应用的核心功能，随 APK 发布 动态快捷方式：适合需要实时更新的功能，如最近联系人 固定快捷方式：适合用户常用的功能，需要用户手动确认

合理使用快捷方式可以显著提升用户体验，让用户更快速地访问应用的核心功能。在实际开发中，应该根据应用的特点和用户需求，选择合适的快捷方式类型。

相关推荐

精选
ViewPager和PagerAdapter、FragmentPagerAdapter、FragmentStatePager
Android

ViewPager和PagerAdapter、FragmentPagerAdapter、FragmentStatePager

ViewPager1、ViewPagerandroidx.viewpager.widget.ViewPager，Android中使用非常广泛的控件，可以说是APP必备：首次打开引导页、页面Banner广告等。常用方法：setAdapter() 设置适配器setOffscreenPageLimit() 设置缓存的页面个数,默认是 1setCurrentItem() 跳转到特定的页面setOnPage

# View
1.1k
获取Android内置WebView内核版本
Android

获取Android内置WebView内核版本

获取Android内置WebView内核版本竟然能遇到这样奇葩的事情，网页用的技术过于新颖，以至于只支持高版本Chromium内核的，低版本安卓系统中内置的内核版本较低，无法加载前端页面。1、设置查看在系统设置里 > 应用 > 应用管理 > 显示系统应用，查看WebView组件：2、页面查看通过WebView发起的网络请求，都会带上浏览器的UA，通常页面都可以通过UA判断浏览器的内核版本。这里有两

# View
1.1w
Android 14适配总结
Android

Android 14适配总结

Android 14适配总结毕业工作至今已经适配了三个Android大版本，从Android 11到Android 12、再到Android 13。2023年，Google即将推出的Android 14，上半年已经开始第一批适配。现在，第四个Android版本已经适配完，总结记录一下。1、Android 14计划Google一般会在2月份对外发布预告，同时放出开发者预览版。“拉通”各大平台、厂商以

1.1w