يتيح لك الغرض بدء نشاط في تطبيق آخر من خلال وصف الإجراء الذي تريد تنفيذه، مثل "عرض خريطة" أو "التقاط صورة" في عنصر Intent
. يُطلق على هذا النوع من الأغراض اسم هدف ضمني لأنّه لا يحدّد مكوّن التطبيق للبدء، بل يحدّد بدلاً من ذلك إجراءً ويقدّم بعض البيانات التي سيتم من خلالها تنفيذ الإجراء.
عند طلب الرمز startActivity()
أو startActivityForResult()
وإدخال هدف ضمني له، يعمل النظام
على تحليل
الغرض إلى تطبيق يمكنه معالجة الغرض ويبدأ
Activity
المقابل له. وإذا كان هناك أكثر من تطبيق واحد يمكنه معالجة الهدف، سيعرض النظام للمستخدم مربّع حوار لاختيار التطبيق الذي يريد استخدامه.
توضّح هذه الصفحة العديد من الأغراض الضمنية التي يمكنك استخدامها لتنفيذ إجراءات شائعة، ويتم تنظيمها حسب نوع التطبيق الذي يعالج الغرض. ويوضّح كل قسم أيضًا كيفية إنشاء فلتر النية للإعلان عن قدرة تطبيقك على تنفيذ الإجراء.
تحذير: إذا لم يكن هناك تطبيقات على الجهاز يمكنها
أن تتلقّى هدفًا ضمنيًا، يتعطّل أحد التطبيقات عند الاتصال بالرقم startActivity()
. للتحقّق أولاً من توفُّر تطبيق لتلقّي intent، استدعِ resolveActivity()
على عنصر Intent
. إذا لم تكن النتيجة خالية، يتوفّر تطبيق واحد على الأقل يمكنه معالجة الغرض، ويمكن طلب الرقم startActivity()
بأمان. إذا كانت النتيجة
فارغة، لا تستخدم intent، وإذا أمكن، أوقِف
الميزة التي تستدعي الغرض.
إذا لم تكن على دراية بكيفية إنشاء فلاتر الأهداف أو الأهداف، اطّلِع أولاً على فلاتر الأهداف والأهداف.
للتعرّف على كيفية تنشيط عناصر intent الواردة في هذه الصفحة من مضيف تطوير البرامج، راجِع قسم التحقق من الأغراض باستخدام مجموعة إعدادات Android Debug Bridge.
الإجراءات الصوتية من Google
تعمل الإجراءات الصوتية من Google على تنشيط بعض الأغراض المدرَجة في هذه الصفحة استجابةً للطلبات الصوتية. لمزيد من المعلومات، راجِع بدء استخدام الإجراءات الصوتية للنظام.
منبّه
في ما يلي الإجراءات الشائعة التي يمكن اتخاذها لتطبيقات المنبّهات، بما في ذلك المعلومات التي تحتاج إليها لإنشاء فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ كل إجراء.
ضبط منبّه
لإنشاء تنبيه جديد، استخدم الإجراء 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
، يجب أن يحصل تطبيقك على
إذن 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
، يجب أن يحصل تطبيقك على
إذن 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>
تقويم Google
إضافة حدث هو إجراء شائع لتطبيقات التقويم. أنشئ فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ هذا الإجراء باستخدام المعلومات الواردة في القسم التالي.
إضافة حدث في التقويم
لإضافة حدث جديد إلى تقويم المستخدم، استخدِم الإجراء
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
على النحو الموضّح في القسم السابق. وتمنحك النتيجة إمكانية الوصول المباشر إلى البيانات المطلوبة بدون الحاجة إلى إجراء طلب بحث أكثر تعقيدًا في Contacts Provider.
تحتوي النتيجة 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:
كبيانات الغرض.
هناك طريقتان أساسيتان لاسترداد عنوان URI لجهة الاتصال بشكل مبدئي:
- استخدِم معرّف الموارد المنتظم (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) أي شيء، مثل معرّف الموارد المنتظم (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_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
إلى الغرض المحدّد من خلال الضبط على 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) للملف في بيانات intent.
- الإجراء
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 أو رسالة وسائط متعددة تتضمّن مرفقًا
لبدء رسالة قصيرة (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>
ملاحظة: إذا كنت تعمل على تطوير تطبيق للرسائل القصيرة/رسائل الوسائط المتعددة، يجب عليك تنفيذ فلاتر الأهداف للعديد من الإجراءات الإضافية حتى تصبح تطبيق الرسائل القصيرة التلقائي على نظام التشغيل Android 4.4 والإصدارات الأحدث. لمزيد من المعلومات، يمكنك الاطّلاع على المستندات
على الرابط 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
لتنشيط أغراض معيّنة من خلال تنفيذ
ما يلي:
لمزيد من المعلومات، يُرجى الاطّلاع على مشكلة أوامر واجهة المستخدم.