『Android Tip』-- Shortcuts 快捷方式

开篇

Shortcuts 功能跟随着 Android7.1 Nougat 一块儿诞生，其主要目在于用户能够定义一些经常使用的操做路径，以快捷方式的形式存在，这些快捷方式展现在能够支持的设备上，帮助用户快速启动经常使用或者推荐的页面和行为。

最近也是有 Shortcut 相关的需求须要开发，特此进行了总结，但愿能够帮助到你们。ShortcutsDemo

概览

快捷方式通常是以两种方式存在：

一种经过 长按 应用 icon，此时会弹出列表弹窗，里面展现须要操做的路径，对于没有配置快捷方式的应用，通常只会展现分享或者应用信息的入口(不一样手机可能展现不同)。若是该应用配置了快捷方式，那么在列表中则会展现对应的快捷方式入口。

如上图所示，配置和没有配置快捷方式的区别就在于，列表中是否配置自定义的快捷方式入口。

另外一种则以桌面快捷方式的形式存在，同一种行为能够存在多个相同的桌面快捷方式。

如上图，对于 Chrome-打开新的标签页 这种行为能够有多个相同的桌面快捷方式。

Shortcuts 类型

每一个快捷方式均可以携带一个或多个 intent，当用户点击快捷方式时，每一个 intent 都会触发应用中对应的操做，通常快捷方式的建立类型取决于你具体快捷方式存在的形态和你想赋予他什么样的行为。能够如下面的例子做为参考：

• 在天气应用中，想查看最近几每天气的趋势
• 在电子邮件应用中，想建立新的电子邮件
• 在地图应用中，定位一个具体的位置
• 在聊天应用中，向指定好友发送信息
• 在媒体应用中，播放电视节目的下一集
• 在游戏应用中，加载游戏最后一个保存的时间点

... ...

你能够为你的应用发布如下类型的快捷方式‘

• 静态的快捷方式： 其直接会打包到 apk 或 apk bundle 中，安装完应用便存在快捷方式入口。
• 动态的快捷方式： 只有在应用运行时才会建立，能够随时的更新、添加和删除对应的快捷方式。
• 桌面快捷方式： 必须在用户受权的状况下，能够主动的添加快捷方式到桌面，一样能够拷贝动态和静态的快捷方式到桌面。

Shortcuts 限制条件

虽然对于一个应用程序通常能够建立五个快捷方式，其中包括静态和动态的，可是但多数的设备上只能展现 四个。

可是桌面快捷方式是不作限制的，不过桌面快捷方式非用户主动删除的话，是无法移除的，只能经过禁用的方式让该桌面快捷方式失效。

使用

快捷方式能够帮助用户快速访问经常使用的路径和页面，从而为用户提供特定类型的内容。代码以上传至 ShortcutsDemo

Shortcuts 类型选择

那该如何选择快捷方式类型，这取决你的快捷方式是应用驱动仍是用户驱动。虽然静态快捷方式意图不可更改，动态的可更改，可是这两种都是属于应用驱动。若是用户想自定义想要的意图，经过桌面快捷方式形式的展示，那这就是用户驱动。

怎么理解呢？用简书做为例子进行讲解：

• 静态快捷方式： 这种最适合那种在整个程序的生命周期中，意图不会改变,始完成整同一种行为。鉴于程序通常只能显示四个快捷方式，那静态的快捷方式通常对于那种比较常见的行为很是有用和有必要。

  例如上图简书中，像「搜索」入口就比较常见，不须要传递参数或传递的参数不会改变，那这种就建议使用静态快捷方式。

• 动态快捷方式： 这种通常对意图较为敏感的操做。意图可能在应用运行中发生改变，须要更新快捷方式。

  例如简书入口中的 「个人公开文章」，由于多帐号的缘由，可能切换帐号，那跳转的页面所携带的参数就会改变，快捷方式就须要更新，这种就须要使用静态快捷方式。

• 桌面快捷方式： 这种容许用户自定义跳转意图。

  例如简书支持将关注的人建立快捷方式到桌面，下次直接能够访问该人的动态信息，这种彻底是用户自发的建立，因此使用桌面快捷方式。

Shortcuts 类型建立

