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

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

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

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

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

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

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

إجراءات Google Voice

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

منبّه

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

ضبط منبّه

إجراءات Google Voice

  • "تعيير منبّه على الساعة 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 intent، يجب أن يحصل تطبيقك على إذن SET_ALARM:

<uses-permission android:name="com.android.alarm.permission.SET_ALARM" />

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

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.SET_ALARM" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

إِنْشَاءْ مُوَقِّتْ

إجراءات Google Voice

  • "ضبط موقّت لمدة 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 intent، يجب أن يحصل تطبيقك على إذن SET_ALARM:

<uses-permission android:name="com.android.alarm.permission.SET_ALARM" />

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

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.SET_TIMER" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

إظهار جميع المنبهات

لعرض قائمة المنبّهات، استخدِم الإجراء ACTION_SHOW_ALARMS.

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

ملاحظة: هذا الإجراء متوفّر في الإصدار Android 4.4 (المستوى 19 لواجهة برمجة التطبيقات) والإصدارات الأحدث.

الإجراء
ACTION_SHOW_ALARMS
معرّف الموارد المنتظم (URI) للبيانات
لا شيء
نوع MIME
بدون

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

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.SHOW_ALARMS" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

التقويم

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

إضافة حدث في التقويم

لإضافة حدث جديد إلى تقويم المستخدم، استخدِم الإجراء ACTION_INSERT وحدِّد معرّف الموارد المنتظم (URI) للبيانات باستخدام Events.CONTENT_URI. ويمكنك بعد ذلك تحديد تفاصيل مختلفة للحدث باستخدام الميزات الإضافية التالية.

الإجراء
ACTION_INSERT
معرّف الموارد المنتظم (URI) للبيانات
Events.CONTENT_URI
نوع MIME
"vnd.android.cursor.dir/event"
العناصر الإضافية
EXTRA_EVENT_ALL_DAY
قيمة منطقية تحدّد ما إذا كان هذا الحدث سيستمر طوال اليوم.
EXTRA_EVENT_BEGIN_TIME
وقت بدء الحدث (بالمللي ثانية منذ البداية)
EXTRA_EVENT_END_TIME
وقت انتهاء الحدث (بالمللي ثانية منذ البداية)
TITLE
عنوان الحدث
DESCRIPTION
وصف الحدث
EVENT_LOCATION
موقع الفعالية.
EXTRA_EMAIL
قائمة بعناوين البريد الإلكتروني التي تُحدِّد المدعوين والمدعوّين مفصولة بفواصل.

يمكن تحديد العديد من تفاصيل الأحداث الأخرى باستخدام الثوابت المحدّدة في الفئة CalendarContract.EventsColumns.

مثال على نيّة الشراء:

Kotlin

