Tạo lối tắt

Lối tắt (shortcut) giúp phân phối nội dung người dùng muốn xem bằng cách giúp họ nhanh chóng truy cập các thành phần của ứng dụng.

Cách thức phân phối nội dung bằng lối tắt sẽ tuỳ thuộc vào trường hợp sử dụng và liệu ngữ cảnh của lối tắt là theo hướng ứng dụng hay hướng đến người dùng. Mặc dù ngữ cảnh của lối tắt tĩnh không thay đổi và ngữ cảnh của lối tắt động thay đổi liên tục, nhưng ngữ cảnh trong cả hai trường hợp đều do ứng dụng chi phối. Trong trường hợp người dùng chọn cách họ muốn ứng dụng phân phối nội dung cho họ, chẳng hạn như thông qua lối tắt được ghim, thì ngữ cảnh sẽ được xác định bởi người dùng. Các tình huống sau đây minh hoạ một vài trường hợp sử dụng cho mỗi loại lối tắt:

  • Lối tắt tĩnh phù hợp nhất với các ứng dụng liên kết đến nội dung bằng cách sử dụng cấu trúc nhất quán trong suốt thời gian người dùng tương tác với ứng dụng. Vì hầu hết trình chạy đều chỉ có thể hiển thị 4 lối tắt cùng một lúc. Lối tắt tĩnh hữu ích cho các hoạt động thông thường. Ví dụ: nếu người dùng muốn xem lịch hoặc email, việc sử dụng lối tắt tĩnh sẽ đảm bảo rằng trải nghiệm của họ được nhất quán khi thực hiện một thao tác thông thường.
  • Lối tắt động được dùng cho các thao tác trong ứng dụng theo ngữ cảnh. Lối tắt theo ngữ cảnh được điều chỉnh cho phù hợp với các hành động mà người dùng thực hiện trong ứng dụng. Ví dụ: nếu bạn phát triển một trò chơi cho phép người dùng bắt đầu từ ải hiện tại khi chạy ứng dụng thì bạn nên thường xuyên cập nhật lối tắt. Việc sử dụng lối tắt động cho phép cập nhật lối tắt mỗi khi người dùng vượt qua một ải.
  • Lối tắt được ghim dùng cho các thao tác cụ thể do người dùng thực hiện. Ví dụ: người dùng có thể muốn ghim một trang web cụ thể vào trình chạy. Lối tắt được ghim có ích vì nó cho phép người dùng thực hiện thao tác tuỳ chỉnh, chẳng hạn như di chuyển đến trang web chỉ trong một bước một cách nhanh chóng hơn so với việc sử dụng một bản sao mặc định của trình duyệt.

Tạo lối tắt tĩnh

Lối tắt tĩnh cung cấp đường liên kết đến các thao tác chung trong ứng dụng của bạn và các thao tác này phải nhất quán trong suốt thời gian hoạt động của phiên bản hiện tại của ứng dụng. Những thao tác có thể tạo lối tắt tĩnh bao gồm xem thư đã gửi, đặt báo thức và hiển thị hoạt động tập thể dục của người dùng trong ngày.