有了上述类型的具体描述，下面针对这三种快捷方式的建立进行例子介绍。

建立静态快捷方式

静态快捷方式提供应用程序内的通用跳转，这些通常在整个程序的生命周期内是保持不变的。

经过如下步骤完成静态快捷方式的建立：

1. 在 AndroidManifest.xml 中找到配置 android.intent.action.MAIN 和 android.intent.category.LAUNCHER 的 Activity。

2. 添加 <meta-data> 元素到 Activity 中

   <activity android:name=".MainActivity">
     <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>
   复制代码

3. 建立新的资源文件：res/xml/shortcuts.xml

   <?xml version="1.0" encoding="utf-8"?>
   <shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
       <shortcut android:enabled="true" android:icon="@drawable/add" android:shortcutDisabledMessage="@string/static_disabled_message" android:shortcutId="staticId" android:shortcutLongLabel="@string/static_shortcut_long_label" android:shortcutShortLabel="@string/static_shortcut_short_label">
           <intent android:action="android.intent.action.VIEW" android:data="content://xiaweizi.com/fromStaticShortcut" android:targetClass="com.example.xiaweizi.shortcutsdemo.TestActivity" android:targetPackage="com.example.xiaweizi.shortcutsdemo" />
           <categories android:name="android.shortcut.conversation" />
       </shortcut>
   </shortcuts>
   复制代码

具体参数配置说明以下：

标签名称	描述
android:shortcutId	shortcut 的惟一标识，更新删除都须要他最为关键字
android:shortcutShortLabel	描述快捷方式的简明短语，若是可能尽量控制为 10 个字符
android:shortcutLongLabel	描述快捷方式的扩展短语，若是空间足够会显示此值，尽量控制在 25 个字符
android:shortcutDisabledMessage	若是桌面快捷方式被禁用，点击会弹出此提示内容
android:enabled	控制桌面快捷方式是否被禁用
android:icon	快捷方式旁边的图标
android:action	intent 跳转的 action
android:targetPackage	跳转页面的包名
android:targetClass	跳转页面的完整路径

4. 若是有数据的传递，要有对应的解析

   if (getIntent().getData() != null && TextUtils.equals(getIntent().getAction(), Intent.ACTION_VIEW)) {
     Uri uri = getIntent().getData();
     List<String> pathSegments = uri.getPathSegments();
     if (pathSegments != null && pathSegments.size() > 0) {
       tvTest.setText(pathSegments.get(0));
     }
   }
   复制代码

最终的运行效果：

建立动态快捷方式

动态快捷方式提供向指向应用内特定的跳转或数据传递，这些跳转和数据可能会在应用执行中发生变化。

此时须要借助 ShortcutManager 提供的 API 来完成动态快捷方式的相应操做：

• 建立： 使用 setDynamicShortcuts() 从新定义动态快捷方式的完整列表
• 添加： 使用 addDynamicShortcut() 来扩充现有的动态快捷方式列表
• 更新： 使用 updateShortcuts() 方法进行更新现有的动态快捷方式列表
• 删除： 使用 removeDynamicShortcuts() 移除一组动态快捷方式，或者使用 removeAllDynamicShortcuts() 移除全部动态快捷方式

以建立为例，其余差很少，自行尝试，具体的操做可参考下面的代码：

1. 建立 ShortcutInfo 对象

   @TargetApi(Build.VERSION_CODES.N_MR1)
   private ShortcutInfo createShortcutInfo1() {
     return new ShortcutInfo.Builder(this, ID_DYNAMIC_1)
       .setShortLabel(getString(R.string.dynamic_shortcut_short_label1))
       .setLongLabel(getString(R.string.dynamic_shortcut_long_label1))
       .setIcon(Icon.createWithResource(this, R.drawable.add))
       .setIntent(new Intent(Intent.ACTION_VIEW, Uri.parse("http://xiaweizi.cn/")))
       .build();
   }
   复制代码

2. 调用 setDynamicShortcuts() 覆盖掉以前的，从新设置新的动态快捷方式列表

   private void setDynamicShortcuts() {
     if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.N_MR1) {
       ShortcutManager shortcutManager = getSystemService(ShortcutManager.class);
       List<ShortcutInfo> shortcutInfo = new ArrayList<>();
       shortcutInfo.add(createShortcutInfo1());
       shortcutInfo.add(createShortcutInfo2());
       if (shortcutManager != null) {
         shortcutManager.setDynamicShortcuts(shortcutInfo);
       }
     }
   }
   复制代码

