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

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

عند استرداد عنوان 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.

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

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. وتحديد جهة الاتصال التي تتضمن معرف موارد منتظم (URI) لـ content: كبيانات intent.

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

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

الإجراء

ACTION_VIEW

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

content:<URI>

نوع MIME

بدون. يتم استنتاج النوع من معرّف الموارد المنتظم (URI) لجهة الاتصال.

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

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

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

الإجراء

ACTION_EDIT

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

content:<URI>

نوع MIME

يتم استنتاج النوع من معرّف الموارد المنتظم (URI) لجهة الاتصال.

الإضافات

تم تحديد عنصر واحد أو أكثر من العناصر الإضافية في 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);
    }
}

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

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

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

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

ما مِن قيمة محدّدة

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

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 مع تحديد موقع معرف الموارد المنتظم (URI) للملف في بيانات intent.

الإجراء

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

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

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

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

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

<uses-permission android:name="android.permission.CALL_PHONE" />

الإجراء

• ACTION_DIAL: لفتح برنامج الاتصال أو تطبيق الهاتف.
• ACTION_CALL - يضع مكالمة هاتفية (يتطلب إذن CALL_PHONE)

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

• tel:<phone-number>
• voicemail:<phone-number>

نوع MIME

ما مِن قيمة محدّدة

أرقام الهاتف الصالحة هي تلك التي يتم تعريفها في معيار 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"

الإضافات

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 أو رسالة وسائط متعددة مع مرفق

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

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

متصفح الويب

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

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

إجراءات Google Voice

• فتح 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:

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

التحقّق من الأهداف باستخدام Android Debug Bridge

للتأكّد من أنّ تطبيقك يستجيب للأغراض التي تريد دعمها، يمكنك استخدام adb لإطلاق أهداف معيّنة من خلال تنفيذ ما يلي:

1. إعداد جهاز Android للتطوير أو استخدام جهاز افتراضي
2. ثبِّت إصدارًا من تطبيقك ينفّذ الأهداف التي تريد تعزيزها.
3. تنشيط النية بالشراء باستخدام adb:

   adb shell am start -a <ACTION> -t <MIME_TYPE> -d <DATA> \
     -e <EXTRA_NAME> <EXTRA_VALUE> -n <ACTIVITY>
   

   مثلاً:

   adb shell am start -a android.intent.action.DIAL \
     -d tel:555-5555 -n org.example.MyApp/.MyActivity
   

4. إذا حدّدت فلاتر الأهداف المطلوبة، فتعامل مع الغرض.

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