يتيح لك الغرض بدء نشاط في تطبيق آخر عن طريق وصف
الإجراء الذي تريد تنفيذه، مثل "عرض خريطة" أو "التقاط صورة" في عنصر Intent
. يُطلق على هذا النوع من الأهداف اسم ضمني لأنّه لا يحدِّد مكوّن التطبيق للبدء، بل يحدّد إجراءً ويوفّر بعض البيانات التي سيتم تنفيذ الإجراء بها.
عند طلب الرمز startActivity()
أو startActivityForResult()
وتمرير هدف ضمني له، يعمل النظام
على تحليل
النية إلى تطبيق يمكنه التعامل مع الغرض ويبدأ
Activity
المقابل له. وإذا كان هناك أكثر من تطبيق واحد يمكنه معالجة الغرض، سيعرض النظام مربع حوار للمستخدم لاختيار التطبيق المراد استخدامه.
توضّح هذه الصفحة العديد من الأغراض الضمنية التي يمكنك استخدامها لتنفيذ إجراءات شائعة، ويتم تنظيمها حسب نوع التطبيق الذي يعالج الغرض. ويوضّح كل قسم أيضًا طريقة إنشاء فلتر النية للإعلان عن قدرة تطبيقك على تنفيذ الإجراء.
تحذير: إذا لم يكن هناك تطبيقات على الجهاز يمكنها
تلقّي هدف ضمني، يتعطّل التطبيق عند طلبه من الرقم startActivity()
. للتحقّق أولاً من توفُّر
تطبيق لتلقّي الغرض، استدعِ resolveActivity()
على الكائن Intent
. إذا لم تكن النتيجة فارغة، يكون هناك تطبيق واحد على الأقل يمكنه معالجة الغرض، ويمكن الاتصال بـ startActivity()
بأمان. إذا كانت النتيجة فارغة، لا تستخدِم سمة intent، وأوقِف الميزة التي تستدعي الغرض، إن أمكن.
إذا لم تكن على دراية بكيفية إنشاء فلاتر الأهداف أو الأهداف، اطّلِع أولاً على فلاتر أهداف وأهداف.
للتعرّف على كيفية تنشيط الأغراض المُدرَجة في هذه الصفحة من مضيف التطوير، يُرجى الاطّلاع على القسم التحقّق من الأغراض باستخدام قسم Android Debug Bridge
إجراءات Google Voice
تعمل إجراءات Google Voice على تنشيط بعض الأغراض المدرَجة في هذه الصفحة استجابةً للأوامر الصوتية. لمزيد من المعلومات، راجِع بدء استخدام الإجراءات الصوتية للنظام.
منبّه
في ما يلي الإجراءات الشائعة التي تتخذها تطبيقات المنبّه، بما في ذلك المعلومات التي تحتاج إليها لإنشاء فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ كل إجراء.
ضبط منبّه
لإنشاء تنبيه جديد، استخدم إجراء ACTION_SET_ALARM
وحدد تفاصيل التنبيه مثل الوقت والرسالة باستخدام الإضافات التالية.
ملاحظة: لا تتوفّر سوى الساعات والدقائق والرسائل الإضافية في نظام التشغيل Android 2.3 (مستوى واجهة برمجة التطبيقات 9) والإصدارات الأقدم. وتتوفر الميزات الإضافية الأخرى في إصدارات أعلى من نظام التشغيل.
- الإجراء
ACTION_SET_ALARM
- معرّف الموارد المنتظم (URI) للبيانات
- لا شيء
- نوع MIME
- بدون
- العناصر الإضافية
-
EXTRA_HOUR
- ساعة المنبّه.
EXTRA_MINUTES
- دقائق المنبّه.
EXTRA_MESSAGE
- رسالة مخصَّصة للتعرّف على المنبّه.
EXTRA_DAYS
ArrayList
بما في ذلك يوم أسبوعي يتكرر فيه هذا المنبّه. يجب الإعلان عن كل يوم باستخدام عدد صحيح من الفئةCalendar
، مثلMONDAY
.بالنسبة إلى المنبّه لمرة واحدة، لا تحدد هذا الرقم الإضافي.
EXTRA_RINGTONE
- معرّف الموارد المنتظم (URI)
content:
الذي يحدد نغمة رنين لاستخدامها مع المنبه، أوVALUE_RINGTONE_SILENT
بدون نغمة رنين.لاستخدام نغمة الرنين التلقائية، لا تحدِّد هذه النغمة الإضافية.
EXTRA_VIBRATE
- قيمة منطقية تحدد ما إذا كان سيتم اهتزاز هذا المنبّه أم لا.
EXTRA_SKIP_UI
- قيمة منطقية تحدّد ما إذا كان على التطبيق المستجيب أن يتخطّى واجهة المستخدم الخاصة به عند ضبط المنبّه في حال الضبط على "صحيح"، يجب أن يتجاوز التطبيق أي واجهة مستخدم للتأكيد وأن يضبط المنبّه المحدَّد.
مثال على نيّة الشراء:
Kotlin
fun createAlarm(message: String, hour: Int, minutes: Int) { val intent = Intent(AlarmClock.ACTION_SET_ALARM).apply { putExtra(AlarmClock.EXTRA_MESSAGE, message) putExtra(AlarmClock.EXTRA_HOUR, hour) putExtra(AlarmClock.EXTRA_MINUTES, minutes) } if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void createAlarm(String message, int hour, int minutes) { Intent intent = new Intent(AlarmClock.ACTION_SET_ALARM) .putExtra(AlarmClock.EXTRA_MESSAGE, message) .putExtra(AlarmClock.EXTRA_HOUR, hour) .putExtra(AlarmClock.EXTRA_MINUTES, minutes); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
لاستدعاء ميزة ACTION_SET_ALARM
intent، يجب أن يحصل تطبيقك على إذن SET_ALARM
:
<uses-permission android:name="com.android.alarm.permission.SET_ALARM" />
مثال على فلتر الأهداف:
<activity ...> <intent-filter> <action android:name="android.intent.action.SET_ALARM" /> <category android:name="android.intent.category.DEFAULT" /> </intent-filter> </activity>
إِنْشَاءْ مُوَقِّتْ
لإنشاء موقت عد تنازلي، استخدِم الإجراء ACTION_SET_TIMER
وحدِّد تفاصيل الموقّت مثل المدة باستخدام الإضافات التالية.
ملاحظة: هذا الإجراء متوفّر في الإصدار Android 4.4 (المستوى 19 لواجهة برمجة التطبيقات) والإصدارات الأحدث.
- الإجراء
ACTION_SET_TIMER
- معرّف الموارد المنتظم (URI) للبيانات
- لا شيء
- نوع MIME
- بدون
- العناصر الإضافية
-
EXTRA_LENGTH
- مدة الموقّت بالثواني.
EXTRA_MESSAGE
- رسالة مخصّصة للتعرّف على الموقّت.
EXTRA_SKIP_UI
- قيمة منطقية تحدِّد ما إذا كان على التطبيق المستجيب أن يتخطّى واجهة المستخدم عند ضبط الموقّت في حال الضبط على "صحيح"، يجب أن يتجاوز التطبيق أي واجهة مستخدم للتأكيد وأن يبدأ الموقّت المحدَّد.
مثال على نيّة الشراء:
Kotlin
fun startTimer(message: String, seconds: Int) { val intent = Intent(AlarmClock.ACTION_SET_TIMER).apply { putExtra(AlarmClock.EXTRA_MESSAGE, message) putExtra(AlarmClock.EXTRA_LENGTH, seconds) putExtra(AlarmClock.EXTRA_SKIP_UI, true) } if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void startTimer(String message, int seconds) { Intent intent = new Intent(AlarmClock.ACTION_SET_TIMER) .putExtra(AlarmClock.EXTRA_MESSAGE, message) .putExtra(AlarmClock.EXTRA_LENGTH, seconds) .putExtra(AlarmClock.EXTRA_SKIP_UI, true); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
لاستدعاء ميزة ACTION_SET_TIMER
intent، يجب أن يحصل تطبيقك على إذن SET_ALARM
:
<uses-permission android:name="com.android.alarm.permission.SET_ALARM" />
مثال على فلتر الأهداف:
<activity ...> <intent-filter> <action android:name="android.intent.action.SET_TIMER" /> <category android:name="android.intent.category.DEFAULT" /> </intent-filter> </activity>
إظهار جميع المنبهات
لعرض قائمة المنبّهات، استخدِم الإجراء ACTION_SHOW_ALARMS
.
على الرغم من أنّ هذا الهدف لا يستدعي العديد من التطبيقات، يمكن لأيّ تطبيق يعمل كمنبه يعمل بشكل أساسي باستخدام فلتر الأهداف والاستجابة هذا من خلال عرض قائمة المنبّهات الحالية.
ملاحظة: هذا الإجراء متوفّر في الإصدار Android 4.4 (المستوى 19 لواجهة برمجة التطبيقات) والإصدارات الأحدث.
- الإجراء
ACTION_SHOW_ALARMS
- معرّف الموارد المنتظم (URI) للبيانات
- لا شيء
- نوع MIME
- بدون
مثال على فلتر الأهداف:
<activity ...> <intent-filter> <action android:name="android.intent.action.SHOW_ALARMS" /> <category android:name="android.intent.category.DEFAULT" /> </intent-filter> </activity>
التقويم
إضافة حدث هي إجراء شائع لتطبيقات التقويم. أنشئ فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ هذا الإجراء باستخدام المعلومات الواردة في القسم التالي.
إضافة حدث في التقويم
لإضافة حدث جديد إلى تقويم المستخدم، استخدِم الإجراء
ACTION_INSERT
وحدِّد معرّف الموارد المنتظم (URI) للبيانات باستخدام
Events.CONTENT_URI
.
ويمكنك بعد ذلك تحديد تفاصيل مختلفة للحدث باستخدام الميزات الإضافية التالية.
- الإجراء
ACTION_INSERT
- معرّف الموارد المنتظم (URI) للبيانات
Events.CONTENT_URI
- نوع MIME
"vnd.android.cursor.dir/event"
- العناصر الإضافية
-
EXTRA_EVENT_ALL_DAY
- قيمة منطقية تحدّد ما إذا كان هذا الحدث سيستمر طوال اليوم.
EXTRA_EVENT_BEGIN_TIME
- وقت بدء الحدث (بالمللي ثانية منذ البداية)
EXTRA_EVENT_END_TIME
- وقت انتهاء الحدث (بالمللي ثانية منذ البداية)
TITLE
- عنوان الحدث
DESCRIPTION
- وصف الحدث
EVENT_LOCATION
- موقع الفعالية.
EXTRA_EMAIL
- قائمة بعناوين البريد الإلكتروني التي تُحدِّد المدعوين والمدعوّين مفصولة بفواصل.
يمكن تحديد العديد من تفاصيل الأحداث الأخرى باستخدام الثوابت المحدّدة في الفئة
CalendarContract.EventsColumns
.
مثال على نيّة الشراء:
Kotlin
fun addEvent(title: String, location: String, begin: Long, end: Long) { val intent = Intent(Intent.ACTION_INSERT).apply { data = Events.CONTENT_URI putExtra(Events.TITLE, title) putExtra(Events.EVENT_LOCATION, location) putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, begin) putExtra(CalendarContract.EXTRA_EVENT_END_TIME, end) } if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void addEvent(String title, String location, long begin, long end) { Intent intent = new Intent(Intent.ACTION_INSERT) .setData(Events.CONTENT_URI) .putExtra(Events.TITLE, title) .putExtra(Events.EVENT_LOCATION, location) .putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, begin) .putExtra(CalendarContract.EXTRA_EVENT_END_TIME, end); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
مثال على فلتر الأهداف:
<activity ...> <intent-filter> <action android:name="android.intent.action.INSERT" /> <data android:mimeType="vnd.android.cursor.dir/event" /> <category android:name="android.intent.category.DEFAULT" /> </intent-filter> </activity>
الكاميرا
في ما يلي الإجراءات الشائعة التي يمكن أن تتخذها تطبيقات الكاميرا، بما في ذلك المعلومات التي تحتاجها لإنشاء فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ كل إجراء.
التقاط صورة أو فيديو وإرجاعه
لفتح تطبيق كاميرا وتلقّي الصورة أو الفيديو الناتجَين، استخدِم الإجراء ACTION_IMAGE_CAPTURE
أو ACTION_VIDEO_CAPTURE
. حدِّد أيضًا موقع معرّف الموارد المنتظم (URI) الذي تريد من
الكاميرا أن تحفظ فيه الصورة أو الفيديو في عنصر EXTRA_OUTPUT
الإضافي.
- الإجراء
ACTION_IMAGE_CAPTURE
أو
ACTION_VIDEO_CAPTURE
- مخطّط معرّف الموارد المنتظم (URI) للبيانات
- لا شيء
- نوع MIME
- لا شيء
- العناصر الإضافية
-
EXTRA_OUTPUT
- موقع معرّف الموارد المنتظم (URI) الذي يحفظ فيه تطبيق الكاميرا ملف الصورة أو
الفيديو (كعنصر
Uri
).
عندما يعيد تطبيق الكاميرا التركيز إلى نشاطك، بمعنى آخر، يتلقّى تطبيقك معاودة الاتصال بـ "onActivityResult()
"، يمكنك الوصول إلى الصورة أو الفيديو من خلال معرّف الموارد المنتظم (URI) الذي حدّدته بالقيمة EXTRA_OUTPUT
.
ملاحظة: عند استخدام ACTION_IMAGE_CAPTURE
لالتقاط صورة، قد تعرض الكاميرا أيضًا نسخة أو صورة مصغّرة تم تصغير حجم الصورة في النتيجة Intent
، وقد تم حفظها كـ Bitmap
في حقل إضافي باسم "data"
.
مثال على نيّة الشراء:
Kotlin
const val REQUEST_IMAGE_CAPTURE = 1 val locationForPhotos: Uri = ... fun capturePhoto(targetFilename: String) { val intent = Intent(MediaStore.ACTION_IMAGE_CAPTURE).apply { putExtra(MediaStore.EXTRA_OUTPUT, Uri.withAppendedPath(locationForPhotos, targetFilename)) } if (intent.resolveActivity(packageManager) != null) { startActivityForResult(intent, REQUEST_IMAGE_CAPTURE) } } override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) { if (requestCode == REQUEST_IMAGE_CAPTURE && resultCode == Activity.RESULT_OK) { val thumbnail: Bitmap = data.getParcelableExtra("data") // Do other work with full size photo saved in locationForPhotos. ... } }
Java
static final int REQUEST_IMAGE_CAPTURE = 1; static final Uri locationForPhotos; public void capturePhoto(String targetFilename) { Intent intent = new Intent(MediaStore.ACTION_IMAGE_CAPTURE); intent.putExtra(MediaStore.EXTRA_OUTPUT, Uri.withAppendedPath(locationForPhotos, targetFilename)); if (intent.resolveActivity(getPackageManager()) != null) { startActivityForResult(intent, REQUEST_IMAGE_CAPTURE); } } @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { if (requestCode == REQUEST_IMAGE_CAPTURE && resultCode == RESULT_OK) { Bitmap thumbnail = data.getParcelableExtra("data"); // Do other work with full size photo saved in locationForPhotos. ... } }
ولإجراء ذلك عند العمل على نظام التشغيل Android 12 (مستوى واجهة برمجة التطبيقات 31) أو الإصدارات الأحدث، يمكنك الرجوع إلى مثال الغرض التالي.
مثال على نيّة الشراء:
Kotlin
val REQUEST_IMAGE_CAPTURE = 1 private fun dispatchTakePictureIntent() { val takePictureIntent = Intent(MediaStore.ACTION_IMAGE_CAPTURE) try { startActivityForResult(takePictureIntent, REQUEST_IMAGE_CAPTURE) } catch (e: ActivityNotFoundException) { // Display error state to the user. } }
Java
static final int REQUEST_IMAGE_CAPTURE = 1; private void dispatchTakePictureIntent() { Intent takePictureIntent = new Intent(MediaStore.ACTION_IMAGE_CAPTURE); try { startActivityForResult(takePictureIntent, REQUEST_IMAGE_CAPTURE); } catch (ActivityNotFoundException e) { // Display error state to the user. } } </section></div>
لمزيد من المعلومات حول كيفية استخدام هذا الهدف لالتقاط صورة، بما في ذلك
كيفية إنشاء Uri
مناسب لموقع الإخراج، اقرأ
التقاط صور أو
التقاط فيديوهات.
مثال على فلتر الأهداف:
<activity ...> <intent-filter> <action android:name="android.media.action.IMAGE_CAPTURE" /> <category android:name="android.intent.category.DEFAULT" /> </intent-filter> </activity>
عند التعامل مع هذا الهدف، يجب أن تتحقّق من نشاطك بحثًا عن زيادة EXTRA_OUTPUT
في Intent
الواردة، ثم احفظ الصورة أو الفيديو الذي تم التقاطه في الموقع الذي حدّدته تلك الإضافة الإضافية واتصل بـ setResult()
مع Intent
يتضمن صورة مصغّرة مضغوطة في صورة إضافية
باسم "data"
.
بدء تطبيق كاميرا في وضع الصور الثابتة
لفتح تطبيق كاميرا في وضع الصور الثابتة، استخدِم الإجراء INTENT_ACTION_STILL_IMAGE_CAMERA
.
- الإجراء
INTENT_ACTION_STILL_IMAGE_CAMERA
- مخطّط معرّف الموارد المنتظم (URI) للبيانات
- لا شيء
- نوع MIME
- لا شيء
- العناصر الإضافية
- لا شيء
مثال على نيّة الشراء:
Kotlin
private fun dispatchTakePictureIntent() { val takePictureIntent = Intent(MediaStore.ACTION_IMAGE_CAPTURE) try { startActivityForResult(takePictureIntent, REQUEST_IMAGE_CAPTURE) } catch (e: ActivityNotFoundException) { // Display error state to the user. } }
Java
public void capturePhoto(String targetFilename) { Intent intent = new Intent(MediaStore.ACTION_IMAGE_CAPTURE); intent.putExtra(MediaStore.EXTRA_OUTPUT, Uri.withAppendedPath(locationForPhotos, targetFilename)); if (intent.resolveActivity(getPackageManager()) != null) { startActivityForResult(intent, REQUEST_IMAGE_CAPTURE); } }
مثال على فلتر الأهداف:
<activity ...> <intent-filter> <action android:name="android.media.action.STILL_IMAGE_CAMERA" /> <category android:name="android.intent.category.DEFAULT" /> </intent-filter> </activity>
بدء تطبيق كاميرا في وضع الفيديو
لفتح تطبيق كاميرا في وضع الفيديو، استخدِم إجراء INTENT_ACTION_VIDEO_CAMERA
.
- الإجراء
INTENT_ACTION_VIDEO_CAMERA
- مخطّط معرّف الموارد المنتظم (URI) للبيانات
- لا شيء
- نوع MIME
- لا شيء
- العناصر الإضافية
- لا شيء
مثال على نيّة الشراء:
Kotlin
fun capturePhoto() { val intent = Intent(MediaStore.INTENT_ACTION_VIDEO_CAMERA) if (intent.resolveActivity(packageManager) != null) { startActivityForResult(intent, REQUEST_IMAGE_CAPTURE) } }
Java
public void capturePhoto() { Intent intent = new Intent(MediaStore.INTENT_ACTION_VIDEO_CAMERA); if (intent.resolveActivity(getPackageManager()) != null) { startActivityForResult(intent, REQUEST_IMAGE_CAPTURE); } }
مثال على فلتر الأهداف:
<activity ...> <intent-filter> <action android:name="android.media.action.VIDEO_CAMERA" /> <category android:name="android.intent.category.DEFAULT" /> </intent-filter> </activity>
تطبيق جهات الاتصال أو الأشخاص
في ما يلي الإجراءات الشائعة المتعلّقة بتطبيقات إدارة جهات الاتصال، بما في ذلك المعلومات التي تحتاجها لإنشاء فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ كل إجراء.
اختيار جهة الاتصال
ولطلب من المستخدم اختيار جهة اتصال ومنح تطبيقك إذن الوصول إلى جميع معلومات الاتصال، استخدِم الإجراء ACTION_PICK
وحدِّد نوع MIME على Contacts.CONTENT_TYPE
.
تحتوي النتيجة Intent
التي تم إرسالها إلى معاودة الاتصال على onActivityResult()
على معرّف الموارد المنتظم (URI)
content:
الذي يشير إلى جهة الاتصال المحددة. ويمنح الردّ تطبيقك أذونات مؤقتة للاطّلاع على جهة الاتصال هذه باستخدام واجهة برمجة تطبيقات Contacts Provider (مقدِّم خدمة جهات الاتصال)، حتى وإن لم يكن تطبيقك يتضمّن إذن READ_CONTACTS
.
نصيحة: إذا كنت بحاجة إلى الوصول إلى جزء معيّن فقط من معلومات الاتصال، مثل رقم الهاتف أو عنوان البريد الإلكتروني، يمكنك مراجعة القسم التالي حول كيفية اختيار بيانات اتصال معيّنة بدلاً من ذلك.
- الإجراء
ACTION_PICK
- مخطّط معرّف الموارد المنتظم (URI) للبيانات
- لا شيء
- نوع MIME
Contacts.CONTENT_TYPE
مثال على نيّة الشراء:
Kotlin
const val REQUEST_SELECT_CONTACT = 1 fun selectContact() { val intent = Intent(Intent.ACTION_PICK).apply { type = ContactsContract.Contacts.CONTENT_TYPE } if (intent.resolveActivity(packageManager) != null) { startActivityForResult(intent, REQUEST_SELECT_CONTACT) } } override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) { if (requestCode == REQUEST_SELECT_CONTACT && resultCode == RESULT_OK) { val contactUri: Uri = data.data // Do something with the selected contact at contactUri. //... } }
Java
static final int REQUEST_SELECT_CONTACT = 1; public void selectContact() { Intent intent = new Intent(Intent.ACTION_PICK); intent.setType(ContactsContract.Contacts.CONTENT_TYPE); if (intent.resolveActivity(getPackageManager()) != null) { startActivityForResult(intent, REQUEST_SELECT_CONTACT); } } @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { if (requestCode == REQUEST_SELECT_CONTACT && resultCode == RESULT_OK) { Uri contactUri = data.getData(); // Do something with the selected contact at contactUri. ... } }
لمعرفة معلومات حول كيفية استرداد تفاصيل جهة الاتصال بعد الحصول على معرّف الموارد المنتظم (URI)، يُرجى الاطّلاع على استرداد التفاصيل لجهة اتصال.
عند استرداد عنوان URI لجهة الاتصال باستخدام هذا الغرض، لا تحتاج بشكل عام إلى
READ_CONTACTS
إذن لقراءة التفاصيل الأساسية لجهة الاتصال هذه، مثل الاسم المعروض
وما إذا كانت جهة الاتصال مميّزة بنجمة. مع ذلك، إذا كنت تحاول
قراءة بيانات أكثر تحديدًا حول جهة اتصال معيّنة،
مثل رقم هاتفها أو عنوان بريدها الإلكتروني، ستحتاج إلى
إذن READ_CONTACTS
.
اختيار بيانات جهات اتصال معيّنة
لتوجيه المستخدم إلى اختيار معلومة معيّنة من جهة اتصال، مثل رقم الهاتف أو عنوان البريد الإلكتروني أو نوع بيانات آخر، يمكنك استخدام الإجراء ACTION_PICK
وتحديد نوع MIME لأحد أنواع المحتوى التالية، مثل CommonDataKinds.Phone.CONTENT_TYPE
للحصول على رقم الهاتف الخاص بجهة الاتصال.
ملاحظة: في كثير من الحالات، يحتاج تطبيقك إلى إذن READ_CONTACTS
لعرض معلومات محددة حول جهة اتصال معيّنة.
إذا كنت بحاجة إلى استرداد نوع واحد فقط من البيانات من جهة اتصال، تكون هذه التقنية التي تستخدم
CONTENT_TYPE
من الفئات
ContactsContract.CommonDataKinds
أكثر فعالية من استخدام
Contacts.CONTENT_TYPE
، كما هو موضّح في القسم السابق. وتتيح لك النتيجة إمكانية الوصول المباشر إلى البيانات المطلوبة بدون الحاجة إلى إجراء طلب بحث أكثر تعقيدًا في جهات الاتصال.
تحتوي النتيجة Intent
التي تم إرسالها إلى معاودة الاتصال على onActivityResult()
على معرّف الموارد المنتظم (URI)
content:
الذي يشير إلى بيانات جهة الاتصال المحددة. ويمنح هذا الردّ تطبيقك أذونات مؤقتة للاطّلاع على بيانات جهة الاتصال هذه حتى إذا لم يكن تطبيقك يتضمّن إذن READ_CONTACTS
.
- الإجراء
ACTION_PICK
- مخطّط معرّف الموارد المنتظم (URI) للبيانات
- لا شيء
- نوع MIME
-
CommonDataKinds.Phone.CONTENT_TYPE
- اختَر من جهات الاتصال التي لديها رقم هاتف.
CommonDataKinds.Email.CONTENT_TYPE
- اختَر من جهات الاتصال التي لديها عنوان بريد إلكتروني.
CommonDataKinds.StructuredPostal.CONTENT_TYPE
- اختَر من جهات الاتصال التي لديها عنوان بريدي.
أو قيمة من بين قيم
CONTENT_TYPE
العديدة الأخرى ضمنContactsContract
مثال على نيّة الشراء:
Kotlin
const val REQUEST_SELECT_PHONE_NUMBER = 1 fun selectContact() { // Start an activity for the user to pick a phone number from contacts. val intent = Intent(Intent.ACTION_PICK).apply { type = CommonDataKinds.Phone.CONTENT_TYPE } if (intent.resolveActivity(packageManager) != null) { startActivityForResult(intent, REQUEST_SELECT_PHONE_NUMBER) } } override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) { if (requestCode == REQUEST_SELECT_PHONE_NUMBER && resultCode == Activity.RESULT_OK) { // Get the URI and query the content provider for the phone number. val contactUri: Uri = data.data val projection: Array<String> = arrayOf(CommonDataKinds.Phone.NUMBER) contentResolver.query(contactUri, projection, null, null, null).use { cursor -> // If the cursor returned is valid, get the phone number. if (cursor.moveToFirst()) { val numberIndex = cursor.getColumnIndex(CommonDataKinds.Phone.NUMBER) val number = cursor.getString(numberIndex) // Do something with the phone number. ... } } } }
Java
static final int REQUEST_SELECT_PHONE_NUMBER = 1; public void selectContact() { // Start an activity for the user to pick a phone number from contacts. Intent intent = new Intent(Intent.ACTION_PICK); intent.setType(CommonDataKinds.Phone.CONTENT_TYPE); if (intent.resolveActivity(getPackageManager()) != null) { startActivityForResult(intent, REQUEST_SELECT_PHONE_NUMBER); } } @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { if (requestCode == REQUEST_SELECT_PHONE_NUMBER && resultCode == RESULT_OK) { // Get the URI and query the content provider for the phone number. Uri contactUri = data.getData(); String[] projection = new String[]{CommonDataKinds.Phone.NUMBER}; Cursor cursor = getContentResolver().query(contactUri, projection, null, null, null); // If the cursor returned is valid, get the phone number. if (cursor != null && cursor.moveToFirst()) { int numberIndex = cursor.getColumnIndex(CommonDataKinds.Phone.NUMBER); String number = cursor.getString(numberIndex); // Do something with the phone number. //... } } }
عرض جهة اتصال
لعرض تفاصيل جهة اتصال معروفة، استخدِم الإجراء ACTION_VIEW
وحدِّد جهة الاتصال باستخدام معرّف الموارد المنتظم (URI) content:
كبيانات الغرض.
هناك طريقتان أساسيتان لاسترداد عنوان URL لجهة الاتصال بشكل مبدئي:
- استخدِم معرّف الموارد المنتظم (URI) لجهة الاتصال الذي يعرضه الإجراء
ACTION_PICK
الموضّح في القسم السابق. ولا يتطلب هذا الأسلوب أي أذونات للتطبيق. - يمكنك الوصول إلى قائمة جميع جهات الاتصال مباشرةً، على النحو الموضَّح في استرداد قائمة جهات الاتصال. يتطلّب هذا الأسلوب الحصول على إذن
READ_CONTACTS
.
- الإجراء
ACTION_VIEW
- مخطّط معرّف الموارد المنتظم (URI) للبيانات
content:<URI>
- نوع MIME
- لم يتم اتخاذ أي إجراءات. يتم استنتاج النوع من معرّف الموارد المنتظم (URI) لجهة الاتصال.
مثال على نيّة الشراء:
Kotlin
fun viewContact(contactUri: Uri) { val intent = Intent(Intent.ACTION_VIEW, contactUri) if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void viewContact(Uri contactUri) { Intent intent = new Intent(Intent.ACTION_VIEW, contactUri); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
تعديل جهة اتصال حالية
لتعديل جهة اتصال معروفة، استخدِم الإجراء ACTION_EDIT
، وحدِّد جهة الاتصال مع معرف الموارد المنتظم (URI) content:
لتكون بيانات الغرض، وأدرِج أي معلومات اتصال معروفة في البيانات الإضافية التي تحدّدها
الثوابت في ContactsContract.Intents.Insert
.
هناك طريقتان أساسيتان لاسترداد معرّف الموارد المنتظم (URI) لجهة الاتصال بشكل مبدئي:
- استخدِم معرّف الموارد المنتظم (URI) لجهة الاتصال الذي يعرضه الإجراء
ACTION_PICK
الموضّح في القسم السابق. ولا يتطلب هذا الأسلوب أي أذونات للتطبيق. - يمكنك الوصول إلى قائمة جميع جهات الاتصال مباشرةً، على النحو الموضَّح في استرداد قائمة جهات الاتصال. يتطلّب هذا الأسلوب الحصول على إذن
READ_CONTACTS
.
- الإجراء
ACTION_EDIT
- مخطّط معرّف الموارد المنتظم (URI) للبيانات
content:<URI>
- نوع MIME
- يتم استنتاج النوع من معرّف الموارد المنتظم (URI) لجهة الاتصال.
- العناصر الإضافية
- تم تحديد عنصر واحد أو أكثر من العناصر الإضافية في
ContactsContract.Intents.Insert
حتى تتمكن من ملء حقول تفاصيل الاتصال.
مثال على نيّة الشراء:
Kotlin
fun editContact(contactUri: Uri, email: String) { val intent = Intent(Intent.ACTION_EDIT).apply { data = contactUri putExtra(ContactsContract.Intents.Insert.EMAIL, email) } if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void editContact(Uri contactUri, String email) { Intent intent = new Intent(Intent.ACTION_EDIT); intent.setData(contactUri); intent.putExtra(Intents.Insert.EMAIL, email); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
للحصول على مزيد من المعلومات حول كيفية تعديل جهة اتصال، اطّلِع على المقالة تعديل جهات الاتصال باستخدام الأغراض.
إدراج جهة اتصال
لإدراج جهة اتصال جديدة، استخدِم الإجراء ACTION_INSERT
،
وحدِّد Contacts.CONTENT_TYPE
على أنّه
نوع MIME،
وضمِّن أي معلومات اتصال معروفة في البيانات الإضافية التي تحدّدها
الثوابت في ContactsContract.Intents.Insert
.
- الإجراء
ACTION_INSERT
- مخطّط معرّف الموارد المنتظم (URI) للبيانات
- لا شيء
- نوع MIME
Contacts.CONTENT_TYPE
- العناصر الإضافية
- تم تحديد واحد أو أكثر من العناصر الإضافية في
ContactsContract.Intents.Insert
.
مثال على نيّة الشراء:
Kotlin
fun insertContact(name: String, email: String) { val intent = Intent(Intent.ACTION_INSERT).apply { type = ContactsContract.Contacts.CONTENT_TYPE putExtra(ContactsContract.Intents.Insert.NAME, name) putExtra(ContactsContract.Intents.Insert.EMAIL, email) } if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void insertContact(String name, String email) { Intent intent = new Intent(Intent.ACTION_INSERT); intent.setType(Contacts.CONTENT_TYPE); intent.putExtra(Intents.Insert.NAME, name); intent.putExtra(Intents.Insert.EMAIL, email); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
لمزيد من المعلومات حول كيفية إدراج جهة اتصال، اطّلِع على المقالة تعديل جهات الاتصال باستخدام الأغراض.
عنوان البريد الإلكتروني
إنّ إنشاء رسالة إلكترونية تتضمّن مرفقات اختيارية هو إجراء شائع لتطبيقات البريد الإلكتروني. أنشئ فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ هذا الإجراء باستخدام المعلومات الواردة في القسم التالي.
إنشاء رسالة إلكترونية تتضمّن مرفقات اختيارية
لإنشاء رسالة إلكترونية، استخدِم أحد الإجراءات التالية استنادًا إلى ما إذا كنت تريد تضمين المرفقات أم لا، وضمِّن تفاصيل الرسالة الإلكترونية مثل المستلِم والموضوع باستخدام المفاتيح الإضافية المُدرَجة.
- الإجراء
ACTION_SENDTO
(لبدون مرفق) أو
ACTION_SEND
(لمرفق واحد) أو
ACTION_SEND_MULTIPLE
(لعدة مرفقات)- مخطّط معرّف الموارد المنتظم (URI) للبيانات
- لا شيء
- نوع MIME
-
"text/plain"
"*/*"
- العناصر الإضافية
-
Intent.EXTRA_EMAIL
- مصفوفة سلسلة لجميع عناوين البريد الإلكتروني للمستلمين "إلى".
Intent.EXTRA_CC
- مصفوفة سلسلة لجميع عناوين البريد الإلكتروني للمستلمين "نسخة إلى".
Intent.EXTRA_BCC
- مصفوفة سلسلة لجميع عناوين البريد الإلكتروني للمستلمين "نسخة مخفية الوجهة"
Intent.EXTRA_SUBJECT
- سلسلة تتضمّن موضوع الرسالة الإلكترونية
Intent.EXTRA_TEXT
- سلسلة تتضمّن نص الرسالة الإلكترونية
Intent.EXTRA_STREAM
- رمز
Uri
يشير إلى المرفق. إذا كنت تستخدم الإجراءACTION_SEND_MULTIPLE
، سيتم استخدام الإجراءArrayList
الذي يحتوي على عدة كائناتUri
.
مثال على نيّة الشراء:
Kotlin
fun composeEmail(addresses: Array<String>, subject: String, attachment: Uri) { val intent = Intent(Intent.ACTION_SEND).apply { type = "*/*" putExtra(Intent.EXTRA_EMAIL, addresses) putExtra(Intent.EXTRA_SUBJECT, subject) putExtra(Intent.EXTRA_STREAM, attachment) } if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void composeEmail(String[] addresses, String subject, Uri attachment) { Intent intent = new Intent(Intent.ACTION_SEND); intent.setType("*/*"); intent.putExtra(Intent.EXTRA_EMAIL, addresses); intent.putExtra(Intent.EXTRA_SUBJECT, subject); intent.putExtra(Intent.EXTRA_STREAM, attachment); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
إذا كنت تريد التأكّد من أنّه يتم التعامل مع الغرض من خلال تطبيق بريد إلكتروني فقط، وليس باستخدام تطبيق مراسلة نصية أو تطبيق اجتماعي، استخدِم الإجراء ACTION_SENDTO
مع تضمين مخطط بيانات "mailto:"
كما هو موضّح في المثال التالي:
Kotlin
fun composeEmail(addresses: Array<String>, subject: String) { val intent = Intent(Intent.ACTION_SENDTO).apply { data = Uri.parse("mailto:") // Only email apps handle this. putExtra(Intent.EXTRA_EMAIL, addresses) putExtra(Intent.EXTRA_SUBJECT, subject) } if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void composeEmail(String[] addresses, String subject) { Intent intent = new Intent(Intent.ACTION_SENDTO); intent.setData(Uri.parse("mailto:")); // Only email apps handle this. intent.putExtra(Intent.EXTRA_EMAIL, addresses); intent.putExtra(Intent.EXTRA_SUBJECT, subject); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
مثال على فلتر الأهداف:
<activity ...> <intent-filter> <action android:name="android.intent.action.SEND" /> <data android:type="*/*" /> <category android:name="android.intent.category.DEFAULT" /> </intent-filter> <intent-filter> <action android:name="android.intent.action.SENDTO" /> <data android:scheme="mailto" /> <category android:name="android.intent.category.DEFAULT" /> </intent-filter> </activity>
تخزين الملفات
في ما يلي الإجراءات الشائعة التي تتّبِعها تطبيقات تخزين الملفات، بما في ذلك المعلومات التي تحتاجها لإنشاء فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ كل إجراء.
استرداد نوع معين من الملفات
لتطلب من المستخدم اختيار ملف، مثل مستند أو صورة، وعرض مرجع إلى تطبيقك، استخدِم الإجراء ACTION_GET_CONTENT
وحدِّد نوع MIME المطلوب. إن مرجع الملف الذي تم إرجاعه إلى تطبيقك مؤقت على دورة حياة نشاطك الحالية، لذا إذا كنت تريد الوصول إليه لاحقًا، يجب استيراد نسخة يمكنك قراءتها لاحقًا.
يتيح هذا الغرض أيضًا للمستخدم إنشاء ملف جديد في العملية. على سبيل المثال، بدلاً من تحديد صورة حالية، يمكن للمستخدم التقاط صورة جديدة بالكاميرا.
يتضمن الغرض من النتيجة الذي تم إرساله إلى طريقة onActivityResult()
بيانات باستخدام معرّف موارد منتظم (URI) يشير إلى الملف.
ويمكن أن يكون معرّف الموارد المنتظم (URI) أي شيء، مثل معرّف الموارد المنتظم http:
أو معرّف الموارد المنتظم (URI) file:
أو معرّف الموارد المنتظم (URI) content:
. ومع ذلك، إذا أردت حصر الملفات القابلة للاختيار على الملفات التي يمكن الوصول إليها فقط من موفّر محتوى (معرّف الموارد المنتظم (URI) content:
) والمتاحة كتدفق بيانات باستخدام openFileDescriptor()
، أضِف
فئة CATEGORY_OPENABLE
إلى الغرض.
في نظام التشغيل Android 4.3 (مستوى واجهة برمجة التطبيقات 18) والإصدارات الأحدث، يمكنك أيضًا السماح للمستخدم باختيار ملفات متعددة عن طريق إضافة EXTRA_ALLOW_MULTIPLE
إلى Intent، مع الضبط على true
.
يمكنك بعد ذلك الوصول إلى كل ملف من الملفات المحدّدة في كائن ClipData
الذي يعرضه getClipData()
.
- الإجراء
ACTION_GET_CONTENT
- مخطّط معرّف الموارد المنتظم (URI) للبيانات
- لا شيء
- نوع MIME
- نوع MIME المقابل لنوع الملف الذي يحتاج المستخدم إلى اختياره.
- العناصر الإضافية
-
EXTRA_ALLOW_MULTIPLE
- تشير هذه القيمة إلى ما إذا كان بإمكان المستخدم اختيار أكثر من ملف واحد في الوقت نفسه.
EXTRA_LOCAL_ONLY
- تشير هذه السمة إلى قيمة منطقية توضّح ما إذا كان يجب أن يكون الملف الذي تم إرجاعه متاحًا مباشرةً من الجهاز، بدلاً من اشتراط تنزيله من خدمة عن بُعد.
- Category (الفئة) (اختيارية)
-
CATEGORY_OPENABLE
- لعرض الملفات "القابلة للفتح" فقط التي يمكن تمثيلها كتدفق ملف باستخدام
openFileDescriptor()
.
مثال على نيّة الحصول على صورة:
Kotlin
const val REQUEST_IMAGE_GET = 1 fun selectImage() { val intent = Intent(Intent.ACTION_GET_CONTENT).apply { type = "image/*" } if (intent.resolveActivity(packageManager) != null) { startActivityForResult(intent, REQUEST_IMAGE_GET) } } override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) { if (requestCode == REQUEST_IMAGE_GET && resultCode == Activity.RESULT_OK) { val thumbnail: Bitmap = data.getParcelableExtra("data") val fullPhotoUri: Uri = data.data // Do work with photo saved at fullPhotoUri. ... } }
Java
static final int REQUEST_IMAGE_GET = 1; public void selectImage() { Intent intent = new Intent(Intent.ACTION_GET_CONTENT); intent.setType("image/*"); if (intent.resolveActivity(getPackageManager()) != null) { startActivityForResult(intent, REQUEST_IMAGE_GET); } } @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { if (requestCode == REQUEST_IMAGE_GET && resultCode == RESULT_OK) { Bitmap thumbnail = data.getParcelable("data"); Uri fullPhotoUri = data.getData(); // Do work with photo saved at fullPhotoUri. ... } }
مثال على فلتر الأهداف لعرض صورة:
<activity ...> <intent-filter> <action android:name="android.intent.action.GET_CONTENT" /> <data android:type="image/*" /> <category android:name="android.intent.category.DEFAULT" /> <!-- The OPENABLE category declares that the returned file is accessible from a content provider that supportsOpenableColumns
andContentResolver.openFileDescriptor()
. --> <category android:name="android.intent.category.OPENABLE" /> </intent-filter> </activity>
فتح نوع محدّد من الملفات
بدلاً من استرداد نسخة من ملف يجب استيراده إلى تطبيقك، باستخدام الإجراء ACTION_GET_CONTENT
، عند تشغيل الإصدار 4.4 من نظام التشغيل Android أو إصدار أحدث، يمكنك بدلاً من ذلك طلب فتح ملف يديره تطبيق آخر باستخدام الإجراء ACTION_OPEN_DOCUMENT
وتحديد نوع MIME.
للسماح للمستخدم أيضًا بإنشاء مستند جديد يمكن لتطبيقك الكتابة إليه، يمكنك استخدام إجراء ACTION_CREATE_DOCUMENT
بدلاً من ذلك.
على سبيل المثال، بدلاً من الاختيار من مستندات PDF الحالية، تتيح النية ACTION_CREATE_DOCUMENT
للمستخدمين اختيار المكان الذي يريدون إنشاء مستند جديد فيه، مثلاً داخل تطبيق آخر يدير مساحة تخزين المستند. يتلقى تطبيقك بعد ذلك موقع عنوان URI الذي
يمكنه كتابة المستند الجديد فيه.
في حين أنّ الغرض الذي تم تسليمه إلى طريقة onActivityResult()
من الإجراء ACTION_GET_CONTENT
قد يعرض معرّف موارد منتظم (URI) من أي نوع، فإنّ الغرض من النتيجة من ACTION_OPEN_DOCUMENT
وACTION_CREATE_DOCUMENT
يحدد دائمًا الملف الذي تم اختياره باعتباره معرّف الموارد المنتظم (URI) content:
المتوافق مع DocumentsProvider
. يمكنك فتح الملف باستخدام openFileDescriptor()
والاستعلام عن تفاصيله باستخدام أعمدة من DocumentsContract.Document
.
يؤدي معرّف الموارد المنتظم (URI) الذي يتم عرضه إلى منح تطبيقك إذن الوصول للقراءة على المدى الطويل إلى الملف، مع إمكانية الوصول أيضًا إلى هذا الملف. ويكون إجراء ACTION_OPEN_DOCUMENT
مفيدًا بشكل خاص
عندما تريد قراءة ملف حالي بدون إنشاء نسخة في التطبيق
أو عندما تريد فتح ملف في تطبيقك وتعديله.
ويمكنك أيضًا السماح للمستخدم باختيار عدة ملفات عن طريق إضافة
EXTRA_ALLOW_MULTIPLE
إلى Intent، مع ضبطها على true
.
إذا اختار المستخدم عنصرًا واحدًا فقط، يمكنك استرداد العنصر من getData()
.
إذا اختار المستخدم أكثر من عنصر واحد، ستعرض السمة getData()
قيمة فارغة، وعليك بدلاً من ذلك استرداد كل عنصر من عنصر ClipData
الذي يعرضه getClipData()
.
ملاحظة: يجب أن يحدّد الغرض نوع MIME ويجب أن يتضمّن تعريف الفئة CATEGORY_OPENABLE
. يمكنك تحديد أكثر من نوع MIME واحد إذا كان ذلك مناسبًا من خلال إضافة مصفوفة من أنواع MIME مع إضافة EXTRA_MIME_TYPES
الإضافية. وفي حال إجراء ذلك، عليك ضبط نوع MIME الأساسي في setType()
على "*/*"
.
- الإجراء
ACTION_OPEN_DOCUMENT
أو
ACTION_CREATE_DOCUMENT
- مخطّط معرّف الموارد المنتظم (URI) للبيانات
- لا شيء
- نوع MIME
- نوع MIME المقابل لنوع الملف الذي يحتاج المستخدم إلى اختياره.
- العناصر الإضافية
-
EXTRA_MIME_TYPES
- مصفوفة من أنواع MIME تتوافق مع أنواع الملفات التي يطلبها تطبيقك. عند استخدام هذا العنصر الإضافي، عليك ضبط نوع MIME الأساسي في
setType()
على"*/*"
. EXTRA_ALLOW_MULTIPLE
- تشير هذه القيمة إلى ما إذا كان بإمكان المستخدم اختيار أكثر من ملف واحد في الوقت نفسه.
EXTRA_TITLE
- تُستخدم مع
ACTION_CREATE_DOCUMENT
لتحديد اسم ملف مبدئي. EXTRA_LOCAL_ONLY
- تشير هذه السمة إلى قيمة منطقية توضّح ما إذا كان يجب أن يكون الملف الذي تم إرجاعه متاحًا مباشرةً من الجهاز، بدلاً من اشتراط تنزيله من خدمة عن بُعد.
- الفئة
-
CATEGORY_OPENABLE
- لعرض الملفات "القابلة للفتح" فقط التي يمكن تمثيلها كتدفق ملف باستخدام
openFileDescriptor()
.
مثال على نيّة الحصول على صورة:
Kotlin
const val REQUEST_IMAGE_OPEN = 1 fun selectImage2() { val intent = Intent(Intent.ACTION_OPEN_DOCUMENT).apply { type = "image/*" addCategory(Intent.CATEGORY_OPENABLE) } // Only the system receives the ACTION_OPEN_DOCUMENT, so no need to test. startActivityForResult(intent, REQUEST_IMAGE_OPEN) } override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) { if (requestCode == REQUEST_IMAGE_OPEN && resultCode == Activity.RESULT_OK) { val fullPhotoUri: Uri = data.data // Do work with full size photo saved at fullPhotoUri. ... } }
Java
static final int REQUEST_IMAGE_OPEN = 1; public void selectImage() { Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT); intent.setType("image/*"); intent.addCategory(Intent.CATEGORY_OPENABLE); // Only the system receives the ACTION_OPEN_DOCUMENT, so no need to test. startActivityForResult(intent, REQUEST_IMAGE_OPEN); } @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { if (requestCode == REQUEST_IMAGE_OPEN && resultCode == RESULT_OK) { Uri fullPhotoUri = data.getData(); // Do work with full size photo saved at fullPhotoUri. ... } }
لا يمكن للتطبيقات التابعة لجهات خارجية الاستجابة لهدف من خلال الإجراء
ACTION_OPEN_DOCUMENT
. بدلاً من ذلك، يتلقّى النظام هذه الغاية، ويعرض جميع الملفات المتاحة من التطبيقات المختلفة في واجهة مستخدم موحّدة.
لتوفير ملفات تطبيقك في واجهة المستخدم هذه والسماح للتطبيقات الأخرى بفتحها، عليك تنفيذ DocumentsProvider
وتضمين فلتر أهداف للسمة
PROVIDER_INTERFACE
("android.content.action.DOCUMENTS_PROVIDER"
)، كما هو موضّح في المثال التالي:
<provider ... android:grantUriPermissions="true" android:exported="true" android:permission="android.permission.MANAGE_DOCUMENTS"> <intent-filter> <action android:name="android.content.action.DOCUMENTS_PROVIDER" /> </intent-filter> </provider>
لمزيد من المعلومات حول كيفية إتاحة الملفات التي يديرها تطبيقك للفتح من خلال التطبيقات الأخرى، يُرجى الاطّلاع على فتح الملفات باستخدام إطار عمل أذونات الوصول إلى مساحة التخزين.
الإجراءات المحلية
يُعد الاتصال بسيارة إجراءً محليًا شائعًا. أنشئ فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ هذا الإجراء باستخدام المعلومات الواردة في القسم التالي.
الاتصال بسيارة
لطلب سيارة أجرة، استخدِم الإجراء
ACTION_RESERVE_TAXI_RESERVATION
.
ملاحظة: يجب أن تطلب التطبيقات التأكيد من المستخدم قبل إكمال هذا الإجراء.
- الإجراء
ACTION_RESERVE_TAXI_RESERVATION
- معرّف الموارد المنتظم (URI) للبيانات
- لا شيء
- نوع MIME
- لا شيء
- العناصر الإضافية
- لا شيء
مثال على نيّة الشراء:
Kotlin
fun callCar() { val intent = Intent(ReserveIntents.ACTION_RESERVE_TAXI_RESERVATION) if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void callCar() { Intent intent = new Intent(ReserveIntents.ACTION_RESERVE_TAXI_RESERVATION); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
مثال على فلتر الأهداف:
<activity ...> <intent-filter> <action android:name="com.google.android.gms.actions.RESERVE_TAXI_RESERVATION" /> <category android:name="android.intent.category.DEFAULT" /> </intent-filter> </activity>
Maps
عرض موقع على الخريطة هو إجراء شائع لتطبيقات الخرائط. أنشئ فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ هذا الإجراء باستخدام المعلومات الواردة في القسم التالي.
عرض موقع جغرافي على الخريطة
لفتح خريطة، استخدِم الإجراء ACTION_VIEW
وحدِّد معلومات الموقع الجغرافي في البيانات المتعلّقة بالهدف باستخدام أحد المخطّطات التالية.
- الإجراء
ACTION_VIEW
- مخطّط معرّف الموارد المنتظم (URI) للبيانات
-
geo:latitude,longitude
- اعرض الخريطة على خط الطول وخط العرض المحددَين.
مثال:
"geo:47.6,-122.3"
geo:latitude,longitude?z=zoom
- اعرض الخريطة على خط الطول وخط العرض بمستوى تكبير معيّن. أما مستوى التكبير أو التصغير 1، فيظهر الأرض بأكملها في مركزها خط العرض، lng المحدد. أعلى
(أقرب) مستوى للتكبير هو 23.
مثال:
"geo:47.6,-122.3?z=11"
geo:0,0?q=lat,lng(label)
- اعرض الخريطة على خط الطول وخط العرض المحدَّدين باستخدام تصنيف سلسلة.
مثال:
"geo:0,0?q=34.99,-106.61(Treasure)"
geo:0,0?q=my+street+address
- اعرض الموقع الجغرافي في "عنوان الشارع"، والذي يمكن أن يكون عنوانًا أو طلب بحث عن الموقع الجغرافي.
مثال:
"geo:0,0?q=1600+Amphitheatre+Parkway%2C+CA"
ملاحظة: يجب ترميز كل السلاسل التي يتم تمريرها في معرّف الموارد المنتظم (URI)
geo
. على سبيل المثال، تصبح السلسلة1st & Pike, Seattle
1st%20%26%20Pike%2C%20Seattle
. يتم ترميز المسافات في السلسلة باستخدام%20
أو استبدالها بعلامة الجمع (+
).
- نوع MIME
- لا ينطبق
مثال على نيّة الشراء:
Kotlin
fun showMap(geoLocation: Uri) { val intent = Intent(Intent.ACTION_VIEW).apply { data = geoLocation } if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void showMap(Uri geoLocation) { Intent intent = new Intent(Intent.ACTION_VIEW); intent.setData(geoLocation); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
مثال على فلتر الأهداف:
<activity ...> <intent-filter> <action android:name="android.intent.action.VIEW" /> <data android:scheme="geo" /> <category android:name="android.intent.category.DEFAULT" /> </intent-filter> </activity>
الموسيقى أو الفيديو
في ما يلي الإجراءات الشائعة المتعلّقة بتطبيقات الموسيقى والفيديو، بما في ذلك المعلومات التي تحتاجها لإنشاء فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ كل إجراء.
تشغيل ملف وسائط
لتشغيل ملف موسيقى، استخدِم الإجراء ACTION_VIEW
وحدِّد موقع معرّف الموارد المنتظم (URI) للملف في بيانات الغرض.
- الإجراء
ACTION_VIEW
- مخطّط معرّف الموارد المنتظم (URI) للبيانات
-
file:<URI>
content:<URI>
http:<URL>
- نوع MIME
-
"audio/*"
"application/ogg"
"application/x-ogg"
"application/itunes"
- أو أي رمز آخر يتطلبه تطبيقك.
مثال على نيّة الشراء:
Kotlin
fun playMedia(file: Uri) { val intent = Intent(Intent.ACTION_VIEW).apply { data = file } if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void playMedia(Uri file) { Intent intent = new Intent(Intent.ACTION_VIEW); intent.setData(file); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
مثال على فلتر الأهداف:
<activity ...> <intent-filter> <action android:name="android.intent.action.VIEW" /> <data android:type="audio/*" /> <data android:type="application/ogg" /> <category android:name="android.intent.category.DEFAULT" /> </intent-filter> </activity>
تشغيل الموسيقى بناءً على طلب بحث
لتشغيل الموسيقى استنادًا إلى طلب بحث، استخدِم
هدف INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH
. قد يعمل التطبيق على تنشيط هذا الهدف استجابة
لأمر المستخدم الصوتي لتشغيل الموسيقى. يجري التطبيق المتلقّي لهذه الغاية بحثًا في المستودع الإعلاني لمطابقة المحتوى الحالي مع طلب البحث المحدّد، ويبدأ تشغيل هذا المحتوى.
في هذا الغرض، يمكنك تضمين سلسلة EXTRA_MEDIA_FOCUS
الإضافية
التي تحدِّد وضع البحث المقصود. على سبيل المثال، يمكن أن يحدد وضع البحث ما إذا
كان البحث عن اسم فنان أو اسم أغنية.
- الإجراء
INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH
- مخطّط معرّف الموارد المنتظم (URI) للبيانات
- لا شيء
- نوع MIME
- لا شيء
- العناصر الإضافية
-
MediaStore.EXTRA_MEDIA_FOCUS
(مطلوب)-
تشير هذه السمة إلى وضع البحث: ما إذا كان المستخدم يبحث عن فنّان محدّد أو ألبوم أو أغنية أو قائمة تشغيل معيّنة. تتطلب معظم أوضاع البحث ميزات إضافية. على سبيل المثال، إذا كان المستخدم مهتمًا بالاستماع إلى أغنية معينة، فقد يتضمن الغرض ثلاثة عناصر إضافية إضافية: عنوان الأغنية والفنان والألبوم. يتيح هذا الغرض أوضاع البحث التالية لكل قيمة من قيم
EXTRA_MEDIA_FOCUS
:أي -
"vnd.android.cursor.item/*"
-
السماح بتشغيل أي محتوى موسيقي يشغّل تطبيق الاستقبال بعض المقاطع الموسيقية بناءً على اختيار ذكي، مثل آخر قائمة تشغيل استمع إليها المستخدم.
ميزات إضافية:
QUERY
(مطلوب): سلسلة فارغة. يتم توفير هذه الإضافة الإضافية دائمًا للتوافق مع الأنظمة القديمة. يمكن للتطبيقات الحالية التي لا تتوفّر لها معرفة بأوضاع البحث معالجة هذا الهدف على أنّه بحث غير منظَّم.
غير مهيكلة -
"vnd.android.cursor.item/*"
-
تشغيل أغنية أو ألبوم أو نوع محدّد من طلب بحث غير منظَّم يمكن للتطبيقات إنشاء هدف باستخدام وضع البحث هذا عندما لا تتمكن من تحديد نوع المحتوى الذي يريد المستخدم الاستماع إليه. استخدِم أوضاع بحث أكثر تحديدًا إن أمكن.
ميزات إضافية:
QUERY
(مطلوبة): سلسلة تحتوي على أي تركيبة من الفنان أو الألبوم أو اسم الأغنية أو النوع.
النوع -
Audio.Genres.ENTRY_CONTENT_TYPE
-
تشغيل موسيقى من نوع معيّن
ميزات إضافية:
"android.intent.extra.genre"
(مطلوبة) - النوع.QUERY
(مطلوبة): النوع. يتم توفير هذه الإضافة الإضافية دائمًا للتوافق مع الأنظمة القديمة. يمكن للتطبيقات الحالية التي لا تتوفّر لها معرفة بأوضاع البحث معالجة هذا الهدف على أنّه بحث غير منظَّم.
-
تشغيل موسيقى لفنّان محدّد
ميزات إضافية:
EXTRA_MEDIA_ARTIST
(مطلوب): الفنان."android.intent.extra.genre"
: النوعQUERY
(مطلوبة): سلسلة تحتوي على أي مجموعة من الفنان أو النوع. يتم توفير هذه الإضافة الإضافية دائمًا للتوافق مع الأنظمة القديمة. يمكن للتطبيقات الحالية التي لا تتوفّر لها معرفة بأوضاع البحث معالجة هذا الهدف على أنّها عملية بحث غير منظَّمة.
ألبوم -
Audio.Albums.ENTRY_CONTENT_TYPE
-
تشغيل موسيقى من ألبوم معيّن
ميزات إضافية:
EXTRA_MEDIA_ALBUM
(مطلوب): الألبوم.EXTRA_MEDIA_ARTIST
: الفنان."android.intent.extra.genre"
: النوعQUERY
(مطلوبة): سلسلة تحتوي على أي تركيبة من الألبوم أو الفنان. ويتم توفير هذه الإضافة الإضافية دائمًا للتوافق مع الأنظمة القديمة. يمكن للتطبيقات الحالية التي لا تتوفّر لها معرفة بأوضاع البحث معالجة هذا الهدف على أنّها بحث غير منظَّم.
الأغنية -
"vnd.android.cursor.item/audio"
-
تشغيل أغنية معيّنة
ميزات إضافية:
EXTRA_MEDIA_ALBUM
: الألبوم.EXTRA_MEDIA_ARTIST
: الفنان."android.intent.extra.genre"
: النوعEXTRA_MEDIA_TITLE
(مطلوب): اسم الأغنية.QUERY
(مطلوبة): سلسلة تحتوي على أي مجموعة من الألبوم أو الفنان أو النوع أو العنوان. ويتم توفير هذه الإضافة الإضافية دائمًا للتوافق مع الأنظمة القديمة. يمكن للتطبيقات الحالية التي لا تتوفّر لها معرفة بأوضاع البحث معالجة هذا الغرض كبحث غير منظَّم.
قائمة التشغيل -
Audio.Playlists.ENTRY_CONTENT_TYPE
-
لتشغيل قائمة تشغيل معينة أو قائمة تشغيل مطابقة لبعض المعايير المحددة في محتوى إضافي إضافي.
ميزات إضافية:
EXTRA_MEDIA_ALBUM
: الألبوم.EXTRA_MEDIA_ARTIST
: الفنان."android.intent.extra.genre"
: النوع"android.intent.extra.playlist"
: قائمة التشغيلEXTRA_MEDIA_TITLE
: اسم الأغنية التي تستند إليها قائمة التشغيل.QUERY
(مطلوبة): سلسلة تحتوي على أي مجموعة من الألبوم أو الفنان أو النوع أو قائمة التشغيل أو العنوان. يتم توفير هذه الإضافة الإضافية دائمًا للتوافق مع الأنظمة القديمة. يمكن للتطبيقات الحالية التي لا تتوفّر لها معرفة بأوضاع البحث معالجة هذا الهدف على أنّه بحث غير منظَّم.
مثال على نيّة الشراء:
إذا أراد المستخدم الاستماع إلى موسيقى من فنان معيّن، قد ينشئ أحد تطبيقات البحث القصد التالي:
Kotlin
fun playSearchArtist(artist: String) { val intent = Intent(MediaStore.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH).apply { putExtra(MediaStore.EXTRA_MEDIA_FOCUS, MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE) putExtra(MediaStore.EXTRA_MEDIA_ARTIST, artist) putExtra(SearchManager.QUERY, artist) } if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void playSearchArtist(String artist) { Intent intent = new Intent(MediaStore.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH); intent.putExtra(MediaStore.EXTRA_MEDIA_FOCUS, MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE); intent.putExtra(MediaStore.EXTRA_MEDIA_ARTIST, artist); intent.putExtra(SearchManager.QUERY, artist); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
مثال على فلتر الأهداف:
<activity ...> <intent-filter> <action android:name="android.media.action.MEDIA_PLAY_FROM_SEARCH" /> <category android:name="android.intent.category.DEFAULT" /> </intent-filter> </activity>
عند التعامل مع هذا الهدف في نشاطك، تحقَّق من قيمة
EXTRA_MEDIA_FOCUS
الإضافة الإضافية في الرسالة الواردة
Intent
لتحديد وضع البحث. بعد تحديد نشاطك لوضع البحث، اقرأ قيم العناصر الإضافية
الإضافية لوضع البحث المحدد هذا.
وباستخدام هذه المعلومات، يمكن لتطبيقك عندئذٍ إجراء البحث في المستودع لتشغيل المحتوى الذي يطابق طلب البحث. ويظهر ذلك في المثال التالي.
Kotlin
override fun onCreate(savedInstanceState: Bundle?) { ... if (intent.action.compareTo(MediaStore.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH) == 0) { val mediaFocus: String? = intent.getStringExtra(MediaStore.EXTRA_MEDIA_FOCUS) val query: String? = intent.getStringExtra(SearchManager.QUERY) // Some of these extras might not be available depending on the search mode. val album: String? = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ALBUM) val artist: String? = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ARTIST) val genre: String? = intent.getStringExtra("android.intent.extra.genre") val playlist: String? = intent.getStringExtra("android.intent.extra.playlist") val title: String? = intent.getStringExtra(MediaStore.EXTRA_MEDIA_TITLE) // Determine the search mode and use the corresponding extras. when { mediaFocus == null -> { // 'Unstructured' search mode (backward compatible) playUnstructuredSearch(query) } mediaFocus.compareTo("vnd.android.cursor.item/*") == 0 -> { if (query?.isNotEmpty() == true) { // 'Unstructured' search mode. playUnstructuredSearch(query) } else { // 'Any' search mode. playResumeLastPlaylist() } } mediaFocus.compareTo(MediaStore.Audio.Genres.ENTRY_CONTENT_TYPE) == 0 -> { // 'Genre' search mode. playGenre(genre) } mediaFocus.compareTo(MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE) == 0 -> { // 'Artist' search mode. playArtist(artist, genre) } mediaFocus.compareTo(MediaStore.Audio.Albums.ENTRY_CONTENT_TYPE) == 0 -> { // 'Album' search mode. playAlbum(album, artist) } mediaFocus.compareTo("vnd.android.cursor.item/audio") == 0 -> { // 'Song' search mode. playSong(album, artist, genre, title) } mediaFocus.compareTo(MediaStore.Audio.Playlists.ENTRY_CONTENT_TYPE) == 0 -> { // 'Playlist' search mode. playPlaylist(album, artist, genre, playlist, title) } } } }
Java
protected void onCreate(Bundle savedInstanceState) { //... Intent intent = this.getIntent(); if (intent.getAction().compareTo(MediaStore.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH) == 0) { String mediaFocus = intent.getStringExtra(MediaStore.EXTRA_MEDIA_FOCUS); String query = intent.getStringExtra(SearchManager.QUERY); // Some of these extras might not be available depending on the search mode. String album = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ALBUM); String artist = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ARTIST); String genre = intent.getStringExtra("android.intent.extra.genre"); String playlist = intent.getStringExtra("android.intent.extra.playlist"); String title = intent.getStringExtra(MediaStore.EXTRA_MEDIA_TITLE); // Determine the search mode and use the corresponding extras. if (mediaFocus == null) { // 'Unstructured' search mode (backward compatible). playUnstructuredSearch(query); } else if (mediaFocus.compareTo("vnd.android.cursor.item/*") == 0) { if (query.isEmpty()) { // 'Any' search mode. playResumeLastPlaylist(); } else { // 'Unstructured' search mode. playUnstructuredSearch(query); } } else if (mediaFocus.compareTo(MediaStore.Audio.Genres.ENTRY_CONTENT_TYPE) == 0) { // 'Genre' search mode. playGenre(genre); } else if (mediaFocus.compareTo(MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE) == 0) { // 'Artist' search mode. playArtist(artist, genre); } else if (mediaFocus.compareTo(MediaStore.Audio.Albums.ENTRY_CONTENT_TYPE) == 0) { // 'Album' search mode. playAlbum(album, artist); } else if (mediaFocus.compareTo("vnd.android.cursor.item/audio") == 0) { // 'Song' search mode. playSong(album, artist, genre, title); } else if (mediaFocus.compareTo(MediaStore.Audio.Playlists.ENTRY_CONTENT_TYPE) == 0) { // 'Playlist' search mode. playPlaylist(album, artist, genre, playlist, title); } } }
ملاحظة جديدة
يعد إنشاء ملاحظة إجراءً شائعًا لتطبيقات تدوين الملاحظات. أنشئ فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ هذا الإجراء باستخدام المعلومات الواردة في القسم التالي.
إنشاء ملاحظة
لإنشاء ملاحظة جديدة، يمكنك استخدام الإجراء
ACTION_CREATE_NOTE
وتحديد تفاصيل الملاحظة مثل الموضوع والنص باستخدام الإضافات التالية.
ملاحظة: يجب أن تطلب التطبيقات التأكيد من المستخدم قبل إكمال هذا الإجراء.
- الإجراء
-
ACTION_CREATE_NOTE
- مخطّط معرّف الموارد المنتظم (URI) للبيانات
- لا شيء
- نوع MIME
-
PLAIN_TEXT_TYPE
- "*/*"
- العناصر الإضافية
-
-
EXTRA_NAME
- سلسلة تشير إلى عنوان الملاحظة أو موضوعها
-
EXTRA_TEXT
- سلسلة تشير إلى نص الملاحظة.
-
- الإجراء
-
ACTION_DIAL
- فتح تطبيق برنامج الاتصال أو الهاتفACTION_CALL
- إجراء مكالمة هاتفية (يتطلب ذلك إذنCALL_PHONE
)
- مخطّط معرّف الموارد المنتظم (URI) للبيانات
-
tel:<phone-number>
voicemail:<phone-number>
- نوع MIME
- لا ينطبق
tel:2125551212
tel:(212) 555 1212
- الإجراء
-
"com.google.android.gms.actions.SEARCH_ACTION"
- إتاحة طلبات البحث من "الإجراءات الصوتية من Google".
- العناصر الإضافية
-
QUERY
- سلسلة تحتوي على طلب البحث.
- الإجراء
ACTION_WEB_SEARCH
- مخطّط معرّف الموارد المنتظم (URI) للبيانات
- لا شيء
- نوع MIME
- لا شيء
- العناصر الإضافية
-
SearchManager.QUERY
- سلسلة البحث
- الإجراء
-
ACTION_SETTINGS
ACTION_WIRELESS_SETTINGS
ACTION_AIRPLANE_MODE_SETTINGS
ACTION_WIFI_SETTINGS
ACTION_APN_SETTINGS
ACTION_BLUETOOTH_SETTINGS
ACTION_DATE_SETTINGS
ACTION_LOCALE_SETTINGS
ACTION_INPUT_METHOD_SETTINGS
ACTION_DISPLAY_SETTINGS
ACTION_SECURITY_SETTINGS
ACTION_LOCATION_SOURCE_SETTINGS
ACTION_INTERNAL_STORAGE_SETTINGS
ACTION_MEMORY_CARD_SETTINGS
للتعرّف على شاشات الإعدادات الإضافية المتاحة، يُرجى الاطّلاع على مستندات
Settings
. - مخطّط معرّف الموارد المنتظم (URI) للبيانات
- لا شيء
- نوع MIME
- لا ينطبق
- الإجراء
ACTION_SENDTO
أو
ACTION_SEND
أو
ACTION_SEND_MULTIPLE
- مخطّط معرّف الموارد المنتظم (URI) للبيانات
-
sms:<phone_number>
smsto:<phone_number>
mms:<phone_number>
mmsto:<phone_number>
يتم التعامل مع جميع هذه المخططات بالطريقة نفسها.
- نوع MIME
-
"text/plain"
"image/*"
"video/*"
- العناصر الإضافية
-
"subject"
- سلسلة لموضوع الرسالة (عادةً ما تكون رسائل الوسائط المتعددة فقط)
"sms_body"
- سلسلة للرسالة النصية
EXTRA_STREAM
- علامة
Uri
تشير إلى الصورة أو الفيديو المطلوب إرفاقه في حال استخدام الإجراءACTION_SEND_MULTIPLE
، سيكون هذا العنصر الإضافيArrayList
منUri
عنصر يشير إلى الصور أو الفيديوهات لإرفاقها.
- الإجراء
ACTION_VIEW
- مخطّط معرّف الموارد المنتظم (URI) للبيانات
http:<URL>
https:<URL>
- نوع MIME
-
"text/plain"
"text/html"
"application/xhtml+xml"
"application/vnd.wap.xhtml+xml"
- عليك إعداد جهاز Android للتطوير أو استخدام جهاز افتراضي.
- ثبِّت إصدارًا من تطبيقك يحدِّد الأهداف التي تريد إتاحة الوصول إليها.
- تنشيط هدف باستخدام
adb
:adb shell am start -a <ACTION> -t <MIME_TYPE> -d <DATA> \ -e <EXTRA_NAME> <EXTRA_VALUE> -n <ACTIVITY>
مثلاً:
adb shell am start -a android.intent.action.DIAL \ -d tel:555-5555 -n org.example.MyApp/.MyActivity
- وفي حال تحديد فلاتر الأهداف المطلوبة، يمكنك التعامل مع الغرض.
مثال على نيّة الشراء:
Kotlin
fun createNote(subject: String, text: String) { val intent = Intent(NoteIntents.ACTION_CREATE_NOTE).apply { putExtra(NoteIntents.EXTRA_NAME, subject) putExtra(NoteIntents.EXTRA_TEXT, text) } if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void createNote(String subject, String text) { Intent intent = new Intent(NoteIntents.ACTION_CREATE_NOTE) .putExtra(NoteIntents.EXTRA_NAME, subject) .putExtra(NoteIntents.EXTRA_TEXT, text); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
مثال على فلتر الأهداف:
<activity ...> <intent-filter> <action android:name="com.google.android.gms.actions.CREATE_NOTE" /> <category android:name="android.intent.category.DEFAULT" /> <data android:mimeType="*/*" /> </intent-filter> </activity>
الهاتف
يُعد بدء مكالمة من الإجراءات الشائعة لتطبيقات الهاتف. أنشئ فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ هذا الإجراء باستخدام المعلومات الواردة في القسم التالي.
بدء مكالمة هاتفية
لفتح تطبيق الهاتف وطلب رقم هاتف، استخدِم الإجراء ACTION_DIAL
وحدِّد رقم هاتف باستخدام نظام URI التالي. عندما يتم فتح تطبيق الهاتف، يتم عرض رقم الهاتف،
ويجب على المستخدم النقر على الزر اتصال لبدء المكالمة الهاتفية.
لإجراء مكالمة هاتفية مباشرةً، يمكنك استخدام الإجراء ACTION_CALL
وتحديد رقم هاتف باستخدام مخطط URI التالي. عند فتح تطبيق الهاتف، يبدأ
المكالمة الهاتفية. لا يحتاج المستخدم إلى النقر على زر الاتصال.
يتطلّب الإجراء ACTION_CALL
إضافة الإذن CALL_PHONE
إلى ملف البيان:
<uses-permission android:name="android.permission.CALL_PHONE" />
أرقام الهاتف الصالحة هي تلك المعرّفات في معيار RFC 3966 التابع لمجموعة مهندسي شبكة الإنترنت (IETF). في ما يلي أمثلة على الإعلانات الصالحة:
يعد برنامج الاتصال في تطبيق الهاتف جيدًا في تسوية المخططات، مثل
أرقام الهواتف. لذلك، فإن المخطط الموضّح غير مطلوب تمامًا في طريقة
Uri.parse()
.
مع ذلك، إذا لم تكن قد جربت مخططًا أو لم تكن متأكدًا مما إذا كان
يمكن التعامل معه، استخدِم الطريقة Uri.fromParts()
بدلاً من ذلك.
مثال على نيّة الشراء:
Kotlin
fun dialPhoneNumber(phoneNumber: String) { val intent = Intent(Intent.ACTION_DIAL).apply { data = Uri.parse("tel:$phoneNumber") } if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void dialPhoneNumber(String phoneNumber) { Intent intent = new Intent(Intent.ACTION_DIAL); intent.setData(Uri.parse("tel:" + phoneNumber)); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
بحث
في ما يلي الإجراءات الشائعة التي يتم اتخاذها لتطبيقات البحث، بما في ذلك المعلومات التي تحتاجها لإنشاء فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ كل إجراء.
البحث باستخدام تطبيق معيّن
لإتاحة البحث في سياق تطبيقك، عرِّف عن فلتر الأهداف في تطبيقك باستخدام الإجراء SEARCH_ACTION
، كما هو موضّح في مثال فلتر الأهداف التالي.
ملاحظة: لا ننصح باستخدام SEARCH_ACTION
للبحث في التطبيقات.
بدلاً من ذلك، يمكنك تنفيذ إجراء
GET_THING
للاستفادة من دعم "مساعد Google" المضمَّن في عمليات البحث داخل التطبيق. للحصول على مزيد من المعلومات، يمكنك الاطّلاع على مستندات إجراءات التطبيقات في "مساعد Google".
مثال على فلتر الأهداف:
<activity android:name=".SearchActivity"> <intent-filter> <action android:name="com.google.android.gms.actions.SEARCH_ACTION"/> <category android:name="android.intent.category.DEFAULT"/> </intent-filter> </activity>
إجراء بحث على الويب
لبدء بحث ويب، استخدِم الإجراء ACTION_WEB_SEARCH
وحدِّد سلسلة البحث في علامة SearchManager.QUERY
الإضافية.
مثال على نيّة الشراء:
Kotlin
fun searchWeb(query: String) { val intent = Intent(Intent.ACTION_WEB_SEARCH).apply { putExtra(SearchManager.QUERY, query) } if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void searchWeb(String query) { Intent intent = new Intent(Intent.ACTION_WEB_SEARCH); intent.putExtra(SearchManager.QUERY, query); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
الإعدادات
لفتح شاشة في تطبيق "إعدادات النظام" عندما يطلب تطبيقك من المستخدم تغيير شيء ما، استخدِم أحد إجراءات الغرض التالية:
مثال على نيّة الشراء:
Kotlin
fun openWifiSettings() { val intent = Intent(Settings.ACTION_WIFI_SETTINGS) if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void openWifiSettings() { Intent intent = new Intent(Settings.ACTION_WIFI_SETTINGS); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
المراسلة النصية
يعتبر إنشاء رسالة قصيرة SMS/رسالة وسائط متعددة MMS مع مرفق واحد إجراءً شائعًا في تطبيقات المراسلة النصية. أنشئ فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ هذا الإجراء باستخدام المعلومات الواردة في القسم التالي.
إنشاء رسالة قصيرة SMS/رسالة وسائط متعددة MMS تتضمّن مرفقًا
لبدء رسالة قصيرة SMS أو رسالة وسائط متعددة MMS، استخدم أحد إجراءات الغرض التالية وحدِّد تفاصيل الرسالة مثل رقم الهاتف والموضوع ونص الرسالة باستخدام المفاتيح الإضافية التالية.
مثال على نيّة الشراء:
Kotlin
fun composeMmsMessage(message: String, attachment: Uri) { val intent = Intent(Intent.ACTION_SENDTO).apply { type = HTTP.PLAIN_TEXT_TYPE putExtra("sms_body", message) putExtra(Intent.EXTRA_STREAM, attachment) } if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void composeMmsMessage(String message, Uri attachment) { Intent intent = new Intent(Intent.ACTION_SENDTO); intent.setType(HTTP.PLAIN_TEXT_TYPE); intent.putExtra("sms_body", message); intent.putExtra(Intent.EXTRA_STREAM, attachment); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
إذا كنت تريد التأكّد من أنّه يتم التعامل مع الغرض من خلال تطبيق مراسلة نصية فقط، وليس من خلال تطبيقات بريد إلكتروني أو اجتماعية أخرى، عليك استخدام إجراء ACTION_SENDTO
وتضمين مخطط بيانات "smsto:"
كما هو موضّح في المثال التالي:
Kotlin
fun composeMmsMessage(message: String, attachment: Uri) { val intent = Intent(Intent.ACTION_SEND).apply { data = Uri.parse("smsto:") // Only SMS apps respond to this. putExtra("sms_body", message) putExtra(Intent.EXTRA_STREAM, attachment) } if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void composeMmsMessage(String message, Uri attachment) { Intent intent = new Intent(Intent.ACTION_SEND); intent.setData(Uri.parse("smsto:")); // Only SMS apps respond to this. intent.putExtra("sms_body", message); intent.putExtra(Intent.EXTRA_STREAM, attachment); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
مثال على فلتر الأهداف:
<activity ...> <intent-filter> <action android:name="android.intent.action.SEND" /> <data android:type="text/plain" /> <data android:type="image/*" /> <category android:name="android.intent.category.DEFAULT" /> </intent-filter> </activity>
ملاحظة: إذا كنت تعمل على تطوير تطبيق لرسائل SMS/رسائل وسائط متعددة، ينبغي لك تنفيذ فلاتر الأهداف للعديد من الإجراءات الإضافية حتى تتوفر كتطبيق الرسائل القصيرة SMS الافتراضي في الإصدار 4.4 من نظام التشغيل Android والإصدارات الأحدث. لمزيد من المعلومات، يمكنك الاطّلاع على المستندات
على "Telephony
".
متصفح الويب
تحميل عنوان URL على الويب هو إجراء شائع لتطبيقات متصفح الويب. أنشئ فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ هذا الإجراء باستخدام المعلومات الواردة في القسم التالي.
تحميل عنوان URL على الويب
لفتح صفحة ويب، استخدِم الإجراء ACTION_VIEW
وحدِّد عنوان URL على الويب في بيانات الغرض.
مثال على نيّة الشراء:
Kotlin
fun openWebPage(url: String) { val webpage: Uri = Uri.parse(url) val intent = Intent(Intent.ACTION_VIEW, webpage) if (intent.resolveActivity(packageManager) != null) { startActivity(intent) } }
Java
public void openWebPage(String url) { Uri webpage = Uri.parse(url); Intent intent = new Intent(Intent.ACTION_VIEW, webpage); if (intent.resolveActivity(getPackageManager()) != null) { startActivity(intent); } }
مثال على فلتر الأهداف:
<activity ...> <intent-filter> <action android:name="android.intent.action.VIEW" /> <!-- Include the host attribute if you want your app to respond only to URLs with your app's domain. --> <data android:scheme="http" android:host="www.example.com" /> <category android:name="android.intent.category.DEFAULT" /> <!-- The BROWSABLE category is required to get links from web pages. --> <category android:name="android.intent.category.BROWSABLE" /> </intent-filter> </activity>
نصيحة: إذا كان تطبيق Android يوفّر وظائف مشابهة لموقعك الإلكتروني، يمكنك تضمين فلتر أهداف لعناوين URL التي تشير إلى موقعك الإلكتروني. بعد ذلك، في حال ثبَّت المستخدمون تطبيقك، ستفتح الروابط من الرسائل الإلكترونية أو صفحات الويب الأخرى التي تشير إلى موقعك الإلكتروني تطبيق Android بدلاً من صفحة الويب. اطّلِع على مزيد من المعلومات في مقالة التعامل مع "روابط تطبيقات Android".
بدءًا من نظام التشغيل Android 12 (مستوى واجهة برمجة التطبيقات 31)، ينتقل هدف الويب العام إلى نشاط في تطبيقك فقط إذا تمت الموافقة على تطبيقك للنطاق المحدَّد المضمَّن في هدف الويب هذا. إذا لم تتم الموافقة على تطبيقك في النطاق، يتم حل قصد الويب لتطبيق المتصفح التلقائي للمستخدم بدلاً من ذلك.
التحقّق من الأغراض باستخدام Android Debug Bridge
للتأكّد من أنّ تطبيقك يستجيب للأغراض التي تريد دعمها، يمكنك استخدام أداة
adb
لتنشيط أهداف محدّدة من خلال تنفيذ
ما يلي:
لمزيد من المعلومات، يُرجى الاطّلاع على مشكلة أوامر واجهة المستخدم.