3. 能够配置 label 的字体颜色

   @TargetApi(Build.VERSION_CODES.N_MR1)
   private ShortcutInfo createShortcutInfo2() {
     Intent intent = new Intent(this, TestActivity.class);
     intent.setAction(Intent.ACTION_VIEW);
     intent.putExtra("key", "fromDynamicShortcut");
     ForegroundColorSpan colorSpan = new ForegroundColorSpan(Color.BLUE);
     String label = getResources().getString(R.string.dynamic_shortcut_short_label2);
     SpannableStringBuilder colouredLabel = new SpannableStringBuilder(label);
     colouredLabel.setSpan(colorSpan, 0, label.length(), Spanned.SPAN_INCLUSIVE_INCLUSIVE);
     return new ShortcutInfo.Builder(this, ID_DYNAMIC_2)
       .setShortLabel(colouredLabel)
       .setLongLabel(getString(R.string.dynamic_shortcut_long_label2))
       .setIcon(Icon.createWithResource(this, R.drawable.link))
       .setIntent(intent)
       .build();
   }
   复制代码

最终的运行效果：

建立桌面快捷方式

在 Android 8.0（API26）或者更高的版本上，能够建立桌面快捷方式。与静态和动态快捷方式不一样，桌面快捷方式支持在设备上单独的 icon 展现。

若是想建立桌面快捷方式，按照如下步骤进行完成：

1. 使用 isRequestPinShortcutSupported() 来验证设备是否支持应用建立桌面快捷方式
2. 根据快捷方式是否已经存在，用下面两种方式之一来建立 ShortcutInfo 对象：
   1. 若是快捷方式已经存在，请建立仅包含现有快捷方式 id 的 ShortcutInfo 对象，系统自动查找并带上与快捷方式有关的全部相关数据
   2. 若是要固定新的快捷方式，请建立一个 ShortcutInfo 对象，其中包含新的快捷方式 id、意图和短标签
3. 尝试经过调用 requestPinShortcut() 将快捷方式固定到设备桌面上，在此过程当中，能够传入 pendingIntent 对象，该对象仅在快捷方式成功固定时告知应用。

具体的代码可参考下面：

private void createPinnedShortcuts() {
  if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O) {
    ShortcutManager shortcutManager = getSystemService(ShortcutManager.class);
    if (shortcutManager != null && shortcutManager.isRequestPinShortcutSupported()) {
      Intent intent = new Intent(this, TestActivity.class);
      intent.setAction(Intent.ACTION_VIEW);
      intent.putExtra("key", "fromPinnedShortcut");
      ShortcutInfo pinShortcutInfo = new ShortcutInfo.Builder(this, "my-shortcut")
        .setShortLabel(getString(R.string.pinned_shortcut_short_label2))
        .setLongLabel(getString(R.string.pinned_shortcut_long_label2))
        .setIcon(Icon.createWithResource(this, R.drawable.add))
        .setIntent(intent)
        .build();
      Intent pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(pinShortcutInfo);
      PendingIntent successCallback = PendingIntent.getBroadcast(this, 0,
                                                                 pinnedShortcutCallbackIntent, 0);
      boolean b = shortcutManager.requestPinShortcut(pinShortcutInfo, successCallback.getIntentSender());
      Utils.showToast(this, "set pinned shortcuts " + (b ? "success" : "failed") + "!");
    }
  }
}
复制代码

最终运行效果：

好了，基础简单的使用就介绍到这了，相信对 Shortcuts 的使用场景和具体实现都有必定的了解了，接下来开始介绍进阶的使用。

Shortcuts 进阶使用

快捷方式建立完成后，可能还须要对其进行管理，好比动态更新或者禁用某些快捷方式，此时就须要了解一些进阶的使用了。

移除 Shortcut

对于 静态快捷方式 而言，其在一开始就打包到了 apk 或者 apk bundle 中，是不容许对其进行更改的，除非发布新的版本覆盖掉以前的快捷方式，否则会一直存在。

