قابلیت ها را به میانبرها اضافه کنید

قابلیت‌های موجود در shortcuts.xml به شما امکان می‌دهند انواع اقداماتی را که کاربران می‌توانند برای راه‌اندازی برنامه شما و انجام مستقیم یک کار خاص انجام دهند، اعلام کنید.

برای مثال، اقدامات برنامه دستیار گوگل از قابلیت‌هایی استفاده می‌کنند که به توسعه‌دهندگان اجازه می‌دهد ویژگی‌های درون برنامه را به اهداف داخلی (BII) گسترش دهند و به کاربران اجازه می‌دهند این ویژگی‌ها را با استفاده از دستورات گفتاری فعال و کنترل کنند. یک قابلیت شامل نام اقدام و یک intent است که مقصد را در برنامه شما هدف قرار می‌دهد و هدف کاربر را برآورده می‌کند.

قابلیت‌ها را در shortcuts.xml تعریف کنید

شما عناصر capability در یک فایل منبع shortcuts.xml در پروژه توسعه برنامه اندروید خود تعریف می‌کنید. برای تعریف یک عنصر capability ، موارد زیر را انجام دهید:

1. با دنبال کردن دستورالعمل‌های موجود در بخش «ایجاد میانبرهای ایستا»، یک منبع shortcuts.xml ایجاد کنید.

2. اطلاعات مورد نیاز زیر را در توانایی خود لحاظ کنید:

   • نام قابلیت: عملی که می‌خواهید برنامه شما از آن پشتیبانی کند. برای ویژگی‌ای که نیاز به تعاریف قابلیت دارد، به مستندات کامپوننت مراجعه کنید. دستورات صوتی App Actions Action ID BII برای نام قابلیت‌ها استفاده می‌کنند که می‌توانید آن را در مرجع BII پیدا کنید. به عنوان مثال، GET_THING BII Action ID خود را به صورت actions.intent.GET_THING فهرست می‌کند.

   • مقصد برنامه: مقصدی در برنامه شما که اکشن برای انجام درخواست کاربر اجرا می‌شود. مقاصد برنامه را با استفاده از عناصر intent که درون capability قرار گرفته‌اند، تعریف کنید.

   • نگاشت پارامترها: هر intent ممکن است شامل پارامترهایی باشد که به عنوان داده‌های extra intent ارسال می‌شوند. به عنوان مثال، هر App Actions BII شامل فیلدهایی است که نشان‌دهنده اطلاعاتی هستند که کاربران اغلب در پرس‌وجوهایی که BII را فعال می‌کنند، ارائه می‌دهند.

مثال زیر تعریف قابلیتی را در shortcuts.xml برای actions.intent.START_EXERCISE نشان می‌دهد، یک BII که به کاربران اجازه می‌دهد از دستورات گفتاری با دستیار برای شروع تمرین در یک برنامه تناسب اندام استفاده کنند:

<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <capability android:name="actions.intent.START_EXERCISE">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="com.example.sampleApp"
      android:targetClass="com.example.sampleApp.ExerciseActivity">
      <parameter
        android:name="exercise.name"
        android:key="exerciseType"/>
    </intent>
  </capability>
</shortcuts>

در مثال قبلی، ویژگی <capability> android:name به START_EXERCISE BII اشاره دارد. اگر کاربری با پرسیدن «سلام گوگل، در ExampleApp یک اجرا را شروع کن» از دستیار، این BII را فراخوانی کند، دستیار درخواست کاربر را با استفاده از اطلاعات ارائه شده در عنصر intent تو در تو انجام می‌دهد. intent در این نمونه جزئیات زیر را تعریف می‌کند:

• android:targetPackage ‎ بسته‌ی برنامه‌ی هدف را برای این intent تنظیم می‌کند.
• فیلد android:targetClass اکتیویتی مقصد را مشخص می‌کند: com.example.sampleApp.ExerciseActivity .
• parameter intent پشتیبانی از پارامتر BII exercise.name و نحوه ارسال مقدار پارامتر - که از کاربر جمع‌آوری شده است - را به عنوان داده اضافی در intent اعلام می‌کند.

مرتبط کردن میانبرها با یک قابلیت

پس از تعریف یک قابلیت، می‌توانید با مرتبط کردن میانبرهای ایستا یا پویا با آن، عملکرد آن را گسترش دهید. نحوه‌ی اتصال میانبرها به یک capability به ویژگی پیاده‌سازی شده و کلمات واقعی موجود در درخواست کاربر بستگی دارد. به عنوان مثال، وقتی کاربر با پرسیدن «سلام گوگل، در ExampleApp شروع به دویدن می‌کند»، در برنامه‌ی ردیابی تناسب اندام شما شروع به دویدن می‌کند. دستیار می‌تواند از یک میانبر برای راه‌اندازی نمونه‌ای از یک capability استفاده کند که یک موجودیت تمرین معتبر «run» را برای پارامتر exercise.name تعریف می‌کند.

برای اطلاعات بیشتر در مورد مرتبط کردن میانبرها با App Actions، به نمای کلی App Actions مراجعه کنید.