إضافة إمكانات إلى الاختصارات
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتيح لك الإمكانات في shortcuts.xml تحديد أنواع الإجراءات التي يمكن للمستخدمين اتّخاذها لتشغيل تطبيقك وتنفيذ مهمة معيّنة مباشرةً.
على سبيل المثال، تستخدم "إجراءات التطبيقات" في "مساعد Google" إمكانات تتيح للمطوّرين توسيع ميزات التطبيق لتشمل الأهداف المضمّنة، ما يتيح للمستخدمين تفعيل هذه الميزات والتحكّم فيها باستخدام الطلبات الصوتية. تتألف إحدى الإمكانات من اسم الإجراء و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 تتيح للمستخدمين استخدام الأوامر الصوتية مع "مساعد Google" لبدء تمرين في تطبيق لياقة بدنية:
<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) من خلال سؤال "مساعد Google"، "Ok Google، ابدأ الركض في ExampleApp"، سيستجيب "مساعد Google" لطلب المستخدم باستخدام المعلومات المقدَّمة في العنصر المتداخل intent. تحدّد intent في هذا النموذج التفاصيل التالية:
- يحدّد
android:targetPackage حزمة التطبيق المستهدَفة لهذا الغرض.
- يحدّد الحقل
android:targetClass النشاط الوجهة:
com.example.sampleApp.ExerciseActivity.
- يُعلن الغرض
parameter عن إتاحة مَعلمة BII
exercise.name وكيفية تمرير قيمة المَعلمة التي تم جمعها
من المستخدِم كبيانات إضافية في intent.
ربط الاختصارات بإحدى الإمكانات
بعد تحديد إحدى الإمكانات، يمكنك توسيع وظائفها من خلال ربط اختصارات ثابتة أو ديناميكية بها. تعتمد طريقة ربط الاختصارات بـ capability
على الميزة التي يتم تنفيذها والكلمات الفعلية المضمّنة في طلب المستخدم. على سبيل المثال، عندما يبدأ مستخدم الركض في تطبيقك لتتبُّع اللياقة البدنية من خلال طلب من "مساعد Google"، "Ok Google، ابدأ الركض في ExampleApp" يمكن أن يستخدم "مساعد Google" اختصارًا لتشغيل مثيل من capability يحدّد كيان تمرين صالحًا من النوع "ركض" للمعلمة exercise.name.
لمزيد من المعلومات حول ربط الاختصارات بـ "مهام في التطبيقات"، يُرجى الاطّلاع على نظرة عامة حول "مهام في التطبيقات".
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-08-27 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","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-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["Capabilities 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\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\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)."]]
