النوايا الشائعة

يتيح لك الغرض بدء نشاط في تطبيق آخر من خلال وصف الإجراء الذي تريد تنفيذه، مثل "عرض خريطة" أو "التقاط صورة" في عنصر Intent. يُطلق على هذا النوع من الأغراض اسم هدف ضمني لأنّه لا يحدّد مكوّن التطبيق للبدء، بل يحدّد بدلاً من ذلك إجراءً ويقدّم بعض البيانات التي سيتم من خلالها تنفيذ الإجراء.

عند طلب الرمز startActivity() أو startActivityForResult() وإدخال هدف ضمني له، يعمل النظام على تحليل الغرض إلى تطبيق يمكنه معالجة الغرض ويبدأ Activity المقابل له. وإذا كان هناك أكثر من تطبيق واحد يمكنه معالجة الهدف، سيعرض النظام للمستخدم مربّع حوار لاختيار التطبيق الذي يريد استخدامه.

توضّح هذه الصفحة العديد من الأغراض الضمنية التي يمكنك استخدامها لتنفيذ إجراءات شائعة، ويتم تنظيمها حسب نوع التطبيق الذي يعالج الغرض. ويوضّح كل قسم أيضًا كيفية إنشاء فلتر النية للإعلان عن قدرة تطبيقك على تنفيذ الإجراء.

تحذير: إذا لم يكن هناك تطبيقات على الجهاز يمكنها أن تتلقّى هدفًا ضمنيًا، يتعطّل أحد التطبيقات عند الاتصال بالرقم startActivity(). للتحقّق أولاً من توفُّر تطبيق لتلقّي intent، استدعِ resolveActivity() على عنصر Intent. إذا لم تكن النتيجة خالية، يتوفّر تطبيق واحد على الأقل يمكنه معالجة الغرض، ويمكن طلب الرقم startActivity() بأمان. إذا كانت النتيجة فارغة، لا تستخدم intent، وإذا أمكن، أوقِف الميزة التي تستدعي الغرض.

إذا لم تكن على دراية بكيفية إنشاء فلاتر الأهداف أو الأهداف، اطّلِع أولاً على فلاتر الأهداف والأهداف.

للتعرّف على كيفية تنشيط عناصر intent الواردة في هذه الصفحة من مضيف تطوير البرامج، راجِع قسم التحقق من الأغراض باستخدام مجموعة إعدادات Android Debug Bridge.

الإجراءات الصوتية من Google

تعمل الإجراءات الصوتية من Google على تنشيط بعض الأغراض المدرَجة في هذه الصفحة استجابةً للطلبات الصوتية. لمزيد من المعلومات، راجِع بدء استخدام الإجراءات الصوتية للنظام.

منبّه

في ما يلي الإجراءات الشائعة التي يمكن اتخاذها لتطبيقات المنبّهات، بما في ذلك المعلومات التي تحتاج إليها لإنشاء فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ كل إجراء.

ضبط منبّه

الإجراءات الصوتية من Google

  • "ضبط منبّه الساعة 7 صباحًا"

لإنشاء تنبيه جديد، استخدم الإجراء 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>

إنشاء موقّت

الإجراءات الصوتية من Google

  • "ضبط موقّت لمدة 5 دقائق"

لإنشاء موقّت عد تنازلي، استخدِم الإجراء 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".

تشغيل تطبيق الكاميرا في وضع الصور الثابتة

الإجراءات الصوتية من Google

  • "أريد التقاط صورة"

لفتح تطبيق كاميرا في وضع الصور الثابتة، استخدِم الإجراء 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>

بدء تطبيق كاميرا في وضع الفيديو

الإجراءات الصوتية من Google

  • "تسجيل فيديو"

لفتح تطبيق كاميرا في وضع الفيديو، استخدِم إجراء 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 supports OpenableColumns
             and ContentResolver.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>

لمزيد من المعلومات حول كيفية جعل الملفات التي يديرها تطبيقك قابلة للفتح من تطبيقات أخرى، يُرجى الاطّلاع على المقالة فتح الملفات باستخدام إطار عمل أذونات الوصول إلى مساحة التخزين.

الإجراءات المحلية

يُعد طلب السيارة إجراءً محليًا شائعًا. أنشئ فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ هذا الإجراء باستخدام المعلومات الواردة في القسم التالي.

الاتصال بسيارة

الإجراءات الصوتية من Google

  • "أريد الحصول على سيارة أجرة"
  • "الاتصال بي بسيارة"

(Wear OS فقط)

للاتصال بسيارة أجرة، استخدِم إجراء 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>

تشغيل الموسيقى بناءً على طلب بحث

الإجراءات الصوتية من Google

  • "تشغيل أغنية مايكل جاكسون شيرين"،

لتشغيل الموسيقى استنادًا إلى طلب بحث، استخدِم 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 (مطلوب): النوع. ويتم توفير هذه الإضافة دائمًا من أجل التوافق مع الأنظمة القديمة. ويمكن للتطبيقات الحالية التي لا تعرف عن أوضاع البحث معالجة هذا الغرض على أنه بحث غير منظَّم.

فنان - Audio.Artists.ENTRY_CONTENT_TYPE

تشغيل موسيقى لفنّان محدّد