Để tạo một lối tắt tĩnh, hoàn thành trình tự các bước sau:

  1. Trong tệp kê khai của ứng dụng (AndroidManifest.xml), tìm một hoạt động có bộ lọc ý định được đặt thành hành động android.intent.action.MAIN và danh mục android.intent.category.LAUNCHER.

  2. Thêm phần tử <meta-data> vào hoạt động tham chiếu đến tệp tài nguyên nơi định nghĩa lối tắt của ứng dụng:

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
              package="com.example.myapplication">
      <application ... >
        <activity android:name="Main">
          <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>
      </application>
    </manifest>
    
  3. Tạo tệp tài nguyên mới: res/xml/shortcuts.xml.

  4. Trong tệp tài nguyên mới này, thêm phần tử gốc <shortcuts>, trong đó có chứa danh sách các phần tử <shortcut>. Mỗi phần tử <shortcut> đều chứa thông tin về một lối tắt tĩnh, bao gồm biểu tượng, các nhãn mô tả và ý định của lối tắt khi được khởi chạy trong ứng dụng:

    <shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
      <shortcut
        android:shortcutId="compose"
        android:enabled="true"
        android:icon="@drawable/compose_icon"
        android:shortcutShortLabel="@string/compose_shortcut_short_label1"
        android:shortcutLongLabel="@string/compose_shortcut_long_label1"
        android:shortcutDisabledMessage="@string/compose_disabled_message1">
        <intent
          android:action="android.intent.action.VIEW"
          android:targetPackage="com.example.myapplication"
          android:targetClass="com.example.myapplication.ComposeActivity" />
        <!-- If your shortcut is associated with multiple intents, include them
             here. The last intent in the list determines what the user sees when
             they launch this shortcut. -->
        <categories android:name="android.shortcut.conversation" />
        <capability-binding android:key="actions.intent.CREATE_MESSAGE" />
      </shortcut>
      <!-- Specify more shortcuts here. -->
    </shortcuts>
    

Tuỳ chỉnh các giá trị thuộc tính

Danh sách sau đây chứa nội dung mô tả các thuộc tính khác nhau trong lối tắt tĩnh. Bạn phải tạo giá trị cho android:shortcutIdandroid:shortcutShortLabel. Tất cả các giá trị khác là tuỳ chọn.

android:shortcutId

Chuỗi ký tự đại diện cho lối tắt khi một đối tượng ShortcutManager thực hiện các thao tác trên lối tắt đó.

Lưu ý: Bạn không thể đặt giá trị của thuộc tính này thành một chuỗi tài nguyên, chẳng hạn như @string/foo.

android:shortcutShortLabel

Cụm từ ngắn gọn mô tả mục đích của lối tắt. Khi có thể, hãy giới hạn độ dài của "phần mô tả ngắn" về lối tắt ở mức 10 ký tự.

Để biết thêm thông tin, hãy xem setShortLabel().

Lưu ý: Giá trị của thuộc tính này phải là một chuỗi tài nguyên, chẳng hạn như @string/shortcut_short_label.

android:shortcutLongLabel

Cụm từ mở rộng mô tả mục đích của lối tắt. Nếu có đủ khoảng trống, trình chạy sẽ hiển thị giá trị này thay vì android:shortcutShortLabel. Khi có thể, hãy giới hạn độ dài của "phần mô tả dài" về lối tắt ở mức 25 ký tự.

Để biết thêm thông tin, hãy xem setLongLabel().

Lưu ý: Giá trị của thuộc tính này phải là một chuỗi tài nguyên, chẳng hạn như @string/shortcut_long_label.

android:shortcutDisabledMessage

Thông báo xuất hiện trong trình chạy được hỗ trợ khi người dùng cố gắng chạy một lối tắt bị vô hiệu hoá. Thông báo phải giải thích cho người dùng tại sao lối tắt hiện bị vô hiệu hoá. Giá trị của thuộc tính này không có hiệu lực nếu android:enabledtrue.

Lưu ý: Giá trị của thuộc tính này phải là một chuỗi tài nguyên, chẳng hạn như @string/shortcut_disabled_message.

android:enabled

Xác định xem người dùng có thể tương tác với lối tắt từ một trình chạy được hỗ trợ hay không. Giá trị mặc định của android:enabledtrue. Nếu đặt giá trị này thành false, bạn cũng nên đặt android:shortcutDisabledMessage để giải thích lý do vô hiệu hoá lối tắt. Nếu không cần phải thông báo như vậy, cách dễ nhất là xoá hoàn toàn lối tắt khỏi tệp XML.

android:icon

Bitmap hoặc biểu tượng thích ứng mà trình chạy sử dụng khi hiển thị lối tắt cho người dùng. Giá trị này có thể là đường dẫn đến một hình ảnh hoặc tệp tài nguyên chứa hình ảnh. Sử dụng các biểu tượng thích ứng bất cứ khi nào có thể để cải thiện hiệu quả và tính nhất quán.