fun addEvent(title: String, location: String, begin: Long, end: Long) {
    val intent = Intent(Intent.ACTION_INSERT).apply {
        data = Events.CONTENT_URI
        putExtra(Events.TITLE, title)
        putExtra(Events.EVENT_LOCATION, location)
        putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, begin)
        putExtra(CalendarContract.EXTRA_EVENT_END_TIME, end)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void addEvent(String title, String location, long begin, long end) {
    Intent intent = new Intent(Intent.ACTION_INSERT)
            .setData(Events.CONTENT_URI)
            .putExtra(Events.TITLE, title)
            .putExtra(Events.EVENT_LOCATION, location)
            .putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, begin)
            .putExtra(CalendarContract.EXTRA_EVENT_END_TIME, end);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

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

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.INSERT" />
        <data android:mimeType="vnd.android.cursor.dir/event" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

الكاميرا

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

التقاط صورة أو فيديو وإرجاعه

لفتح تطبيق كاميرا وتلقّي الصورة أو الفيديو الناتجَين، استخدِم الإجراء ACTION_IMAGE_CAPTURE أو ACTION_VIDEO_CAPTURE. حدِّد أيضًا موقع معرّف الموارد المنتظم (URI) الذي تريد من الكاميرا أن تحفظ فيه الصورة أو الفيديو في عنصر EXTRA_OUTPUT الإضافي.

الإجراء
ACTION_IMAGE_CAPTURE أو
ACTION_VIDEO_CAPTURE
مخطّط معرّف الموارد المنتظم (URI) للبيانات
لا شيء
نوع MIME
لا شيء
العناصر الإضافية
EXTRA_OUTPUT
موقع معرّف الموارد المنتظم (URI) الذي يحفظ فيه تطبيق الكاميرا ملف الصورة أو الفيديو (كعنصر Uri).

عندما يعيد تطبيق الكاميرا التركيز إلى نشاطك، بمعنى آخر، يتلقّى تطبيقك معاودة الاتصال بـ "onActivityResult()"، يمكنك الوصول إلى الصورة أو الفيديو من خلال معرّف الموارد المنتظم (URI) الذي حدّدته بالقيمة EXTRA_OUTPUT.

ملاحظة: عند استخدام ACTION_IMAGE_CAPTURE لالتقاط صورة، قد تعرض الكاميرا أيضًا نسخة أو صورة مصغّرة تم تصغير حجم الصورة في النتيجة Intent، وقد تم حفظها كـ Bitmap في حقل إضافي باسم "data".

مثال على نيّة الشراء:

Kotlin

const val REQUEST_IMAGE_CAPTURE = 1
val locationForPhotos: Uri = ...

fun capturePhoto(targetFilename: String) {
    val intent = Intent(MediaStore.ACTION_IMAGE_CAPTURE).apply {
        putExtra(MediaStore.EXTRA_OUTPUT, Uri.withAppendedPath(locationForPhotos, targetFilename))
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_CAPTURE)
    }
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    if (requestCode == REQUEST_IMAGE_CAPTURE && resultCode == Activity.RESULT_OK) {
        val thumbnail: Bitmap = data.getParcelableExtra("data")
        // Do other work with full size photo saved in locationForPhotos.
        ...
    }
}

Java

static final int REQUEST_IMAGE_CAPTURE = 1;
static final Uri locationForPhotos;

public void capturePhoto(String targetFilename) {
    Intent intent = new Intent(MediaStore.ACTION_IMAGE_CAPTURE);
    intent.putExtra(MediaStore.EXTRA_OUTPUT,
            Uri.withAppendedPath(locationForPhotos, targetFilename));
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_CAPTURE);
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_IMAGE_CAPTURE && resultCode == RESULT_OK) {
        Bitmap thumbnail = data.getParcelableExtra("data");
        // Do other work with full size photo saved in locationForPhotos.
        ...
    }
}

ولإجراء ذلك عند العمل على نظام التشغيل Android 12 (مستوى واجهة برمجة التطبيقات 31) أو الإصدارات الأحدث، يمكنك الرجوع إلى مثال الغرض التالي.

مثال على نيّة الشراء:

Kotlin

val REQUEST_IMAGE_CAPTURE = 1

private fun dispatchTakePictureIntent() {
    val takePictureIntent = Intent(MediaStore.ACTION_IMAGE_CAPTURE)
    try {
        startActivityForResult(takePictureIntent, REQUEST_IMAGE_CAPTURE)
    } catch (e: ActivityNotFoundException) {
        // Display error state to the user.
    }
}

Java

static final int REQUEST_IMAGE_CAPTURE = 1;

private void dispatchTakePictureIntent() {
    Intent takePictureIntent = new Intent(MediaStore.ACTION_IMAGE_CAPTURE);
    try {
        startActivityForResult(takePictureIntent, REQUEST_IMAGE_CAPTURE);
    } catch (ActivityNotFoundException e) {
        // Display error state to the user.
    }
}
</section></div>

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

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

<activity ...>
    <intent-filter>
        <action android:name="android.media.action.IMAGE_CAPTURE" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

عند التعامل مع هذا الهدف، يجب أن تتحقّق من نشاطك بحثًا عن زيادة EXTRA_OUTPUT في Intent الواردة، ثم احفظ الصورة أو الفيديو الذي تم التقاطه في الموقع الذي حدّدته تلك الإضافة الإضافية واتصل بـ setResult() مع Intent يتضمن صورة مصغّرة مضغوطة في صورة إضافية باسم "data".

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