الميزات الإضافية الإضافية:

  • 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
سلسلة تشير إلى نص الملاحظة.

مثال على النية:

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) التالي. عندما يتم فتح تطبيق الهاتف، يتم عرض رقم الهاتف، ويجب على المستخدم النقر على الزر اتصال لبدء المكالمة الهاتفية.

الإجراءات الصوتية من Google

  • "الاتصال برقم 555-5555"
  • "الاتصال ببوب"
  • "الاتصال بالبريد الصوتي"

لإجراء مكالمة هاتفية مباشرةً، يمكنك استخدام الإجراء ACTION_CALL وتحديد رقم هاتف باستخدام نظام URI التالي. عند فتح تطبيق الهاتف، يبدأ المكالمة الهاتفية. ولا يحتاج المستخدم إلى النقر على زر الاتصال.

يتطلب الإجراء ACTION_CALL إضافة إذن "CALL_PHONE" إلى ملف البيان:

<uses-permission android:name="android.permission.CALL_PHONE" />
الإجراء
  • ACTION_DIAL - يتم فتح تطبيق برنامج الاتصال أو الهاتف.
  • ACTION_CALL - إجراء مكالمة هاتفية (يتطلب ذلك إذن CALL_PHONE)
مخطط معرّف الموارد المنتظم (URI) للبيانات
  • tel:<phone-number>
  • voicemail:<phone-number>
نوع MIME
بدون إشراف

أرقام الهاتف الصالحة هي تلك المحدّدة في معيار RFC 3966 التابع لمجموعة مهندسي شبكة الإنترنت (IETF). في ما يلي أمثلة على المحتوى الصالح:

  • tel:2125551212
  • tel:(212) 555 1212

يعد برنامج الاتصال في تطبيق "الهاتف" جيدًا في تسوية المخططات، مثل أرقام الهواتف. وبالتالي، فإنّ المخطط الموضّح غير مطلوب تمامًا في طريقة 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);
    }
}

في ما يلي الإجراءات الشائعة التي يجب اتخاذها بشأن تطبيقات البحث، بما في ذلك المعلومات التي تحتاج إليها لإنشاء فلتر أهداف للإعلان عن قدرة تطبيقك على تنفيذ كل إجراء.

البحث باستخدام تطبيق معيّن

الإجراءات الصوتية من Google

  • "أريد البحث عن فيديوهات عن القطط على myvideoapp"

لإتاحة البحث في سياق تطبيقك، حدِّد فلتر أهداف في تطبيقك باستخدام الإجراء SEARCH_ACTION، كما هو موضّح في مثال فلتر الأهداف التالي.

ملاحظة: لا ننصح باستخدام SEARCH_ACTION للبحث في التطبيق. بدلاً من ذلك، يمكنك تنفيذ إجراء GET_THING للاستفادة من الدعم المضمَّن في "مساعد Google" للبحث داخل التطبيق. لمزيد من المعلومات، يمكنك الاطّلاع على مستندات الإجراءات على التطبيقات في "مساعد Google".

الإجراء
"com.google.android.gms.actions.SEARCH_ACTION"
إتاحة طلبات البحث من "الإجراءات الصوتية من Google"
العناصر الإضافية
QUERY
سلسلة تحتوي على طلب البحث.

مثال على فلتر الأهداف:

<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.

الإجراء
ACTION_WEB_SEARCH
مخطط معرّف الموارد المنتظم (URI) للبيانات
لا شيء
نوع MIME
لا شيء
العناصر الإضافية
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);
    }
}

الإعدادات

لفتح شاشة في تطبيق "إعدادات النظام" عندما يطلب تطبيقك من المستخدم إجراء تغيير، استخدِم أحد إجراءات الغرض التالية:

الإجراء
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
بدون إشراف

مثال على النية:

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)، استخدِم أحد إجراءات الأغراض التالية وحدِّد تفاصيل الرسالة مثل رقم الهاتف والموضوع ونص الرسالة باستخدام المفاتيح الإضافية التالية.

الإجراء
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 عنصر يشير إلى الصور أو الفيديوهات لإرفاقها.

مثال على النية:

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 على الويب

الإجراءات الصوتية من Google

  • "فتح example.com"

لفتح صفحة ويب، استخدِم الإجراء ACTION_VIEW وحدِّد عنوان URL على الويب في بيانات الغرض.

الإجراء
ACTION_VIEW
مخطط معرّف الموارد المنتظم (URI) للبيانات
http:<URL>
https:<URL>
نوع MIME
"text/plain"
"text/html"
"application/xhtml+xml"
"application/vnd.wap.xhtml+xml"

مثال على النية:

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 لتنشيط أغراض معيّنة من خلال تنفيذ ما يلي:

  1. عليك إعداد جهاز Android من أجل التطوير أو استخدام جهاز افتراضي.
  2. ثبِّت إصدارًا من تطبيقك يعالج الأغراض التي تريد إتاحة الوصول إليها.
  3. تنشيط النية باستخدام السمة 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
    
  4. في حال تحديد فلاتر الأهداف المطلوبة، تعامل مع الغرض.

لمزيد من المعلومات، يُرجى الاطّلاع على مشكلة أوامر واجهة المستخدم.