Lưu ý: Biểu tượng lối tắt không được phủ màu.

Định cấu hình các thành phần bên trong

Tệp XML liệt kê các lối tắt tĩnh của một ứng dụng sẽ hỗ trợ các phần tử sau bên trong mỗi phần tử <shortcut>. Bạn phải thêm một phần tử bên trong intent cho mỗi lối tắt tĩnh được định nghĩa.

intent

Thao tác mà hệ thống khởi chạy khi người dùng chọn lối tắt. Ý định này phải cung cấp một giá trị cho thuộc tính android:action.

Lưu ý: Phần tử intent này không được chứa tài nguyên chuỗi.

Bạn có thể cung cấp nhiều ý định cho một lối tắt. Xem Quản lý nhiều ý định và hoạt động, Đặt ý định, và tài liệu tham khảo lớp TaskStackBuilder để biết thêm thông tin chi tiết.

categories

Nhóm các loại thao tác mà lối tắt của ứng dụng thực hiện, chẳng hạn như tạo tin nhắn trò chuyện mới.

Để biết danh sách các danh mục lối tắt được hỗ trợ, hãy xem tài liệu tham khảo lớp ShortcutInfo.

capability-binding

Khai báo chức năng liên kết với lối tắt này.

Trong ví dụ này, lối tắt được liên kết với một chức năng được khai báo cho CREATE_MESSAGE. Đây là ý định tích hợp của Hành động trong ứng dụng. Việc liên kết chức năng này cho phép người dùng sử dụng lệnh thoại để gọi lối tắt này thông qua Trợ lý Google.

Tạo lối tắt động

Lối tắt động cung cấp đường liên kết đến các thao tác theo ngữ cảnh cụ thể trong ứng dụng. Những thao tác này có thể thay đổi giữa những lần sử dụng ứng dụng và có thể thay đổi ngay cả khi ứng dụng đang chạy. Một số ví dụ điển hình về trường hợp sử dụng lối tắt động bao gồm gọi điện cho ai đó, di chuyển đến một vị trí cụ thể và tải một trò chơi tại điểm lưu cuối cùng của người dùng. Bạn cũng có thể dùng các lối tắt động để mở một cuộc trò chuyện.

Thư viện Jetpack ShortcutManagerCompat hỗ trợ API ShortcutManager, cho phép bạn quản lý các lối tắt động trong ứng dụng của mình. Việc sử dụng thư viện ShortcutManagerCompat sẽ giảm mã nguyên mẫu và đảm bảo lối tắt hoạt động nhất quán trên các phiên bản Android. Bạn cũng cần thư viện này để đẩy các lối tắt động để chúng đủ điều kiện xuất hiện trên các nền tảng của Google, chẳng hạn như Trợ lý Google, cùng với Thư viện tích hợp lối tắt của Google.

API ShorcutManagerCompat cho phép ứng dụng thực hiện các thao tác sau bằng lối tắt động:

  • Đẩy và cập nhật: Sử dụng pushDynamicShortcut() để phát hành và cập nhật lối tắt động. Nếu đã có lối tắt động hoặc lối tắt được ghim với cùng ID thì từng lối tắt có thể thay đổi sẽ được cập nhật.
  • Xoá: Xoá một nhóm lối tắt động bằng removeDynamicShortcuts() hoặc xoá tất cả lối tắt động bằng removeAllDynamicShortcuts().

Để biết thêm thông tin về cách thực hiện các thao tác trên lối tắt, hãy đọc bài viết Quản lý lối tắt và tài liệu tham khảo ShortcutManagerCompat.

Đoạn mã sau là ví dụ hướng dẫn cách tạo lối tắt động và liên kết lối tắt đó với ứng dụng:

Kotlin


