میانبرهای پویا را به دستیار Google با اقدامات برنامه گسترش دهید

1. بررسی اجمالی

در codelab قبلی ، شما از میانبرهای ثابت برای پیاده سازی مقاصد داخلی (BII) در یک برنامه نمونه استفاده کردید. توسعه دهندگان اندروید از App Actions برای گسترش عملکرد برنامه به دستیار Google استفاده می کنند.

میانبرهای ثابت همراه با یک برنامه هستند و فقط با انتشار نسخه های جدید برنامه قابل به روز رسانی هستند. فعال کردن عملکرد صوتی برای عناصر پویا در یک برنامه، مانند محتوای تولید شده توسط کاربر، با استفاده از میانبرهای پویا به دست می آید. پس از انجام اقدامات مرتبط، مانند ایجاد یادداشت جدید در برنامه ردیابی کار، برنامه‌ها میانبرهای پویا را انجام می‌دهند. با App Actions، این میان‌برهای صوتی را با اتصال به یک BII فعال می‌کنید، و به کاربران امکان می‌دهد با گفتن جملاتی مانند «Hey Google، لیست مواد غذایی من را در ExampleApp باز کن» از «دستیار» به محتوای خود دسترسی داشته باشند.

سه صفحه پیشرونده که دستیار گوگل را در حال راه اندازی میانبر پویا نشان می دهد.

شکل 1. سه صفحه پیشرونده که یک کار ایجاد شده توسط کاربر را نشان می دهد و دستیار Google یک میانبر پویا برای آن مورد کار راه اندازی می کند.

چیزی که خواهی ساخت

در این لبه کد، میانبرهای پویا برای صدا را در یک نمونه برنامه لیست کارهای Android فعال می‌کنید و به کاربران امکان می‌دهد از دستیار بخواهند موارد فهرست کار را که در برنامه ایجاد می‌کنند باز کند. شما این کار را با استفاده از الگوهای معماری اندروید، به‌ویژه مخزن ، سرویس یاب و الگوهای ViewModel انجام می‌دهید.

پیش نیازها

این کد لبه بر روی مفاهیم App Actions تحت پوشش قبلی کدها ، به ویژه BII ها و میانبرهای ایستا استوار است. اگر با App Actions تازه کار هستید، توصیه می‌کنیم قبل از ادامه، آن لبه کد را تکمیل کنید.

علاوه بر این، قبل از ادامه، مطمئن شوید که محیط توسعه شما دارای پیکربندی زیر است:

  • ترمینالی برای اجرای دستورات پوسته با نصب git.
  • آخرین نسخه پایدار اندروید استودیو .
  • یک دستگاه اندروید فیزیکی یا مجازی با دسترسی به اینترنت.
  • یک حساب Google که به Android Studio، برنامه Google و برنامه Google Assistant وارد شده است.

2. درک کنید که چگونه کار می کند

فعال کردن میانبر پویا برای دسترسی صوتی شامل مراحل زیر است:

میانبرهای صحافی

برای اینکه میانبر پویا از دستیار قابل دسترسی باشد، باید به یک BII مربوطه متصل شود. هنگامی که یک BII با یک میانبر راه اندازی می شود، دستیار پارامترهای درخواست کاربر را با کلمات کلیدی تعریف شده در میانبر محدود مطابقت می دهد. به عنوان مثال:

  • میانبر متصل به GET_THING BII می تواند به کاربران اجازه دهد تا محتوای درون برنامه ای خاص را مستقیماً از Assistant درخواست کنند. * "Hey Google، لیست مواد غذایی من را در ExampleApp باز کنید."
  • یک میانبر محدود به ORDER_MENU_ITEM BII می‌تواند به کاربران اجازه دهد سفارش‌های قبلی را دوباره پخش کنند. * "Hey Google، معمول من را از ExampleApp سفارش دهید."

برای فهرست کامل طبقه بندی شده BII ها به مرجع مقاصد داخلی مراجعه کنید.

ارائه میانبر به دستیار

پس از اتصال میانبرهای خود به یک BII، گام بعدی این است که با افزودن کتابخانه Google Shortcuts Integration به پروژه، دستیار را فعال کنید تا این میانبرها را وارد کند. با وجود این کتابخانه، «دستیار» از هر میانبری که توسط برنامه شما فشار داده می‌شود آگاه خواهد بود و به کاربران امکان می‌دهد با استفاده از عبارت راه‌انداز میانبر در «دستیار» آن میان‌برها را راه‌اندازی کنند.