对于 动态快捷方式 ，既然能够在代码中进行建立，一样也能够在代码中进行移除，这个以前也介绍过。

而对于 桌面快捷方式，它直接展现在桌面上，始终可见，仅在如下状况才能删除桌面快捷方式。

• 用户主动移除
• 卸载与快捷方式的应用
• 用户在应用信息中，清除所有的缓存数据

Shortcut 展现顺序

对于一个应用上全部的快捷方式，展现的规则按照如下顺序：

1. 静态快捷方式： isDeclaredInManifest() 放回 true 的快捷方式
2. 动态快捷方式：ShortcutInfo.isDynamic() 返回 true 的快捷方式

在每种快捷方式中，又会按照 ShortcutInfo.getRank() 按等级递增的顺序排序。等级是非负的，连续的整数， 调用 updateShortcuts(List)，addDynamicShortcuts(List) 或 setDynamicShortcuts(List) 时，能够更新现有快捷方式的等级。

排名是自动调整的，所以它们对于每种类型的快捷方式都是惟一的。 例如，有三个 rank 分别为 0、1和2 的动态快捷方式，此时再添加一个 rank 为 1 的动态快捷方式放在第二的位置上，那最后两个就会被顺延一个位置，rank 变成 2和3。

Shortcut intents 配置

若是但愿应用在用户激活快捷方式时执行多项操做，则能够将其配置为触发后多项活动。你能够经过分配多个 intent，启动一个 activity 到另外一个 activity，具体的要取决你快捷方式的类型。

使用 ShortcutInfo.Builder 建立快捷方式时，可使用 setIntents() 而不是 setIntent()。经过调用 setIntents() 你能够在用户点击快捷方式时触发多个 activity，将除列表中最后一个 activity 以外的全部 activity 放在后续堆栈中。若是此时点击返回按钮，会按照以前存储的堆栈 activity 顺序进行展现，而不是直接回到首页。

好比按照下面代码配置多个 intent：

@TargetApi(Build.VERSION_CODES.N_MR1)
private ShortcutInfo createShortcutInfo1() {
  Intent intent1 = new Intent(Intent.ACTION_VIEW, Uri.parse("http://xiaweizi.cn/"));
  Intent intent = new Intent(this, TestActivity.class);
  intent.setAction(Intent.ACTION_VIEW);
  intent.putExtra("key", "fromDynamicShortcut");
  return new ShortcutInfo.Builder(this, ID_DYNAMIC_1)
    .setShortLabel(getString(R.string.dynamic_shortcut_short_label1))
    .setLongLabel(getString(R.string.dynamic_shortcut_long_label1))
    .setIcon(Icon.createWithResource(this, R.drawable.add))
    .setIntents(new Intent[]{intent, intent1})
    .build();
}
复制代码

那么它会一次触发 intent 和 intent1,此时 intent 被压入 intent1 的栈底，点击返回，则展现 intent 的信息。如图：

还有一个问题，静态快捷方式是不能拥有自定的 intent flag 的，静态快捷方式始终设置为 Intent.FLAG_ACTIVITY_NEW_TASK 和 Intent.FLAG_ACTIVITY_CLEAR_TASK 这意味着，当应用程序已经在运行时，启动静态快捷方式时，应用中全部的活动都将被销毁。若是不但愿出现这种状况，可使用 trampoline activity，或者在 Activity.onCreate(Bundle) 中启动一个 不可见的 activity，而后调用 Activity.finish()。

1. 在 AndroidManifest.xml 中， trampoline activity 应用设置 android:taskAffinity=""。
2. 在快捷方式资源文件中，静态快捷方式中的 intent 应引用 trampoline activity。

更新 pinned Shortcuts

每一个应用最多包含 getMaxShortcutCountPerActivity() 个快捷方式，其中包括动态和静态的总和。可是桌面快捷方式的数量是不限制的。

当动态快捷方式被放置到桌面时，即便代码中将该动态快捷方式移除，桌面的还依然存在，所以对于桌面的快捷方式是不止 getMaxShortcutCountPerActivity 的限制的。

假设 getMaxShortcutCountPerActivity() 的值为4：

1. 聊天应用程序发布四个动态快捷方式，表示最近的四个对话(c1,c2,c3,c4)