val shortcut = ShortcutInfoCompat.Builder(context, "id1")
        .setShortLabel("Website")
        .setLongLabel("Open the website")
        .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website))
        .setIntent(Intent(Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")))
        .build()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut)

Java


ShortcutInfo shortcut = new ShortcutInfoCompat.Builder(context, "id1")
    .setShortLabel("Website")
    .setLongLabel("Open the website")
    .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website))
    .setIntent(new Intent(Intent.ACTION_VIEW,
                   Uri.parse("https://www.mysite.example.com/")))
    .build();

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut);

Thêm Thư viện tích hợp lối tắt của Google

Thư viện tích hợp lối tắt của Google là thư viện Jetpack không bắt buộc. Thư viện này cho phép bạn đẩy các lối tắt động có thể hiển thị trên cả nền tảng Android (ví dụ như trình chạy) và nền tảng Google (ví dụ như Trợ lý Google). Việc sử dụng thư viện này cho phép người dùng dễ dàng khám phá các lối tắt để truy cập nhanh vào một số nội dung cụ thể hoặc lập lại các thao tác trong ứng dụng. Ví dụ: một ứng dụng nhắn tin có thể đẩy một lối tắt động đại diện cho thông tin liên hệ "Alex" sau khi người dùng nhắn tin cho người đó. Sau khi lối tắt động đó được đẩy, nếu người dùng hỏi Trợ lý, "Ok Google, nhắn tin cho Alex trên ExampleApp", Trợ lý có thể chạy ExampleApp và tự động định cấu hình ứng dụng để gửi một tin nhắn cho Alex.

Các lối tắt động được đẩy cùng với thư viện này không phải tuân theogiới hạn lối tắt mà mỗi thiết bị quy định. Điều này cho phép ứng dụng đẩy lối tắt mỗi khi người dùng hoàn tất một thao tác liên kết trong ứng dụng. Việc thường xuyên đẩy các lối tắt theo cách này sẽ giúp Google nắm bắt xu hướng sử dụng của người dùng và đề xuất các lối tắt phù hợp cho họ. Ví dụ: Trợ lý Google có thể học từ các lối tắt được đẩy từ ứng dụng theo dõi sức khỏe mà người dùng thường sử dụng mỗi khi chạy bộ buổi sáng và chủ động đề xuất một lối tắt "bắt đầu chạy bộ" khi người dùng cầm điện thoại lên vào buổi sáng.

Thư viện tích hợp lối tắt của Google không cung cấp bất kỳ chức năng cho phép truy cập vào bất kỳ địa chỉ nào. Khi thêm thư viện này vào ứng dụng, Google sẽ có thể nhập các lối tắt mà ứng dụng đẩy bằng ShortcutManagerCompat.

Để sử dụng thư viện này trong ứng dụng, hãy làm theo các bước sau:

  1. Cập nhật tệp gradle.properties để hỗ trợ thư viện AndroidX:

    
             android.useAndroidX=true
             # Automatically convert third-party libraries to use AndroidX
             android.enableJetifier=true
    
          
  2. Trong app/build.gradle, thêm các phần phụ thuộc cho Thư viện tích hợp lối tắt của Google và ShortcutManagerCompat:

    
             dependencies {
               implementation "androidx.core:core:1.6.0"
               implementation 'androidx.core:core-google-shortcuts:1.0.0'
               ...
             }
    
          
  3. Sau khi thêm các phần phụ thuộc của thư viện vào dự án Android, ứng dụng có thể sử dụng phương thức ShortcutManagerCompat của pushDynamicShortcut() để đẩy các lối tắt động mà sẽ đủ điều kiện hiển thị lên trình chạy và các nền tảng tham gia của Google.

    Lưu ý: Bạn nên sử dụng pushDynamicShortcut để đẩy các lối tắt động bằng Thư viện tích hợp lối tắt của Google. Ứng dụng có thể sử dụng các phương thức khác để phát hành lối tắt, nhưng những phương thức đó có thể không chạy được nếu đạt giới hạn số lối tắt tối đa.

Tạo lối tắt được ghim