3. محیط توسعه خود را آماده کنید

این کد لبه از یک نمونه برنامه لیست کارهایی که برای اندروید ساخته شده است استفاده می کند. با استفاده از این برنامه، کاربران می توانند موارد را به لیست ها اضافه کنند، آیتم های لیست وظایف را بر اساس دسته بندی جستجو کنند و وظایف را بر اساس وضعیت تکمیل فیلتر کنند. با تکمیل این قسمت نمونه برنامه را دانلود و آماده کنید.

فایل های پایه خود را دانلود کنید

دستور زیر را برای کلون کردن مخزن GitHub نمونه برنامه اجرا کنید:

git clone https://github.com/actions-on-google/app-actions-dynamic-shortcuts.git

پس از کلون کردن مخزن، مراحل زیر را برای باز کردن آن در Android Studio دنبال کنید:

  1. در گفتگوی خوش آمدید به Android Studio ، روی وارد کردن پروژه کلیک کنید.
  2. پوشه ای را که مخزن را در آن کلون کرده اید انتخاب کنید.

از طرف دیگر، می‌توانید نسخه‌ای از برنامه نمونه را که نشان‌دهنده لبه کد تکمیل‌شده است، با شبیه‌سازی شاخه codelab-complete مخزن Github آن مشاهده کنید: 

git clone https://github.com/actions-on-google/app-actions-dynamic-shortcuts.git --branch codelab-complete

شناسه برنامه اندروید را به روز کنید

به‌روزرسانی شناسه برنامه برنامه به‌طور منحصربه‌فرد برنامه را در دستگاه آزمایشی شما شناسایی می‌کند و در صورتی که برنامه در کنسول Play آپلود شود، از خطای «نام بسته تکراری» جلوگیری می‌کند. برای به‌روزرسانی شناسه برنامه، app/build.gradle را باز کنید:

android {
...
  defaultConfig {
    applicationId "com.MYUNIQUENAME.android.fitactions"
    ...
  }
}

"MYUNIQUENAME" را در قسمت applicationId با چیزی منحصر به فرد برای خود جایگزین کنید.

افزودن وابستگی های میانبر API

کتابخانه های Jetpack زیر را به فایل منبع app/build.gradle اضافه کنید:

app/build.gradle 

dependencies {
   ...
   // Shortcuts library
   implementation "androidx.core:core:1.6.0"
   implementation 'androidx.core:core-google-shortcuts:1.0.1'
   ...
}

برنامه را روی دستگاه خود تست کنید

قبل از ایجاد تغییرات بیشتر در برنامه، ایده‌ای درباره آنچه که برنامه نمونه می‌تواند انجام دهد، مفید است. برای اجرای برنامه در شبیه ساز خود، مراحل زیر را دنبال کنید:

  1. در Android Studio، Run > Run app را انتخاب کنید یا روی Run کلیک کنید نماد برنامه را در اندروید استودیو اجرا کنید در نوار ابزار
  2. در گفتگوی Select Deployment Target ، یک دستگاه را انتخاب کنید و روی OK کلیک کنید. نسخه سیستم عامل پیشنهادی Android 10 (سطح API 30) یا بالاتر است، اگرچه App Actions بر روی دستگاه‌هایی به Android 5 (سطح API 21) کار می‌کند.
  3. برای راه‌اندازی «دستیار» و تأیید عملکرد آن، دکمه «صفحه اصلی» را طولانی فشار دهید. اگر قبلاً این کار را نکرده‌اید، باید در دستگاه خود وارد «دستیار» شوید.

برای اطلاعات بیشتر در مورد دستگاه‌های مجازی Android، به ایجاد و مدیریت دستگاه‌های مجازی مراجعه کنید.

به طور خلاصه برنامه را بررسی کنید تا ببینید چه کاری می تواند انجام دهد. با ضربه زدن روی نماد Plus یک آیتم وظیفه جدید ایجاد می‌شود و آیتم‌های منو در بالا سمت راست به شما امکان می‌دهند موارد کار را بر اساس وضعیت تکمیل جستجو و فیلتر کنید.

4. یک کلاس مخزن میانبر ایجاد کنید