إجراءات Google Voice

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

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

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

لفتح تطبيق كاميرا في وضع الفيديو، استخدِم إجراء INTENT_ACTION_VIDEO_CAMERA.

الإجراء
INTENT_ACTION_VIDEO_CAMERA
مخطّط معرّف الموارد المنتظم (URI) للبيانات
لا شيء
نوع MIME
لا شيء
العناصر الإضافية
لا شيء

مثال على نيّة الشراء:

Kotlin

fun capturePhoto() {
    val intent = Intent(MediaStore.INTENT_ACTION_VIDEO_CAMERA)
    if (intent.resolveActivity(packageManager) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_CAPTURE)
    }
}

Java

public void capturePhoto() {
    Intent intent = new Intent(MediaStore.INTENT_ACTION_VIDEO_CAMERA);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_CAPTURE);
    }
}

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

<activity ...>
    <intent-filter>
        <action android:name="android.media.action.VIDEO_CAMERA" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

تطبيق جهات الاتصال أو الأشخاص

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

اختيار جهة الاتصال

ولطلب من المستخدم اختيار جهة اتصال ومنح تطبيقك إذن الوصول إلى جميع معلومات الاتصال، استخدِم الإجراء ACTION_PICK وحدِّد نوع MIME على Contacts.CONTENT_TYPE.

تحتوي النتيجة Intent التي تم إرسالها إلى معاودة الاتصال على onActivityResult() على معرّف الموارد المنتظم (URI) content: الذي يشير إلى جهة الاتصال المحددة. ويمنح الردّ تطبيقك أذونات مؤقتة للاطّلاع على جهة الاتصال هذه باستخدام واجهة برمجة تطبيقات Contacts Provider (مقدِّم خدمة جهات الاتصال)، حتى وإن لم يكن تطبيقك يتضمّن إذن READ_CONTACTS.

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

الإجراء
ACTION_PICK
مخطّط معرّف الموارد المنتظم (URI) للبيانات
لا شيء
نوع MIME
Contacts.CONTENT_TYPE

مثال على نيّة الشراء:

Kotlin

const val REQUEST_SELECT_CONTACT = 1

fun selectContact() {
    val intent = Intent(Intent.ACTION_PICK).apply {
        type = ContactsContract.Contacts.CONTENT_TYPE
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivityForResult(intent, REQUEST_SELECT_CONTACT)
    }
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    if (requestCode == REQUEST_SELECT_CONTACT && resultCode == RESULT_OK) {
        val contactUri: Uri = data.data
        // Do something with the selected contact at contactUri.
        //...
    }
}

Java

static final int REQUEST_SELECT_CONTACT = 1;

public void selectContact() {
    Intent intent = new Intent(Intent.ACTION_PICK);
    intent.setType(ContactsContract.Contacts.CONTENT_TYPE);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_SELECT_CONTACT);
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_SELECT_CONTACT && resultCode == RESULT_OK) {
        Uri contactUri = data.getData();
        // Do something with the selected contact at contactUri.
        ...
    }
}

لمعرفة معلومات حول كيفية استرداد تفاصيل جهة الاتصال بعد الحصول على معرّف الموارد المنتظم (URI)، يُرجى الاطّلاع على استرداد التفاصيل لجهة اتصال.

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

اختيار بيانات جهات اتصال معيّنة

لتوجيه المستخدم إلى اختيار معلومة معيّنة من جهة اتصال، مثل رقم الهاتف أو عنوان البريد الإلكتروني أو نوع بيانات آخر، يمكنك استخدام الإجراء ACTION_PICK وتحديد نوع MIME لأحد أنواع المحتوى التالية، مثل CommonDataKinds.Phone.CONTENT_TYPE للحصول على رقم الهاتف الخاص بجهة الاتصال.

ملاحظة: في كثير من الحالات، يحتاج تطبيقك إلى إذن READ_CONTACTS لعرض معلومات محددة حول جهة اتصال معيّنة.

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