Bạn có thể tạo lối tắt được ghim trên Android 8.0 (API cấp 26) trở lên. Không giống như lối tắt tĩnh và động, lối tắt được ghim sẽ xuất hiện trong những trình chạy được hỗ trợ dưới dạng biểu tượng riêng biệt. Hình 1 cho thấy sự khác biệt giữa hai loại lối tắt này.

Lưu ý: Khi bạn thực hiện ghim một lối tắt vào trình chạy được hỗ trợ, người dùng sẽ nhận được một hộp thoại xác nhận yêu cầu họ cho phép ghim lối tắt đó. Nếu người dùng không cho phép ghim lối tắt, trình chạy sẽ huỷ yêu cầu.

Ảnh chụp màn hình thể hiện sự tương phản giữa lối tắt ứng dụng và lối tắt được ghim
Hình 1. Giao diện của lối tắt ứng dụng và lối tắt được ghim

Để ghim lối tắt vào trình chạy được hỗ trợ bằng ứng dụng, hãy hoàn thành các bước sau:

  1. Sử dụng isRequestPinShortcutSupported() để xác minh rằng trình chạy mặc định của thiết bị có hỗ trợ tính năng ghim lối tắt trong ứng dụng.
  2. Tạo đối tượng ShortcutInfo bằng một trong hai cách, tuỳ thuộc vào việc đã có lối tắt hay chưa:

    1. Nếu đã có lối tắt, tạo một đối tượng ShortcutInfo chỉ chứa ID của lối tắt hiện có. Hệ thống sẽ tự động tìm và ghim tất thông tin khác liên quan đến lối tắt.
    2. Nếu ghim một lối tắt mới, tạo một đối tượng ShortcutInfo chứa một ID, ý định và một nhãn ngắn cho lối tắt mới.

    Lưu ý: Do hệ thống tự động thực hiện việc sao lưu và khôi phục đối với các lối tắt được ghim, nên ID của các lối tắt này phải chứa các chuỗi ổn định, không đổi hoặc giá trị nhận dạng máy chủ thay vì giá trị nhận dạng được tạo cục bộ mà có thể không có ý nghĩa trên các thiết bị khác.

  3. Hãy thử ghim lối tắt vào trình chạy của thiết bị bằng cách gọi requestPinShortcut(). Trong quá trình này, bạn có thể truyền đối tượng PendingIntent, qua đó thông báo cho ứng dụng biết khi ghim thành công lối tắt.

    Lưu ý: Nếu người dùng không cho phép ghim lối tắt vào trình chạy, thì ứng dụng sẽ không nhận được lệnh gọi lại.

    Sau khi lối tắt được ghim, ứng dụng có thể cập nhật nội dung bằng phương thức updateShortcuts(). Để biết thêm thông tin, hãy đọc bài viết Cập nhật lối tắt.

Đoạn mã sau đây minh hoạ cách tạo lối tắt được ghim:

Lưu ý: Bạn phải lấy các thực thể của lớp ShortcutManager bằng Context.getSystemService(Class) với đối số ShortcutManager.class hoặc Context.getSystemService(String) với đối số Context.SHORTCUT_SERVICE.

Kotlin

val shortcutManager = getSystemService(ShortcutManager::class.java)

if (shortcutManager!!.isRequestPinShortcutSupported) {
    // Assumes there's already a shortcut with the ID "my-shortcut".
    // The shortcut must be enabled.
    val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build()

    // Create the PendingIntent object only if your app needs to be notified
    // that the user allowed the shortcut to be pinned. Note that, if the
    // pinning operation fails, your app isn't notified. We assume here that the
    // app has implemented a method called createShortcutResultIntent() that
    // returns a broadcast intent.
    val pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(pinShortcutInfo)

    // Configure the intent so that your app's broadcast receiver gets
    // the callback successfully.For details, see PendingIntent.getBroadcast().
    val successCallback = PendingIntent.getBroadcast(context, /* request code */ 0,
            pinnedShortcutCallbackIntent, /* flags */ 0)

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.intentSender)
}