چندین کلاس در برنامه نمونه ما ShortcutManagerCompat API را برای فشار و مدیریت میانبرهای پویا فراخوانی می کنند. برای کاهش افزونگی کد، یک مخزن برای فعال کردن کلاس های پروژه خود برای مدیریت آسان میانبرهای پویا پیاده سازی خواهید کرد.

الگوی طراحی مخزن یک API تمیز برای مدیریت میانبرها ارائه می دهد. مزیت یک مخزن این است که جزئیات API اساسی به طور یکنواخت در پشت یک API حداقلی انتزاع شده است. با دنبال کردن مراحل زیر، مخزن را پیاده سازی کنید:

  1. یک کلاس ShortcutsRepository برای انتزاع ShortcutManagerCompat API ایجاد کنید.
  2. روش های ShortcutsRepository را به مکان یاب سرویس برنامه اضافه کنید.
  3. سرویس ShortcutRepository را در برنامه اصلی ثبت کنید.

مخزن را ایجاد کنید

یک کلاس Kotlin جدید به نام ShortcutsRepository در بسته com.example.android.architecture.blueprints.todoapp.data.source ایجاد کنید. می توانید این بسته را در پوشه app/src/main/java سازماندهی شده پیدا کنید. شما از این کلاس برای پیاده‌سازی یک رابط استفاده خواهید کرد که مجموعه‌ای از روش‌های حداقلی را پوشش می‌دهد که مورد استفاده ما را پوشش می‌دهد.

پنجره Android Studio مکان کلاس ShortcutsRepository را نشان می دهد.

شکل 2. پنجره Android Studio Project Files که محل کلاس ShortcutsRepository را نشان می دهد.

کد زیر را در کلاس جدید قرار دهید:

package com.example.android.architecture.blueprints.todoapp.data.source

import android.content.Context
import android.content.Intent
import androidx.annotation.WorkerThread
import androidx.core.content.pm.ShortcutInfoCompat
import androidx.core.content.pm.ShortcutManagerCompat
import com.example.android.architecture.blueprints.todoapp.data.Task
import com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity

private const val GET_THING_KEY = "q"

/**
* ShortcutsRepository provides an interface for managing dynamic shortcuts.
*/
class ShortcutsRepository(val context: Context) {

   private val appContext = context.applicationContext

   /**
    * Pushes a dynamic shortcut. The task ID is used as the shortcut ID.
    * The task's title and description are used as shortcut's short and long labels.
    * The resulting shortcut corresponds to the GET_THING capability with task's
    * title used as BII's "name" argument.
    *
    * @param task Task object for which to create a shortcut.
    */
   @WorkerThread
   fun pushShortcut(task: Task) {
      // TODO
   }

   private fun createShortcutCompat(task: Task): ShortcutInfoCompat {
      //...
   }

   /**
    *  Updates a dynamic shortcut for the provided task. If the shortcut
    *  associated with this task doesn't exist, this method throws an error.
    *  This operation may take a few seconds to complete.
    *
    * @param tasks list of tasks to update.
    */
   @WorkerThread
   fun updateShortcuts(tasks: List<Task>) {
       //...
   }

   /**
    * Removes shortcuts if IDs are known.
    *
    * @param ids list of shortcut IDs
    */
   @WorkerThread
   fun removeShortcutsById(ids: List<String>) {
       //...
   }

   /**
    * Removes shortcuts associated with the tasks.
    *
    * @param tasks list of tasks to remove.
    */
   @WorkerThread
   fun removeShortcuts(tasks: List<Task>) {
       //...
   }
}

سپس، متد pushShortcut را برای فراخوانی ShortcutManagerCompat API به‌روزرسانی کنید. کلاس ShortcutsRepository را با کد زیر به روز کنید:

ShortcutsRepository.kt

/**
* Pushes a dynamic shortcut for the task. The task's ID is used as a shortcut
* ID. The task's title and description are used as shortcut's short and long
* labels. The created shortcut corresponds to GET_THING capability with task's
* title used as BII's "name" argument.
*
* @param task Task object for which to create a shortcut.
*/


@WorkerThread
fun pushShortcut(task: Task) {
   ShortcutManagerCompat.pushDynamicShortcut(appContext, createShortcutCompat(task))
}

در نمونه کد قبلی، appContext به API ارسال کردیم. این یک ویژگی کلاس است که یک Application Context را در خود دارد. مهم است که از یک Application Context (برخلاف یک Activity Context ) برای جلوگیری از نشت حافظه استفاده کنید، زیرا زمینه ممکن است بیشتر از چرخه عمر فعالیت میزبان حفظ شود.

علاوه بر این، API نیاز دارد که یک شی ShortcutInfoCompat برای شی Task ارسال کنیم. در نمونه کد قبلی، این کار را با فراخوانی متد خصوصی createShortcutCompat انجام می دهیم، که برای ایجاد و برگرداندن یک شی ShortcutInfoCompat آن را به روز می کنیم. برای انجام این کار، خرد createShortcutCompat را با کد زیر به روز کنید:

ShortcutsRepository.kt

private fun createShortcutCompat(task: Task): ShortcutInfoCompat {
   val intent = Intent(appContext, TasksActivity::class.java)
   intent.action = Intent.ACTION_VIEW
   // Filtering is set based on currentTitle.
   intent.putExtra(GET_THING_KEY, task.title)

   // A unique ID is required to avoid overwriting an existing shortcut.
   return ShortcutInfoCompat.Builder(appContext, task.id)
           .setShortLabel(task.title)
           .setLongLabel(task.title)
           // Call addCapabilityBinding() to link this shortcut to a BII. Enables user to invoke a shortcut using its title in Assistant.
           .addCapabilityBinding(
                   "actions.intent.GET_THING", "thing.name", listOf(task.title))
           .setIntent(intent)
           .setLongLived(false)
       .build()
}

کارکردهای خرد باقی مانده در این کلاس با به روز رسانی و حذف میانبرهای پویا سروکار دارند. این توابع را با به روز رسانی با کد زیر فعال کنید:

ShortcutsRepository.kt 

/**
* Updates a Dynamic Shortcut for the task. If the shortcut associated with this task
* doesn't exist, throws an error. This operation may take a few seconds to complete.
*
* @param tasks list of tasks to update.
*/
@WorkerThread
fun updateShortcuts(tasks: List<Task>) {
   val scs = tasks.map { createShortcutCompat(it) }
   ShortcutManagerCompat.updateShortcuts(appContext, scs)
}

/**
* Removes shortcuts if IDs are known.
* @param ids list of shortcut IDs
*/
@WorkerThread
fun removeShortcutsById(ids: List<String>) {
   ShortcutManagerCompat.removeDynamicShortcuts(appContext, ids)
}

/**
* Removes shortcuts associated with the tasks.
*
* @param tasks list of tasks to remove.
*/
@WorkerThread
fun removeShortcuts(tasks: List<Task>) {
   ShortcutManagerCompat.removeDynamicShortcuts (appContext,
           tasks.map { it.id })
}

کلاس را به سرویس یاب اضافه کنید

با ایجاد کلاس ShortcutsRepository ، گام بعدی این است که اشیاء نمونه این کلاس را در دسترس بقیه برنامه قرار دهید. این برنامه با پیاده سازی الگوی یاب سرویس، وابستگی های کلاس را مدیریت می کند. کلاس یاب سرویس را با استفاده از مرورگر کلاس در Android Studio با رفتن به Navigate > Class و تایپ "ServiceLocator" باز کنید. روی فایل Kotlin حاصل کلیک کنید تا در IDE باز شود.

در بالای ServiceLocator.kt ، کد زیر را برای وارد کردن بسته های ShortcutsRepository و SuppressLint قرار دهید:

ServiceLocator.kt

package com.example.android.architecture.blueprints.todoapp

// ...Other import statements
import com.example.android.architecture.blueprints.todoapp.data.source.ShortcutsRepository
import android.annotation.SuppressLint

اعضا و متدهای سرویس ShortcutRepository را با چسباندن کد زیر در بدنه ServiceLocator.kt اضافه کنید:

ServiceLocator.kt 

object ServiceLocator {

   // ...
   // Only the code immediately below this comment needs to be copied and pasted
   // into the body of ServiceLocator.kt:

   @SuppressLint("StaticFieldLeak")
   @Volatile
   var shortcutsRepository: ShortcutsRepository? = null


   private fun createShortcutsRepository(context: Context): ShortcutsRepository {
       val newRepo = ShortcutsRepository(context.applicationContext)
       shortcutsRepository = newRepo
       return newRepo
   }

   fun provideShortcutsRepository(context: Context): ShortcutsRepository {
       synchronized(this) {
           return shortcutsRepository ?: shortcutsRepository ?: createShortcutsRepository(context)
       }
   }
 }

سرویس میانبر را ثبت کنید

مرحله آخر این است که سرویس ShortcutsRepository جدید خود را در برنامه ثبت کنید. در Android Studio، TodoApplication.kt را باز کنید و کد زیر را در بالای فایل کپی کنید:

TodoApplication.kt

package com.example.android.architecture.blueprints.todoapp
/// ... Other import statements

import com.example.android.architecture.blueprints.todoapp.data.source.ShortcutsRepository

سپس با افزودن کد زیر به بدنه کلاس، سرویس را ثبت کنید:

TodoApplication.kt

//...
class TodoApplication : Application() {

   //...

   val shortcutsRepository: ShortcutsRepository
       get() = ServiceLocator.provideShortcutsRepository(this)

   //...
}

برنامه را بسازید و مطمئن شوید که به کار خود ادامه می دهد.

5. یک میانبر جدید فشار دهید

با ایجاد سرویس میانبر خود، آماده شروع فشار دادن میانبرها هستید. از آنجایی که کاربران در این برنامه محتوا (موارد وظیفه) تولید می‌کنند و انتظار دارند که بعداً بتوانند به آن‌ها بازگردند، با فشار دادن میانبر پویا که هر بار که کاربر یک مطلب جدید ایجاد می‌کند، با فشار دادن میانبر پویا که به GET_THING BII محدود می‌شود، دسترسی به این محتوا را به صورت صوتی فعال می‌کنیم. وظیفه این به دستیار امکان می‌دهد تا وقتی کاربران BII را فعال می‌کنند، مستقیماً به سمت مورد درخواستی خود راه‌اندازی کند و از مواردی مانند « Hey Google, لیست خواربارم را در SampleApp باز کن».

با انجام این مراحل، این قابلیت را در برنامه نمونه فعال می‌کنید:

  1. وارد کردن سرویس ShortcutsRepository به کلاس AddEditTaskViewModel که مسئول مدیریت اشیاء لیست وظایف است.
  2. فشار دادن میانبر پویا هنگامی که کاربر یک کار جدید ایجاد می کند.

وارد کردن ShortcutsRepository

ابتدا باید سرویس ShortcutsRepository را در دسترس AddEditTaskViewModel قرار دهیم. برای انجام این کار، سرویس را به ViewModelFactory وارد کنید، کلاس کارخانه ای که برنامه برای نمونه سازی اشیاء ViewModel از جمله AddEditTaskViewModel استفاده می کند.

مرورگر کلاس را در Android Studio با رفتن به Navigate > Class و تایپ کردن "ViewModelFactory" باز کنید. روی فایل Kotlin حاصل کلیک کنید تا در IDE باز شود.

در بالای ViewModelFactory.kt ، کد زیر را برای وارد کردن بسته های ShortcutsRepository و SuppressLint قرار دهید:

ViewModelFactory.kt

package com.example.android.architecture.blueprints.todoapp

// ...Other import statements
import com.example.android.architecture.blueprints.todoapp.data.source.ShortcutsRepository

سپس بدنه ViewModelFactory را با کد زیر جایگزین کنید:

ViewModelFactory.kt

/**
 * Factory for all ViewModels.
 */
@Suppress("UNCHECKED_CAST")
class ViewModelFactory constructor(
    private val tasksRepository: TasksRepository,
    private val shortcutsRepository: ShortcutsRepository,
    owner: SavedStateRegistryOwner,
    defaultArgs: Bundle? = null
) : AbstractSavedStateViewModelFactory(owner, defaultArgs) {

    override fun <T : ViewModel> create(
        key: String,
        modelClass: Class<T>,
        handle: SavedStateHandle
    ) = with(modelClass) {
        when {
            isAssignableFrom(StatisticsViewModel::class.java) ->
                StatisticsViewModel(tasksRepository)
            isAssignableFrom(TaskDetailViewModel::class.java) ->
                TaskDetailViewModel(tasksRepository)
            isAssignableFrom(AddEditTaskViewModel::class.java) ->
                AddEditTaskViewModel(tasksRepository, shortcutsRepository)
            isAssignableFrom(TasksViewModel::class.java) ->
                TasksViewModel(tasksRepository, handle)
            else ->
                throw IllegalArgumentException("Unknown ViewModel class: ${modelClass.name}")
        }
    } as T
}

تغییرات ViewModelFactory را با بالا رفتن یک لایه به پایان برسانید و ShortcutsRepository را به سازنده کارخانه ارسال کنید. مرورگر فایل Android Studio را با رفتن به Navigate > File و تایپ «FragmentExt.kt» باز کنید. روی فایل Kotlin حاصل که در بسته util قرار دارد کلیک کنید تا در IDE شما باز شود.

متن FragmentExt.kt را با کد زیر جایگزین کنید: 

fun Fragment.getViewModelFactory(): ViewModelFactory {
   val taskRepository = (requireContext().applicationContext as TodoApplication).taskRepository
   val shortcutsRepository = (requireContext().applicationContext as TodoApplication).shortcutsRepository
   return ViewModelFactory(taskRepository, shortcutsRepository, this)
}

یک میانبر را فشار دهید

با کلاس انتزاعی ShortcutsRepository که برای کلاس‌های ViewModel برنامه نمونه در دسترس است، AddEditTaskViewModel را به‌روزرسانی می‌کنید، کلاس ViewModel که مسئول ایجاد یادداشت‌ها است، تا هر بار که کاربر یادداشت جدیدی ایجاد می‌کند، میانبر پویا را فشار دهد.

در اندروید استودیو، مرورگر کلاس را باز کرده و «AddEditTaskViewModel» را تایپ کنید. روی فایل Kotlin حاصل کلیک کنید تا در IDE باز شود.

ابتدا بسته ShortcutsRepository را با دستور import زیر به این کلاس اضافه کنید:

package com.example.android.architecture.blueprints.todoapp.addedittask

//Other import statements
import com.example.android.architecture.blueprints.todoapp.data.source.ShortcutsRepository

سپس با به روز رسانی سازنده کلاس با کد زیر، ویژگی کلاس shortcutsRepository را اضافه کنید:

AddEditTaskViewModel.kt

//...

