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

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

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

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

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

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

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

الإجراءات الصوتية في 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
معرّف موارد 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 Voice

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

لإنشاء موقّت للعد التنازلي، استخدِم الإجراء ACTION_SET_TIMER وحدِّد تفاصيل الموقّت مثل المدة باستخدام الإضافات التالية.

ملاحظة: يتوفّر هذا الإجراء في الإصدار 4.4 من نظام التشغيل Android (المستوى 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 .

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

ملاحظة: يتوفّر هذا الإجراء في الإصدار 4.4 من نظام التشغيل Android (المستوى 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. حدِّد أيضًا موقع عنوان URL الذي تريد أن تحفظ فيه الكاميرا الصورة أو الفيديو، في EXTRA_OUTPUT extra.

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

عندما يعيد تطبيق الكاميرا توجيه التركيز إلى نشاطك بنجاح، أي عندما يتلقّى تطبيقك طلب إعادة الاتصال onActivityResult()، يمكنك الوصول إلى الصورة أو الفيديو على عنوان URL الذي حدّدته باستخدام القيمة 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 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث، يمكنك الاطّلاع على مثال intent التالي.

مثال على الغرض:

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()" على content: معرف موارد منتظم (URI) يشير إلى جهة الاتصال المحددة. يمنح الردّ تطبيقك أذونات مؤقتة لقراءة جهة الاتصال هذه باستخدام واجهة برمجة التطبيقات Provider of Contacts، حتى إذا كان تطبيقك لا يتضمّن الإذن 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 لجهة الاتصال باستخدام هذا الغرض، فلن بحاجة إلى READ_CONTACTS إذن بقراءة التفاصيل الأساسية لجهة الاتصال تلك، مثل الاسم المعروض ما إذا كانت جهة الاتصال مميزة بنجمة. ومع ذلك، إذا كنت تحاول قراءة بيانات أكثر تحديدًا حول جهة اتصال معينة، مثل كرقم هاتفه أو عنوان بريده الإلكتروني، ستحتاج إلى READ_CONTACTS إذن.

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

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

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

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

تحتوي النتيجة "Intent" التي تم إرسالها إلى معاودة الاتصال على "onActivityResult()" على content: هو معرّف موارد منتظم (URI) يشير إلى بيانات الاتصال المحدّدة. الرد يمنح أذونات مؤقتة للتطبيق لقراءة بيانات جهات الاتصال هذه حتى إذا لم يكن يتضمّن إذن 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 وحدِّد جهة الاتصال باستخدام عنوان URL content: بصفتها بيانات النية.

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

  • استخدِم معرّف الموارد المنتظم لجهة الاتصال الذي يعرضه الإجراء 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.

هناك طريقتان أساسيتان لاسترداد عنوان URL المؤدي إلى جهة الاتصال في البداية:

  • استخدِم معرّف الموارد المنتظم لجهة الاتصال الذي يعرضه الإجراء 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);
    }
}

لمعرفة مزيد من المعلومات عن كيفية تعديل جهة اتصال، يُرجى قراءة مقالة تعديل. جهات الاتصال باستخدام عناصر 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: . ومع ذلك، إذا كنت تريد حصر الملفات القابلة للاختيار بتلك التي يمكن الوصول إليها من مقدّم محتوى (عنوان URL‏ content:) والتي تتوفّر كبث ملفات باستخدام openFileDescriptor()، أضِف فئة CATEGORY_OPENABLE إلى طلبك.

في نظام التشغيل Android 4.3 (المستوى 18 من واجهة برمجة التطبيقات) والإصدارات الأحدث، يمكنك أيضًا السماح للمستخدم بتحديد ملفات متعددة عن طريق إضافة EXTRA_ALLOW_MULTIPLE للغرض، وتم ضبطه على 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، يمكنك بدلاً من ذلك طلب فتح ملف يديره تطبيق آخر باستخدام الإجراء ACTION_OPEN_DOCUMENT وتحديد نوع MIME. للسماح للمستخدم أيضًا بإنشاء مستند جديد يمكن لتطبيقك الكتابة فيه، استخدِم الإجراء ACTION_CREATE_DOCUMENT بدلاً من ذلك.

على سبيل المثال، بدلاً من من مستندات PDF الحالية، ACTION_CREATE_DOCUMENT يتيح intent للمستخدمين اختيار المكان الذي يريدون إنشاء مستند جديد فيه، مثل المحتوى داخل تطبيق آخر. يدير مساحة تخزين المستند. يتلقّى تطبيقك بعد ذلك موقع معرّف الموارد المنتظم (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 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 الكرة الأرضية بأكملها، مع وضعها في وسط lat و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 و حدِّد موقع معرّف الموارد المنتظم للملف في بيانات النية.

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

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

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

في هذا الإجراء، أدرِج السلسلة EXTRA_MEDIA_FOCUS extra التي تحدّد وضع البحث المقصود. على سبيل المثال، يمكن أن يحدّد وضع البحث ما إذا كان العميل يبحث عن اسم فنّان أو اسم أغنية.

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

الإجراءات الصوتية في Google Voice

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

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

يتطلب الإجراء 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
بدون

أرقام الهواتف الصالحة هي تلك المحدّدة في معيار IETF RFC 3966. تشمل الأمثلة الصالحة ما يلي:

  • 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 Voice
الإضافات
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/رسالة وسائط متعددة مع مرفق

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

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

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

متصفح الويب

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

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

الإجراءات الصوتية في Google Voice

  • "open example.com"

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

الإجراء
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 App Links:

اعتبارًا من الإصدار 12 من نظام التشغيل Android (المستوى 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. إذا حدّدت فلاتر الأهداف المطلوبة، فتعامل مع الغرض.

لمزيد من المعلومات، يُرجى مراجعة أوامر واجهة المستخدم: