הוספת יכולות לקיצורי הדרך
קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
היכולות ב-shortcuts.xml מאפשרות לכם להצהיר על סוגי הפעולות שהמשתמשים יכולים לבצע כדי להפעיל את האפליקציה ולבצע ישירות משימה ספציפית.
לדוגמה, פעולות באפליקציות של Google Assistant משתמשות ביכולות כדי לאפשר למפתחים להרחיב תכונות באפליקציה לכוונות מוכללות (BII), וכך לאפשר למשתמשים להפעיל ולשלוט בתכונות האלה באמצעות פקודות קוליות. יכולת מורכבת משם הפעולה ומintent שמטרגט את היעד באפליקציה שנותן מענה לכוונת המשתמש.
הגדרת יכולות בקובץ shortcuts.xml
מגדירים רכיבי capability בקובץ משאבים shortcuts.xml בפרויקט פיתוח אפליקציות ל-Android. כדי להגדיר רכיב capability, מבצעים את הפעולות הבאות:
- יוצרים משאב
shortcuts.xml לפי ההוראות במאמר יצירת קיצורי דרך סטטיים.
צריך לכלול את הפרטים הבאים ביכולת:
שם היכולת: הפעולה שרוצים שהאפליקציה תתמוך בה. במסמכי התיעוד של הרכיב מפורטת התכונה שדורשת הגדרות של יכולות. פקודות קוליות של פעולות באפליקציות משתמשות ב-BII Action ID לשמות של יכולות, שאפשר למצוא בהפניה ל-BII. לדוגמה,
ב-GET_THING BII, Action ID מופיע כ-actions.intent.GET_THING.
יעד באפליקציה: היעד באפליקציה שאליו מגיעים אחרי הפעלת הפעולה כדי למלא את בקשת המשתמש. מגדירים יעדים באפליקציה באמצעות רכיבי intent שמוטמעים בתוך capability.
מיפוי פרמטרים: כל intent עשוי להכיל פרמטרים שיועברו כנתוני extra של הכוונה. לדוגמה, כל BII של פעולות באפליקציה כולל שדות שמייצגים מידע שמשתמשים מספקים בדרך כלל בשאילתות שמפעילות את ה-BII.
בדוגמה הבאה מוצגת הגדרת יכולת ב-shortcuts.xml
עבור actions.intent.START_EXERCISE, ממשק BII שמאפשר למשתמשים להשתמש בפקודות קוליות עם Assistant כדי להתחיל אימון באפליקציית כושר:
<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. אם משתמש מפעיל את ה-BII הזה באמצעות בקשה ל-Assistant, 'Ok Google, תתחיל ריצה ב-ExampleApp', Assistant מבצעת את בקשת המשתמש באמצעות המידע שמופיע ברכיב intent המקונן. התג intent בדוגמה הזו מגדיר את הפרטים הבאים:
- התג
android:targetPackage מגדיר את חבילת אפליקציית היעד עבור הכוונה הזו.
- בשדה
android:targetClass מציינים את פעילות היעד:
com.example.sampleApp.ExerciseActivity.
- ה-Intent
parameter מכריז על תמיכה בפרמטר BII
exercise.name ועל האופן שבו מעבירים את ערך הפרמטר – שנאסף מהמשתמש – כנתונים נוספים ב-intent.
שיוך קיצורי דרך ליכולת
אחרי שמגדירים יכולת, אפשר להרחיב את הפונקציונליות שלה על ידי שיוך קיצורי דרך סטטיים או דינמיים אליה. האופן שבו מקשרים קיצורי דרך ל-capability תלוי בתכונה שמטמיעים ובמילים בפועל שנכללות בבקשה של המשתמש. לדוגמה, כשמשתמש מתחיל ריצה באפליקציה למעקב אחר כושר על ידי שאילתה ל-Assistant, "Ok Google, start a run in ExampleApp" Assistant יכול להשתמש בקיצור דרך כדי להפעיל מופע של capability שמגדיר ישות תרגיל תקפה של 'ריצה' לפרמטר exercise.name.
מידע נוסף על שיוך קיצורי דרך לפעולות באפליקציה זמין במאמר סקירה כללית על פעולות באפליקציה.
דוגמאות התוכן והקוד שבדף הזה כפופות לרישיונות המפורטים בקטע רישיון לתוכן. Java ו-OpenJDK הם סימנים מסחריים או סימנים מסחריים רשומים של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2025-08-21 (שעון UTC).
[[["התוכן קל להבנה","easyToUnderstand","thumb-up"],["התוכן עזר לי לפתור בעיה","solvedMyProblem","thumb-up"],["סיבה אחרת","otherUp","thumb-up"]],[["חסרים לי מידע או פרטים","missingTheInformationINeed","thumb-down"],["התוכן מורכב מדי או עם יותר מדי שלבים","tooComplicatedTooManySteps","thumb-down"],["התוכן לא עדכני","outOfDate","thumb-down"],["בעיה בתרגום","translationIssue","thumb-down"],["בעיה בדוגמאות/בקוד","samplesCodeIssue","thumb-down"],["סיבה אחרת","otherDown","thumb-down"]],["עדכון אחרון: 2025-08-21 (שעון UTC)."],[],[],null,["# Add capabilities to shortcuts\n\nCapabilities in `shortcuts.xml` let you declare the types of actions users can\ntake to launch your app and directly perform a specific task.\n\nFor example, Google Assistant App Actions use capabilities to let developers\nextend in-app features to [built-in intents](//developers.google.com/assistant/app/intents) (BIIs), letting users activate\nand control those features using spoken commands. A capability consists of the\nname of the action and an `intent` targeting the destination in your app that\nresolves the user intent.\n\nDefine capabilities in shortcuts.xml\n------------------------------------\n\nYou define `capability` elements in a `shortcuts.xml` resource file in your\nAndroid app development project. To define a `capability` element, do the\nfollowing:\n\n1. Create a `shortcuts.xml` resource by following the instructions in [Create\n static shortcuts](//develop/ui/views/launch/shortcuts/creating-shortcuts#static).\n2. Include the following required information in your capability:\n\n - **Capability name:** the action you want your app to support. Refer to\n the component documentation for the feature that requires capability\n definitions. App Actions voice-enabled commands use the BII `Action ID`\n for capability names, which you can find in [BII reference](//developers.google.com/assistant/app/reference/built-in-intents). For example,\n the [`GET_THING`](//developers.google.com/assistant/app/reference/built-in-intents/common/get-thing) BII lists its `Action ID` as `actions.intent.GET_THING`.\n\n - **App destination:** the destination in your app the action launches to\n fulfill the user request. Define app destinations using `intent` elements\n nested within the `capability`.\n\n - **Parameter mappings:** each `intent` might contain parameters to be\n passed as `extra` data of the intent. For example, each App Actions BII\n includes fields representing information users often provide in queries that\n trigger the BII.\n\nThe following example demonstrates a capability definition in `shortcuts.xml`\nfor [`actions.intent.START_EXERCISE`](//developers.google.com/assistant/app/reference/built-in-intents/health-and-fitness/start-exercise), a BII that lets users use spoken\ncommands with Assistant to begin a workout in a fitness app: \n\n \u003cshortcuts xmlns:android=\"http://schemas.android.com/apk/res/android\"\u003e\n \u003ccapability android:name=\"actions.intent.START_EXERCISE\"\u003e\n \u003cintent\n android:action=\"android.intent.action.VIEW\"\n android:targetPackage=\"com.example.sampleApp\"\n android:targetClass=\"com.example.sampleApp.ExerciseActivity\"\u003e\n \u003cparameter\n android:name=\"exercise.name\"\n android:key=\"exerciseType\"/\u003e\n \u003c/intent\u003e\n \u003c/capability\u003e\n \u003c/shortcuts\u003e\n\nIn the preceding example, the `\u003ccapability\u003e` `android:name` attribute refers to\nthe `START_EXERCISE` BII. If a user invokes this BII by asking Assistant, *\"Hey\nGoogle, start a run in ExampleApp,\"* Assistant fulfills the user request using\ninformation provided in the nested `intent` element. The `intent` in this sample\ndefines the following details:\n\n- The `android:targetPackage` sets the target application package for this intent.\n- The `android:targetClass` field specifies the destination activity: `com.example.sampleApp.ExerciseActivity`.\n- The intent `parameter` declares support for a BII parameter [`exercise.name`](//developers.google.com/assistant/app/reference/built-in-intents/health-and-fitness/start-exercise#recommended-fields) and how to pass the parameter value---collected from the user---as extra data in the `intent`.\n\nAssociate shortcuts with a capability\n-------------------------------------\n\nOnce you define a capability, you can extend its functionality by associating\nstatic or dynamic shortcuts with it. How shortcuts are linked to a `capability`\ndepends on the feature being implemented and the actual words included in a\nuser's request. For example, when a user begins a run in your fitness tracking\napp by asking Assistant, *\"Hey Google, start a run in ExampleApp.\"* Assistant\ncan use a shortcut to launch an instance of a `capability` that defines a valid\nexercise entity of \"run\" for the `exercise.name` parameter.\n\nFor more information about associating shortcuts to App Actions, see [App\nActions overview](//developers.google.com/assistant/app)."]]
