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

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

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

لا ينطبق

الإضافات

لا شيء

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

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

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

لا ينطبق

الإضافات

لا شيء

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

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

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: الذي يشير إلى جهة الاتصال المحدّدة. يمنح الردّ تطبيقك أذونات مؤقتة لقراءة جهة الاتصال هذه باستخدام واجهة برمجة التطبيقات Provider of Contacts، حتى إذا كان تطبيقك لا يتضمّن الإذن READ_CONTACTS.

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

الإجراء

ACTION_PICK

مخطّط معرّف الموارد المنتظم (URI) للبيانات

لا ينطبق

نوع MIME

Contacts.CONTENT_TYPE

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

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

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) لجهة الاتصال، اقرأ استرداد تفاصيل جهة اتصال.

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

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

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

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

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

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

الإجراء

ACTION_PICK

مخطّط معرّف الموارد المنتظم (URI) للبيانات

لا ينطبق

نوع MIME

CommonDataKinds.Phone.CONTENT_TYPE

اختَر من جهات الاتصال التي تتضمّن رقم هاتف.

CommonDataKinds.Email.CONTENT_TYPE

الاختيار من جهات الاتصال التي تحتوي على عنوان بريد إلكتروني

CommonDataKinds.StructuredPostal.CONTENT_TYPE

اختَر من جهات الاتصال التي لها عنوان بريدي.

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

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

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

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: بصفتها بيانات النية.

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

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

الإجراء

ACTION_VIEW

مخطّط معرّف الموارد المنتظم (URI) للبيانات

content:<URI>

نوع MIME

ما مِن صورة فائزة: يتم استنتاج النوع من عنوان URL الخاص بجهة الاتصال.

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

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

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 لجهة الاتصال مبدئيًا:

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

الإجراء

ACTION_EDIT

مخطّط معرّف الموارد المنتظم (URI) للبيانات

content:<URI>

نوع MIME

يتم استنتاج النوع من عنوان URL الخاص بجهة الاتصال.

الإضافات

واحد أو أكثر من الإضافات المحدّدة في ContactsContract.Intents.Insert لكي تتمكّن من تعبئة حقول تفاصيل الاتصال

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

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)
    }
}

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.

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

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)
    }
}

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);
    }
}

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

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

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)
    }
}

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:" كما هو موضّح في المثال التالي:

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)
    }
}

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

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

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

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

في حين أنّ النية التي يتم إرسالها إلى onActivityResult() الطريقة من الإجراء ACTION_GET_CONTENT قد تؤدي إلى عرض معرّف موارد منتظم (URI) من أي نوع، فإنّ نية النتيجة من ACTION_OPEN_DOCUMENT وACTION_CREATE_DOCUMENT تحدّد دائمًا الملف الذي تم اختياره على أنّه معرّف موارد منتظم (URI) من النوع content: مصحوبًا بـ DocumentsProvider. يمكنك فتح الملف باستخدام openFileDescriptor() والاستعلام عن تفاصيله باستخدام أعمدة من DocumentsContract.Document.

يمنح معرّف الموارد المنتظم الذي تم إرجاعه تطبيقك إذن الوصول للقراءة إلى الملف على المدى الطويل، وقد يمنح أيضًا إذن الوصول للكتابة. ويكون الإجراء 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().

مثال على الرغبة في الحصول على صورة:

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

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

لا ينطبق

الإضافات

لا شيء

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

fun callCar() {
    val intent = Intent(ReserveIntents.ACTION_RESERVE_TAXI_RESERVATION)
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

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"

ملاحظة: يجب ترميز جميع السلاسل التي يتم تمريرها في عنوان URL الخاص بgeo. على سبيل المثال، تصبح السلسلة 1st & Pike, Seattle 1st%20%26%20Pike%2C%20Seattle. يتم ترميز المسافات في السلسلة باستخدام %20 أو استبدالها بعلامة الجمع (+).

نوع MIME

بدون

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

fun showMap(geoLocation: Uri) {
    val intent = Intent(Intent.ACTION_VIEW).apply {
        data = geoLocation
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

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"

أو أيّ موافقة أخرى يتطلّبها تطبيقك

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

fun playMedia(file: Uri) {
    val intent = Intent(Intent.ACTION_VIEW).apply {
        data = file
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

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 الإضافية التي تحدد وضع البحث المقصود. على سبيل المثال، يمكن أن يحدد وضع البحث ما إذا كان البحث عن اسم فنان أو اسم أغنية.

الإجراء

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

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

إذا أراد المستخدم الاستماع إلى موسيقى من فنان معيّن، قد ينشئ تطبيق البحث الطلب التالي:

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)
    }
}

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

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)
            }
        }
    }
}

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"
• "call bob"
• "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 أو رسالة وسائط متعددة 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>

ملاحظة: إذا كنت تُطوّر تطبيق مراسلة رسائل قصيرة أو رسائل وسائط متعددة، عليك تنفيذ فلاتر الأهداف لعدة إجراءات إضافية لكي يكون التطبيق متاحًا كأحد تطبيقات الرسائل القصيرة التلقائية على الإصدار 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.

اعتبارًا من الإصدار 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. إذا حدّدت فلاتر الأهداف المطلوبة، يمكنك معالجة الطلب.

لمزيد من المعلومات، يُرجى الاطّلاع على إصدار أوامر shell.