2. 用户将全部的快捷方式复制到桌面

3. 而后用户又启动三个额外的最近对话(c5,c6和c7)，这是从新发布更新动态快捷方式，那新的快捷方式列表为：c4,c5,c6,c7。改应用必须删除过 c1,c2喝c3，由于只能展现四个快捷方式，可是桌面已经保存的这三个快捷方式是能够正常访问的。

   用户如今其实能够总共访问七个快捷方式，其中包括四个最大的动态快捷方式和桌面的三个快捷方式

4. 应用程序可使用 updateShortcuts(List) 来更新上述七个任意快捷方式

5. 使用 addDynamicShortcuts() 和 setDynamicShortcuts() 一样能够更新具备相同 shortcutId 的快捷方式对象，可是他们不能跟新非动态的快捷方式。

系统设置更改

系统设置的更改，好比修改系统的语言，Shortcuts 是不能动态更新的，此时须要建立广播监听 Intent.ACTION_LOCALE_CHANGED ,当收到广播时从新更新快捷方式，保证快捷方式展现没有问题。

处理前：

处理后：

track Shortcuts

为了肯定静态和动态快捷方式以哪一种方式出现，每次启动都会检查快捷方式的激活历史记录。能够经过调用 reportShortcutUsed() 方法传入其 shortcutId，提升 action 的响应速度。

ShortCuts 频率限制

当使用 setDynamicShortcuts()、addDynamicShortcuts() 和 updateDynamicShortcuts() 方法时，须要注意的是，你可能在后台调用这方法是有固定的次数限制的，那能够调用方法的次数限制就是 rate limiting。此功能用于防止 ShortcutManager 过分消耗设备资源。

当处于 rate limiting 中，isRateLimitingActive() 返回 true，可是在某些操做执行会重置这个值，所以即便是在后台应用程序也能够调用 shortcutManager方法，直到再次达到速率限制。这些操做包括：

1. 应用再次回到前台
2. 系统区域设置更改
3. 用户在通知栏处理嵌入的交互操做

若是在开发或者测试中遇到次数被限制的状况，能够在 开发者选项中 -> 重置 ShortcutsManager 调用频率限制 来恢复。或者使用 adb 命令

adb shell cmd shortcut reset-throttling [ --user your-user-id ]
复制代码

建议

在设计和建立快捷方式时，请遵循如下建议：

遵循设计准则

要使应用程序的快捷方式与系统应用程序使用的快捷方式在视觉上保持一致，请遵循 快捷方式设计指南

仅发布四个不一样的快捷方式

尽管 API 目前支持给任何应用最多五个快捷方式(静态和动态)，但仍是建议仅发布四个不一样的快捷方式，以改善在设备上的视觉效果。

限制快捷方式的描述长度

快捷方式的菜单空间有限，在桌面展现应用程序须要考虑到这个因素。若是能够的话，将快捷方式的 shortLable 长度限制在 10 个字符，并将 longLable 长度限制在 25个字符。

记录快捷方式和其操做的历史记录

对于建立的每一个快捷方式，请考虑用户在应用中是否能够直接用不一样方式来完成相同的任务，须要记住的是，这种状况下，调用 reportShortcutUsed() ，这样 launcher 就能够提升 shortcut 对应的 actions 的响应速度。

只有在 shortcuts 的意义存在时更新

当改变更态快捷方式时，只有在 shortcut 仍然保持它的含义时，调用 updateShortcuts() 方法改变它的信息，不然，应该使用 addDynamicShortcuts() 或 setDynamicShortcuts() 建立一个具备新含义的 shortcutId 的快捷方式。

例如，若是咱们已经建立了导航到一个超市的快捷方式，若是超市的名称改变了可是位置并无变化时，只更新信息是合适的，可是若是用户开始再一个不一样位置的超市购物时，最好就是建立一个新的快捷方式。

每次打开 APP 都须要检查快捷方式

在备份或恢复时，动态 shortcuts 不会被保存， 正是由于这个缘由，推荐咱们在须要 APP 启动和从新发布动态快捷方式时，检查 getDynamicShortcuts() 的对象的数量。

参考自

官方Demo

官方文档

原文地址 kua