Java

ShortcutManager shortcutManager =
        context.getSystemService(ShortcutManager.class);

if (shortcutManager.isRequestPinShortcutSupported()) {
    // Assumes there's already a shortcut with the ID "my-shortcut".
    // The shortcut must be enabled.
    ShortcutInfo pinShortcutInfo =
            new ShortcutInfo.Builder(context, "my-shortcut").build();

    // Create the PendingIntent object only if your app needs to be notified
    // that the user allowed the shortcut to be pinned. Note that, if the
    // pinning operation fails, your app isn't notified. We assume here that the
    // app has implemented a method called createShortcutResultIntent() that
    // returns a broadcast intent.
    Intent pinnedShortcutCallbackIntent =
            shortcutManager.createShortcutResultIntent(pinShortcutInfo);

    // Configure the intent so that your app's broadcast receiver gets
    // the callback successfully.For details, see PendingIntent.getBroadcast().
    PendingIntent successCallback = PendingIntent.getBroadcast(context, /* request code */ 0,
            pinnedShortcutCallbackIntent, /* flags */ 0);

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.getIntentSender());
}

Lưu ý: Xem thêm các API thư viện hỗ trợ, isRequestPinShortcutSupported() requestPinShortcut() mà hoạt động trên Android 7.1 (API cấp 25) trở xuống. Thư viện hỗ trợ sẽ sử dụng lại EXTRA_SHORTCUT_INTENT không còn dùng nữa để tiến hành ghim.

Tạo một hoạt động lối tắt tuỳ chỉnh

Hoạt động của hộp thoại tuỳ chỉnh hiển thị lời nhắc "Bạn có muốn thêm biểu tượng trình chạy Gmail vào màn hình chính không?" Các tuỳ chọn tuỳ chỉnh là "Không, cảm ơn" và "Thêm biểu tượng".
Hình 2. Ví dụ về hoạt động hộp thoại lối tắt ứng dụng tuỳ chỉnh

Bạn cũng có thể tạo một hoạt động đặc biệt giúp người dùng tạo lối tắt, hoàn tất bằng các tuỳ chọn tuỳ chỉnh và nút xác nhận. Hình 2 là ví dụ về loại hoạt động này trong ứng dụng Gmail.

Trong tệp kê khai của ứng dụng, thêm ACTION_CREATE_SHORTCUT vào phần tử <intent-filter> của hoạt động. Khai báo này thiết lập hành vi sau đây khi người dùng cố gắng tạo một lối tắt:

  1. Hệ thống sẽ bắt đầu hoạt động đặc biệt của ứng dụng.
  2. Người dùng đặt các tuỳ chọn cho phím tắt.
  3. Người dùng chọn nút xác nhận.
  4. Ứng dụng tạo lối tắt bằng phương thức createShortcutResultIntent(). Phương thức này trả về một Intent mà ứng dụng sẽ chuyển tiếp về hoạt động đang được thực hiện trước đó bằng setResult().
  5. Ứng dụng sẽ gọi finish() dựa trên hoạt động dùng để tạo lối tắt tuỳ chỉnh.

Tương tự, ứng dụng có thể nhắc người dùng thêm lối tắt được ghim vào màn hình chính sau khi cài đặt hoặc trong lần đầu tiên người dùng chạy ứng dụng. Phương thức này hiệu quả vì nó giúp người dùng tạo lối tắt trong quá trình làm việc thông thường.

Kiểm thử lối tắt

Để kiểm thử các lối tắt của ứng dụng, hãy cài đặt ứng dụng trên thiết bị có trình chạy hỗ trợ lối tắt. Sau đó, thực hiện những thao tác sau:

  • Nhấn và giữ biểu tượng trình chạy của ứng dụng để xem các lối tắt được định nghĩa cho ứng dụng.
  • Nhấn và kéo một lối tắt để ghim vào trình chạy của thiết bị.