تحتوي النتيجة Intent التي تم إرسالها إلى معاودة الاتصال على onActivityResult() على معرّف الموارد المنتظم (URI) content: الذي يشير إلى بيانات جهة الاتصال المحددة. ويمنح هذا الردّ تطبيقك أذونات مؤقتة للاطّلاع على بيانات جهة الاتصال هذه حتى إذا لم يكن تطبيقك يتضمّن إذن READ_CONTACTS.

الإجراء
ACTION_PICK
مخطّط معرّف الموارد المنتظم (URI) للبيانات
لا شيء
نوع MIME
CommonDataKinds.Phone.CONTENT_TYPE
اختَر من جهات الاتصال التي لديها رقم هاتف.
CommonDataKinds.Email.CONTENT_TYPE
اختَر من جهات الاتصال التي لديها عنوان بريد إلكتروني.
CommonDataKinds.StructuredPostal.CONTENT_TYPE
اختَر من جهات الاتصال التي لديها عنوان بريدي.

أو قيمة من بين قيم CONTENT_TYPE العديدة الأخرى ضمن ContactsContract

مثال على نيّة الشراء:

Kotlin

const val REQUEST_SELECT_PHONE_NUMBER = 1

fun selectContact() {
    // Start an activity for the user to pick a phone number from contacts.
    val intent = Intent(Intent.ACTION_PICK).apply {
        type = CommonDataKinds.Phone.CONTENT_TYPE
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivityForResult(intent, REQUEST_SELECT_PHONE_NUMBER)
    }
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    if (requestCode == REQUEST_SELECT_PHONE_NUMBER && resultCode == Activity.RESULT_OK) {
        // Get the URI and query the content provider for the phone number.
        val contactUri: Uri = data.data
        val projection: Array<String> = arrayOf(CommonDataKinds.Phone.NUMBER)
        contentResolver.query(contactUri, projection, null, null, null).use { cursor ->
            // If the cursor returned is valid, get the phone number.
            if (cursor.moveToFirst()) {
                val numberIndex = cursor.getColumnIndex(CommonDataKinds.Phone.NUMBER)
                val number = cursor.getString(numberIndex)
                // Do something with the phone number.
                ...
            }
        }
    }
}

Java

static final int REQUEST_SELECT_PHONE_NUMBER = 1;

public void selectContact() {
    // Start an activity for the user to pick a phone number from contacts.
    Intent intent = new Intent(Intent.ACTION_PICK);
    intent.setType(CommonDataKinds.Phone.CONTENT_TYPE);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_SELECT_PHONE_NUMBER);
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_SELECT_PHONE_NUMBER && resultCode == RESULT_OK) {
        // Get the URI and query the content provider for the phone number.
        Uri contactUri = data.getData();
        String[] projection = new String[]{CommonDataKinds.Phone.NUMBER};
        Cursor cursor = getContentResolver().query(contactUri, projection,
                null, null, null);
        // If the cursor returned is valid, get the phone number.
        if (cursor != null && cursor.moveToFirst()) {
            int numberIndex = cursor.getColumnIndex(CommonDataKinds.Phone.NUMBER);
            String number = cursor.getString(numberIndex);
            // Do something with the phone number.
            //...
        }
    }
}

عرض جهة اتصال

لعرض تفاصيل جهة اتصال معروفة، استخدِم الإجراء ACTION_VIEW وحدِّد جهة الاتصال باستخدام معرّف الموارد المنتظم (URI) content: كبيانات الغرض.

هناك طريقتان أساسيتان لاسترداد عنوان URL لجهة الاتصال بشكل مبدئي:

  • استخدِم معرّف الموارد المنتظم (URI) لجهة الاتصال الذي يعرضه الإجراء ACTION_PICK الموضّح في القسم السابق. ولا يتطلب هذا الأسلوب أي أذونات للتطبيق.
  • يمكنك الوصول إلى قائمة جميع جهات الاتصال مباشرةً، على النحو الموضَّح في استرداد قائمة جهات الاتصال. يتطلّب هذا الأسلوب الحصول على إذن READ_CONTACTS.