/**
* ViewModel for the Add/Edit screen.
*/
class AddEditTaskViewModel(
   private val tasksRepository: TasksRepository,
   private val shortcutsRepository: ShortcutsRepository
) : ViewModel() {

    //...

با اضافه شدن کلاس ShortcutsRepository ، یک تابع جدید به نام pushShortcut() برای فراخوانی این کلاس ایجاد کنید. تابع خصوصی زیر را در بدنه AddEditTaskViewModel قرار دهید:

AddEditTaskViewModel.kt

//...
private fun pushShortcut(newTask: Task) = viewModelScope.launch {
   shortcutsRepository.pushShortcut(newTask)
}

در نهایت، هر زمان که وظیفه ای ایجاد شد، یک میانبر پویا جدید فشار دهید. محتویات تابع saveTask() را با کد زیر جایگزین کنید:

AddEditTaskViewModel.kt

fun saveTask() {
    val currentTitle = title.value
    val currentDescription = description.value

    if (currentTitle == null || currentDescription == null) {
        _snackbarText.value = Event(R.string.empty_task_message)
        return
    }
    if (Task(currentTitle, currentDescription).isEmpty) {
        _snackbarText.value = Event(R.string.empty_task_message)
        return
    }

    val currentTaskId = taskId
    if (isNewTask || currentTaskId == null) {
        val task = Task(currentTitle, currentDescription)
        createTask(task)
        pushShortcut(task)
    } else {
        val task = Task(currentTitle, currentDescription, taskCompleted, currentTaskId)
        updateTask(task)
    }
}

کد خود را تست کنید

ما بالاخره آماده آزمایش کد خود هستیم! در این مرحله، یک میانبر پویا با قابلیت صوتی را فشار می‌دهید و با استفاده از برنامه Google Assistant آن را بررسی می‌کنید.

یک پیش نمایش ایجاد کنید

ایجاد یک پیش‌نمایش با استفاده از افزونه Google Assistant ، میانبرهای پویا را قادر می‌سازد تا در دستگاه آزمایشی شما در Assistant ظاهر شوند.

افزونه تست را نصب کنید

اگر قبلاً افزونه Google Assistant را ندارید، آن را با دنبال کردن مراحل زیر در Android Studio نصب کنید:

  1. به **File > Settings (Android Studio > Preferences در MacOS) بروید.
  2. در بخش Plugins ، به Marketplace بروید و «دستیار Google» را جستجو کنید.
  3. ابزار را نصب کنید و اندروید استودیو را مجددا راه اندازی کنید.

پیش نمایش را ایجاد کنید

با دنبال کردن این مراحل در Android Studio یک پیش نمایش ایجاد کنید:

  1. روی Tools > Google Assistant > « App Actions Test Tool » کلیک کنید.
  2. در کادر نام برنامه ، نامی مانند «فهرست کارها» تعریف کنید.
  3. روی ایجاد پیش نمایش کلیک کنید. در صورت درخواست، خط‌مشی‌ها و شرایط خدمات App Actions را بررسی کرده و بپذیرید.

پنجره ایجاد پیش نمایش ابزار تست اقدامات برنامه.

شکل 3. پنجره ایجاد پیش نمایش ابزار تست اقدامات برنامه.

در طول آزمایش، میانبرهای پویایی که به دستیار فشار می‌دهید در دستیار ظاهر می‌شوند که با نام برنامه‌ای که برای پیش‌نمایش ارائه کرده‌اید سازمان‌دهی شده‌اند.

یک میانبر را فشار داده و بررسی کنید

برنامه نمونه را مجدداً در دستگاه آزمایشی خود راه اندازی کنید و مراحل زیر را انجام دهید:

  1. یک کار جدید با عنوان "Start Codelab" ایجاد کنید
  2. برنامه Google Assistant را باز کنید و بگویید یا تایپ کنید: «میانبرهای من».
  3. روی تب Explore ضربه بزنید. باید میانبر نمونه را ببینید.
  4. برای فراخوانی روی میانبر ضربه بزنید. باید برنامه راه‌اندازی شده را با نام میانبر از قبل در کادر فیلتر مشاهده کنید که یافتن مورد درخواستی را آسان می‌کند.

6. (اختیاری) میانبر را به روز کنید و حذف کنید

علاوه بر فشار دادن میانبرهای پویا جدید در زمان اجرا، برنامه شما می تواند آنها را به روز کند تا وضعیت فعلی محتوای کاربر و تنظیمات برگزیده شما را منعکس کند. به روز رسانی میانبرهای موجود هر زمان که کاربر مورد مقصد را تغییر می دهد، مانند تغییر نام یک کار در برنامه نمونه، تمرین خوبی است. همچنین باید هر زمان که منبع مقصد حذف شد، میانبر مربوطه را حذف کنید تا از نمایش میانبرهای شکسته به کاربر جلوگیری کنید.

یک میانبر را به روز کنید

AddEditTaskViewModel تغییر دهید تا هر زمان که کاربر جزئیات یک مورد وظیفه را تغییر می دهد، میانبر پویا را به روز کنید. ابتدا بدنه کلاس را با کد زیر به روز کنید تا یک تابع به روز رسانی که از کلاس مخزن ما استفاده می کند اضافه کنید:

AddEditTaskViewModel.kt

private fun updateShortcut(newTask: Task) = viewModelScope.launch {
   shortcutsRepository.updateShortcuts(listOf(newTask))
}

در مرحله بعد، تابع saveTask() را تغییر دهید تا هر زمان که یک کار موجود به روز می شود، متد جدید ما را فراخوانی کند.

AddEditTaskViewModel.kt

// Called when clicking on fab.
fun saveTask() {
   // ...
   // Note: the shortcuts are created/updated in a worker thread.
   if (isNewTask || currentTaskId == null) {
       //...
   } else {
       //...
       updateShortcut(task)
   }
}

کد خود را با راه‌اندازی مجدد برنامه و دنبال کردن مراحل زیر آزمایش کنید:

  1. عنوان مورد کار موجود خود را به "Finish codelab" تغییر نام دهید.
  2. دستیار Google را با گفتن «Hey Google, my shortcuts» باز کنید.
  3. روی تب Explore ضربه بزنید. باید یک برچسب کوتاه به روز شده برای میانبر آزمایشی خود ببینید.

یک میانبر را حذف کنید

هر زمان که کاربر وظیفه ای را حذف می کند، میانبرهای نمونه برنامه ما باید حذف شوند. در برنامه نمونه، منطق حذف کار در کلاس TaskDetailViewModel زندگی می کند. قبل از اینکه این کلاس را به روز کنیم، باید ViewModelFactory دوباره به روز کنیم تا shortcutsRepository را به TaskDetailViewModel منتقل کنیم.

ViewModelFactory را باز کنید و محتوای متد سازنده آن را با کد زیر جایگزین کنید:

//...
class ViewModelFactory constructor(
       private val tasksRepository: TasksRepository,
       private val shortcutsRepository: ShortcutsRepository,
       owner: SavedStateRegistryOwner,
       defaultArgs: Bundle? = null
) : AbstractSavedStateViewModelFactory(owner, defaultArgs) {

   override fun <T : ViewModel> create(
           key: String,
           modelClass: Class<T>,
           handle: SavedStateHandle
   ) = with(modelClass) {
       when {
           isAssignableFrom(StatisticsViewModel::class.java) ->
               StatisticsViewModel(tasksRepository)
           isAssignableFrom(TaskDetailViewModel::class.java) ->
               TaskDetailViewModel(tasksRepository, shortcutsRepository)
           isAssignableFrom(AddEditTaskViewModel::class.java) ->
               AddEditTaskViewModel(tasksRepository, shortcutsRepository)
           isAssignableFrom(TasksViewModel::class.java) ->
               TasksViewModel(tasksRepository, handle)
           else ->
               throw IllegalArgumentException("Unknown ViewModel class: ${modelClass.name}")
       }
   } as T
}

سپس TaskDetailViewModel را باز کنید. ماژول ShortcutsRepository را وارد کنید و یک متغیر نمونه برای آن با استفاده از کد زیر اعلام کنید:

TaskDetailViewModel.kt

package com.example.android.architecture.blueprints.todoapp.taskdetail

...
import com.example.android.architecture.blueprints.todoapp.data.source.ShortcutsRepository


/**
* ViewModel for the Details screen.
*/
class TaskDetailViewModel(
       //...
       private val shortcutsRepository: ShortcutsRepository
   ) : ViewModel() {
...
}

در نهایت، تابع deleteTask() برای فراخوانی shortcutsRepository تغییر دهید تا هر زمان که وظیفه ای با taskId مربوطه حذف شد، میانبر بر اساس شناسه آن حذف شود:

TaskDetailViewModel.kt

fun deleteTask() = viewModelScope.launch {
   _taskId.value?.let {
       //...
       shortcutsRepository.removeShortcutsById(listOf(it))
   }
}

برای آزمایش کد خود، برنامه را دوباره راه اندازی کنید و این مراحل را دنبال کنید:

  1. وظیفه آزمایشی خود را حذف کنید.
  2. عنوان مورد کار موجود خود را به "Finish codelab" تغییر نام دهید.
  3. دستیار Google را با گفتن «Hey Google, my shortcuts» باز کنید.
  4. روی تب Explore ضربه بزنید. تأیید کنید که میانبر آزمایشی شما دیگر ظاهر نمی شود.

7. مراحل بعدی

تبریک می گویم! با تشکر از شما، کاربران برنامه نمونه ما می‌توانند به راحتی با پرسیدن مواردی از دستیار مانند «Hey Google, لیست خواربارم را در ExampleApp باز کن» به یادداشت‌هایی که ایجاد می‌کنند بازگردند. میانبرها با آسان‌کردن بازپخش عملکردهای پرکاربرد در برنامه شما، تعامل عمیق‌تر کاربر را تشویق می‌کنند.

آنچه را پوشش داده ایم

در این کد لبه یاد گرفتید که چگونه:

  • موارد استفاده برای فشار دادن میانبرهای پویا در یک برنامه را شناسایی کنید.
  • کاهش پیچیدگی کد با استفاده از الگوهای طراحی مخزن، تزریق وابستگی و سرویس یاب.
  • میانبرهای پویا با قابلیت صوتی را به محتوای برنامه تولید شده توسط کاربر فشار دهید.
  • میانبرهای موجود را به روز کنید و حذف کنید.

بعدش چی

از اینجا، می‌توانید اصلاحات بیشتری را در برنامه Task List خود انجام دهید. برای ارجاع به پروژه تمام شده، به شعبه repo-codelab-complete در GitHub مراجعه کنید.

در اینجا چند پیشنهاد برای یادگیری بیشتر در مورد گسترش این برنامه با App Actions وجود دارد:

برای ادامه سفر Actions on Google، این منابع را کاوش کنید:

ما را در توییتر @ActionsOnGoogle دنبال کنید تا با آخرین اطلاعیه‌های ما همراه باشید و برای اشتراک‌گذاری آنچه ساخته‌اید در #appActions توییت کنید!

نظرسنجی بازخورد

در نهایت، لطفاً این نظرسنجی را پر کنید تا در مورد تجربه خود در مورد این کد لبه نظر بدهید.