الإجراء
ACTION_VIEW
مخطّط معرّف الموارد المنتظم (URI) للبيانات
content:<URI>
نوع MIME
لم يتم اتخاذ أي إجراءات. يتم استنتاج النوع من معرّف الموارد المنتظم (URI) لجهة الاتصال.

مثال على نيّة الشراء:

Kotlin

fun viewContact(contactUri: Uri) {
    val intent = Intent(Intent.ACTION_VIEW, contactUri)
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void viewContact(Uri contactUri) {
    Intent intent = new Intent(Intent.ACTION_VIEW, contactUri);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

تعديل جهة اتصال حالية

لتعديل جهة اتصال معروفة، استخدِم الإجراء ACTION_EDIT، وحدِّد جهة الاتصال مع معرف الموارد المنتظم (URI) content: لتكون بيانات الغرض، وأدرِج أي معلومات اتصال معروفة في البيانات الإضافية التي تحدّدها الثوابت في ContactsContract.Intents.Insert.

هناك طريقتان أساسيتان لاسترداد معرّف الموارد المنتظم (URI) لجهة الاتصال بشكل مبدئي:

  • استخدِم معرّف الموارد المنتظم (URI) لجهة الاتصال الذي يعرضه الإجراء ACTION_PICK الموضّح في القسم السابق. ولا يتطلب هذا الأسلوب أي أذونات للتطبيق.
  • يمكنك الوصول إلى قائمة جميع جهات الاتصال مباشرةً، على النحو الموضَّح في استرداد قائمة جهات الاتصال. يتطلّب هذا الأسلوب الحصول على إذن READ_CONTACTS.
الإجراء
ACTION_EDIT
مخطّط معرّف الموارد المنتظم (URI) للبيانات
content:<URI>
نوع MIME
يتم استنتاج النوع من معرّف الموارد المنتظم (URI) لجهة الاتصال.
العناصر الإضافية
تم تحديد عنصر واحد أو أكثر من العناصر الإضافية في ContactsContract.Intents.Insert حتى تتمكن من ملء حقول تفاصيل الاتصال.

مثال على نيّة الشراء:

Kotlin

fun editContact(contactUri: Uri, email: String) {
    val intent = Intent(Intent.ACTION_EDIT).apply {
        data = contactUri
        putExtra(ContactsContract.Intents.Insert.EMAIL, email)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void editContact(Uri contactUri, String email) {
    Intent intent = new Intent(Intent.ACTION_EDIT);
    intent.setData(contactUri);
    intent.putExtra(Intents.Insert.EMAIL, email);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

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

إدراج جهة اتصال

لإدراج جهة اتصال جديدة، استخدِم الإجراء ACTION_INSERT، وحدِّد Contacts.CONTENT_TYPE على أنّه نوع MIME، وضمِّن أي معلومات اتصال معروفة في البيانات الإضافية التي تحدّدها الثوابت في ContactsContract.Intents.Insert.

الإجراء
ACTION_INSERT
مخطّط معرّف الموارد المنتظم (URI) للبيانات
لا شيء
نوع MIME
Contacts.CONTENT_TYPE
العناصر الإضافية
تم تحديد واحد أو أكثر من العناصر الإضافية في ContactsContract.Intents.Insert.

مثال على نيّة الشراء:

Kotlin

fun insertContact(name: String, email: String) {
    val intent = Intent(Intent.ACTION_INSERT).apply {
        type = ContactsContract.Contacts.CONTENT_TYPE
        putExtra(ContactsContract.Intents.Insert.NAME, name)
        putExtra(ContactsContract.Intents.Insert.EMAIL, email)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void insertContact(String name, String email) {
    Intent intent = new Intent(Intent.ACTION_INSERT);
    intent.setType(Contacts.CONTENT_TYPE);
    intent.putExtra(Intents.Insert.NAME, name);
    intent.putExtra(Intents.Insert.EMAIL, email);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

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

عنوان البريد الإلكتروني

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

إنشاء رسالة إلكترونية تتضمّن مرفقات اختيارية

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

الإجراء
ACTION_SENDTO (لبدون مرفق) أو
ACTION_SEND (لمرفق واحد) أو
ACTION_SEND_MULTIPLE (لعدة مرفقات)
مخطّط معرّف الموارد المنتظم (URI) للبيانات
لا شيء
نوع MIME
"text/plain"
"*/*"
العناصر الإضافية
Intent.EXTRA_EMAIL
مصفوفة سلسلة لجميع عناوين البريد الإلكتروني للمستلمين "إلى".
Intent.EXTRA_CC
مصفوفة سلسلة لجميع عناوين البريد الإلكتروني للمستلمين "نسخة إلى".
Intent.EXTRA_BCC
مصفوفة سلسلة لجميع عناوين البريد الإلكتروني للمستلمين "نسخة مخفية الوجهة"
Intent.EXTRA_SUBJECT
سلسلة تتضمّن موضوع الرسالة الإلكترونية
Intent.EXTRA_TEXT
سلسلة تتضمّن نص الرسالة الإلكترونية
Intent.EXTRA_STREAM
رمز Uri يشير إلى المرفق. إذا كنت تستخدم الإجراء ACTION_SEND_MULTIPLE، سيتم استخدام الإجراء ArrayList الذي يحتوي على عدة كائنات Uri.

مثال على نيّة الشراء:

Kotlin

fun composeEmail(addresses: Array<String>, subject: String, attachment: Uri) {
    val intent = Intent(Intent.ACTION_SEND).apply {
        type = "*/*"
        putExtra(Intent.EXTRA_EMAIL, addresses)
        putExtra(Intent.EXTRA_SUBJECT, subject)
        putExtra(Intent.EXTRA_STREAM, attachment)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void composeEmail(String[] addresses, String subject, Uri attachment) {
    Intent intent = new Intent(Intent.ACTION_SEND);
    intent.setType("*/*");
    intent.putExtra(Intent.EXTRA_EMAIL, addresses);
    intent.putExtra(Intent.EXTRA_SUBJECT, subject);
    intent.putExtra(Intent.EXTRA_STREAM, attachment);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

إذا كنت تريد التأكّد من أنّه يتم التعامل مع الغرض من خلال تطبيق بريد إلكتروني فقط، وليس باستخدام تطبيق مراسلة نصية أو تطبيق اجتماعي، استخدِم الإجراء ACTION_SENDTO مع تضمين مخطط بيانات "mailto:" كما هو موضّح في المثال التالي:

Kotlin

fun composeEmail(addresses: Array<String>, subject: String) {
    val intent = Intent(Intent.ACTION_SENDTO).apply {
        data = Uri.parse("mailto:") // Only email apps handle this.
        putExtra(Intent.EXTRA_EMAIL, addresses)
        putExtra(Intent.EXTRA_SUBJECT, subject)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void composeEmail(String[] addresses, String subject) {
    Intent intent = new Intent(Intent.ACTION_SENDTO);
    intent.setData(Uri.parse("mailto:")); // Only email apps handle this.
    intent.putExtra(Intent.EXTRA_EMAIL, addresses);
    intent.putExtra(Intent.EXTRA_SUBJECT, subject);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

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

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <data android:type="*/*" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.SENDTO" />
        <data android:scheme="mailto" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

تخزين الملفات

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

استرداد نوع معين من الملفات

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

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

يتضمن الغرض من النتيجة الذي تم إرساله إلى طريقة onActivityResult() بيانات باستخدام معرّف موارد منتظم (URI) يشير إلى الملف. ويمكن أن يكون معرّف الموارد المنتظم (URI) أي شيء، مثل معرّف الموارد المنتظم http: أو معرّف الموارد المنتظم (URI) file: أو معرّف الموارد المنتظم (URI) content:. ومع ذلك، إذا أردت حصر الملفات القابلة للاختيار على الملفات التي يمكن الوصول إليها فقط من موفّر محتوى (معرّف الموارد المنتظم (URI) content:) والمتاحة كتدفق بيانات باستخدام openFileDescriptor()، أضِف فئة CATEGORY_OPENABLE إلى الغرض.

في نظام التشغيل Android 4.3 (مستوى واجهة برمجة التطبيقات 18) والإصدارات الأحدث، يمكنك أيضًا السماح للمستخدم باختيار ملفات متعددة عن طريق إضافة EXTRA_ALLOW_MULTIPLE إلى Intent، مع الضبط على true. يمكنك بعد ذلك الوصول إلى كل ملف من الملفات المحدّدة في كائن ClipData الذي يعرضه getClipData().

الإجراء
ACTION_GET_CONTENT
مخطّط معرّف الموارد المنتظم (URI) للبيانات
لا شيء
نوع MIME
نوع MIME المقابل لنوع الملف الذي يحتاج المستخدم إلى اختياره.
العناصر الإضافية
EXTRA_ALLOW_MULTIPLE
تشير هذه القيمة إلى ما إذا كان بإمكان المستخدم اختيار أكثر من ملف واحد في الوقت نفسه.
EXTRA_LOCAL_ONLY
تشير هذه السمة إلى قيمة منطقية توضّح ما إذا كان يجب أن يكون الملف الذي تم إرجاعه متاحًا مباشرةً من الجهاز، بدلاً من اشتراط تنزيله من خدمة عن بُعد.
Category (الفئة) (اختيارية)
CATEGORY_OPENABLE
لعرض الملفات "القابلة للفتح" فقط التي يمكن تمثيلها كتدفق ملف باستخدام openFileDescriptor().

مثال على نيّة الحصول على صورة:

Kotlin

const val REQUEST_IMAGE_GET = 1

fun selectImage() {
    val intent = Intent(Intent.ACTION_GET_CONTENT).apply {
        type = "image/*"
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_GET)
    }
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    if (requestCode == REQUEST_IMAGE_GET && resultCode == Activity.RESULT_OK) {
        val thumbnail: Bitmap = data.getParcelableExtra("data")
        val fullPhotoUri: Uri = data.data
        // Do work with photo saved at fullPhotoUri.
        ...
    }
}

Java

static final int REQUEST_IMAGE_GET = 1;

public void selectImage() {
    Intent intent = new Intent(Intent.ACTION_GET_CONTENT);
    intent.setType("image/*");
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_GET);
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_IMAGE_GET && resultCode == RESULT_OK) {
        Bitmap thumbnail = data.getParcelable("data");
        Uri fullPhotoUri = data.getData();
        // Do work with photo saved at fullPhotoUri.
        ...
    }
}

مثال على فلتر الأهداف لعرض صورة:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.GET_CONTENT" />
        <data android:type="image/*" />
        <category android:name="android.intent.category.DEFAULT" />
        <!-- The OPENABLE category declares that the returned file is accessible
             from a content provider that 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 إلى Intent، مع ضبطها على true. إذا اختار المستخدم عنصرًا واحدًا فقط، يمكنك استرداد العنصر من getData(). إذا اختار المستخدم أكثر من عنصر واحد، ستعرض السمة getData() قيمة فارغة، وعليك بدلاً من ذلك استرداد كل عنصر من عنصر ClipData الذي يعرضه getClipData().

ملاحظة: يجب أن يحدّد الغرض نوع MIME ويجب أن يتضمّن تعريف الفئة CATEGORY_OPENABLE. يمكنك تحديد أكثر من نوع MIME واحد إذا كان ذلك مناسبًا من خلال إضافة مصفوفة من أنواع MIME مع إضافة EXTRA_MIME_TYPES الإضافية. وفي حال إجراء ذلك، عليك ضبط نوع MIME الأساسي في setType() على "*/*".

الإجراء
ACTION_OPEN_DOCUMENT أو
ACTION_CREATE_DOCUMENT
مخطّط معرّف الموارد المنتظم (URI) للبيانات
لا شيء
نوع MIME
نوع MIME المقابل لنوع الملف الذي يحتاج المستخدم إلى اختياره.
العناصر الإضافية
EXTRA_MIME_TYPES
مصفوفة من أنواع MIME تتوافق مع أنواع الملفات التي يطلبها تطبيقك. عند استخدام هذا العنصر الإضافي، عليك ضبط نوع MIME الأساسي في setType() على "*/*".
EXTRA_ALLOW_MULTIPLE
تشير هذه القيمة إلى ما إذا كان بإمكان المستخدم اختيار أكثر من ملف واحد في الوقت نفسه.
EXTRA_TITLE
تُستخدم مع ACTION_CREATE_DOCUMENT لتحديد اسم ملف مبدئي.
EXTRA_LOCAL_ONLY
تشير هذه السمة إلى قيمة منطقية توضّح ما إذا كان يجب أن يكون الملف الذي تم إرجاعه متاحًا مباشرةً من الجهاز، بدلاً من اشتراط تنزيله من خدمة عن بُعد.
الفئة
CATEGORY_OPENABLE
لعرض الملفات "القابلة للفتح" فقط التي يمكن تمثيلها كتدفق ملف باستخدام openFileDescriptor().

مثال على نيّة الحصول على صورة:

Kotlin

const val REQUEST_IMAGE_OPEN = 1

fun selectImage2() {
    val intent = Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
        type = "image/*"
        addCategory(Intent.CATEGORY_OPENABLE)
    }
    // Only the system receives the ACTION_OPEN_DOCUMENT, so no need to test.
    startActivityForResult(intent, REQUEST_IMAGE_OPEN)
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    if (requestCode == REQUEST_IMAGE_OPEN && resultCode == Activity.RESULT_OK) {
        val fullPhotoUri: Uri = data.data
        // Do work with full size photo saved at fullPhotoUri.
        ...
    }
}

Java

static final int REQUEST_IMAGE_OPEN = 1;

public void selectImage() {
    Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
    intent.setType("image/*");
    intent.addCategory(Intent.CATEGORY_OPENABLE);
    // Only the system receives the ACTION_OPEN_DOCUMENT, so no need to test.
    startActivityForResult(intent, REQUEST_IMAGE_OPEN);
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_IMAGE_OPEN && resultCode == RESULT_OK) {
        Uri fullPhotoUri = data.getData();
        // Do work with full size photo saved at fullPhotoUri.
        ...
    }
}

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

لتوفير ملفات تطبيقك في واجهة المستخدم هذه والسماح للتطبيقات الأخرى بفتحها، عليك تنفيذ DocumentsProvider وتضمين فلتر أهداف للسمة PROVIDER_INTERFACE ("android.content.action.DOCUMENTS_PROVIDER")، كما هو موضّح في المثال التالي: 

<provider ...
    android:grantUriPermissions="true"
    android:exported="true"
    android:permission="android.permission.MANAGE_DOCUMENTS">
    <intent-filter>
        <action android:name="android.content.action.DOCUMENTS_PROVIDER" />
    </intent-filter>
</provider>

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

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

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

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

إجراءات Google Voice

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

(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) للملف في بيانات الغرض.

الإجراء
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 Voice

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

لتشغيل الموسيقى استنادًا إلى طلب بحث، استخدِم هدف 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 Voice

  • "الاتصال بـ 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 Voice

  • "البحث عن فيديوهات عن القطط على 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/رسالة وسائط متعددة MMS تتضمّن مرفقًا

لبدء رسالة قصيرة 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>

ملاحظة: إذا كنت تعمل على تطوير تطبيق لرسائل SMS/رسائل وسائط متعددة، ينبغي لك تنفيذ فلاتر الأهداف للعديد من الإجراءات الإضافية حتى تتوفر كتطبيق الرسائل القصيرة SMS الافتراضي في الإصدار 4.4 من نظام التشغيل Android والإصدارات الأحدث. لمزيد من المعلومات، يمكنك الاطّلاع على المستندات على "Telephony".

متصفح الويب

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

تحميل عنوان URL على الويب

إجراءات Google Voice

  • "فتح 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. وفي حال تحديد فلاتر الأهداف المطلوبة، يمكنك التعامل مع الغرض.

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