هدف‌های مشترک

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

• «عکس بگیر»

برای باز کردن برنامه دوربین در حالت تصویر ثابت، از کنش 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

• «record a video» (ویدیو ضبط کن)

برای باز کردن برنامه دوربین در حالت ویدیو، از کنش 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 است که به مخاطب انتخاب‌شده اشاره می‌کند. پاسخ به برنامه شما اجازه موقت می‌دهد تا بااستفاده از میانای برنامه‌سازی کاربردی ارائه‌کننده مخاطبین آن مخاطب را بخواند، حتی اگر برنامه شما شامل اجازه 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 مخاطب، بازیابی جزئیات مخاطب را بخوانید.

وقتی شناسه منبع یکسان مخاطب را بااستفاده از این هدف بازیابی می‌کنید، معمولاً برای خواندن جزئیات اصلی آن مخاطب، مثل نام نمایشی و اینکه مخاطب ستاره‌دار است یا نه، به اجازه 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: به‌عنوان داده هدف مشخص کنید.

دو روش اصلی برای بازیابی اولیه شناسه منبع یکسان مخاطب وجود دارد:

• از 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 مخاطب که توسط کنش ACTION_PICK برگردانده شده است و در بخش قبلی نشان داده شده است استفاده کنید. این رویکرد به هیچ اجازه برنامه‌ای نیاز ندارد.
• همان‌طور که در بازیابی فهرست مخاطبین شرح داده شده است، مستقیماً به فهرست همه مخاطبین دسترسی پیدا کنید. این رویکرد به اجازه READ_CONTACTS نیاز دارد.

کنش

ACTION_EDIT

طرح‌واره URI داده

content:<URI>

نوع MIME

نوع از شناسه منبع یکسان مخاطب استنباط می‌شود.

موارد اضافی

یک یا چند مورد از موارد اضافی تعریف‌شده در 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);
    }
}

برای اطلاعات بیشتر درباره نحوه درج مخاطب، اصلاح مخاطبین بااستفاده از هدف‌ها را بخوانید.

ایمیل

نوشتن ایمیل با پیوست‌های اختیاری کنشی رایج برای برنامه‌های ایمیل است. بااستفاده از اطلاعات بخش زیر، فیلتر قصدی ایجاد کنید تا توانایی برنامه‌تان را برای انجام این کنش تبلیغ کنید.

ایمیلی با پیوست‌های اختیاری بنویسید

برای نوشتن ایمیل، بسته به اینکه می‌خواهید پیوست اضافه کنید یا نه، از یکی از کنش‌های زیر استفاده کنید، و جزئیات ایمیل مانند گیرنده و موضوع را بااستفاده از کلیدهای اضافی فهرست‌شده اضافه کنید.

کنش

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 است که به فایل اشاره می‌کند. شناسه منبع یکسان می‌تواند هر چیزی باشد، مثلاً شناسه منبع یکسان http:، شناسه منبع یکسان file:، یا شناسه منبع یکسان content:. بااین‌حال، اگر می‌خواهید فایل‌های قابل‌انتخاب را فقط به فایل‌هایی محدود کنید که از ارائه‌دهنده محتوا (content: URI) قابل‌دسترسی هستند و به‌عنوان جاری‌سازی فایل با openFileDescriptor() دردسترس هستند، دسته CATEGORY_OPENABLE را به قصدتان اضافه کنید.

در Android 4.3 (سطح میانای برنامه‌سازی کاربردی ۱۸) و بالاتر، می‌توانید با افزودن 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 نسخه ۴.۴ یا بالاتر، می‌توانید بااستفاده از کنش ACTION_OPEN_DOCUMENT و مشخص کردن نوع MIME، درخواست کنید فایل مدیریت‌شده توسط برنامه دیگری باز شود. برای اینکه به کاربر اجازه دهید سند جدیدی نیز ایجاد کند که برنامه‌تان بتواند در آن بنویسد، به‌جای‌آن از کنش ACTION_CREATE_DOCUMENT استفاده کنید.

برای مثال، به‌جای انتخاب از بین اسناد PDF موجود، هدف ACTION_CREATE_DOCUMENT به کاربران اجازه می‌دهد جایی را که می‌خواهند سند جدید ایجاد شود انتخاب کنند، مثلاً در برنامه دیگری که فضای ذخیره‌سازی سند را مدیریت می‌کند. سپس برنامه‌تان مکان URI را که می‌تواند سند جدید را در آن بنویسد دریافت می‌کند.

درحالی‌که هدف ارائه‌شده به روش onActivityResult() شما از کنش ACTION_GET_CONTENT ممکن است URI از هر نوعی را برگرداند، هدف نتیجه از ACTION_OPEN_DOCUMENT و ACTION_CREATE_DOCUMENT همیشه فایل انتخاب‌شده را به‌عنوان URI content: که توسط DocumentsProvider پشتیبانی می‌شود مشخص می‌کند. می‌توانید فایل را با openFileDescriptor() باز کنید و جزئیات آن را بااستفاده از ستون‌های DocumentsContract.Document پُرسمان کنید.

URI برگردانده‌شده به برنامه شما دسترسی خواندن طولانی‌مدت به فایل را اعطا می‌کند، احتمالاً با دسترسی نوشتن. کنش ACTION_OPEN_DOCUMENT به‌ویژه زمانی مفید است که می‌خواهید فایل موجودی را بدون ایجاد کپی در برنامه‌تان بخوانید یا زمانی که می‌خواهید فایلی را در محل باز و ویرایش کنید.

همچنین می‌توانید با افزودن EXTRA_ALLOW_MULTIPLE به هدف، که روی true تنظیم شده است، به کاربر اجازه دهید چندین فایل را انتخاب کند. اگر کاربر فقط یک مورد را انتخاب کند، می‌توانید آن مورد را از getData() بازیابی کنید. اگر کاربر بیش‌از یک مورد را انتخاب کند، getData() مقدار null را برمی‌گرداند و باید به‌جای آن هر مورد را از شیء ClipData که توسط getClipData() برگردانده شده است بازیابی کنید.

توجه: قصد شما باید نوع MIME را مشخص کند و باید دسته CATEGORY_OPENABLE را اعلام کند. درصورت لزوم، می‌توانید با افزودن آرایه‌ای از انواع MIME با EXTRA_MIME_TYPES اضافی، بیش از یک نوع MIME را مشخص کنید—اگر این کار را انجام دهید، باید نوع 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

• «get me a taxi» (برایم تاکسی بگیر)
• «call me a car» (برایم ماشین بگیر)

(فقط 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

نقشه را در طول و عرض جغرافیایی داده‌شده در سطح بزرگ‌نمایی خاصی نشان می‌دهد. سطح بزرگ‌نمایی ۱ کل زمین را با مرکزیت عرض جغرافیایی،طول جغرافیایی داده‌شده نشان می‌دهد. بالاترین (نزدیک‌ترین) سطح بزرگ‌نمایی ۲۳ است.

مثال: "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"

توجه: همه رشته‌های ارسال‌شده در geo URI باید کدبندی شوند. برای مثال، رشته 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 فایل را در داده‌های هدف مشخص کنید.

کنش

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

• «بیلی جین مایکل جکسون را پخش کن»

برای پخش موسیقی براساس پرسمان جستجو، از هدف 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

رشته‌ای که نوشتار یادداشت را نشان می‌دهد.

قصد نمونه:

کاتلین

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

جاوا

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

• «با ۵۵۵-۵۵۵۵ تماس بگیر»
• «با باب تماس بگیر»
• «با پست صوتی تماس بگیر»

برای برقراری تماس تلفنی مستقیم، از کنش 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() استفاده کنید.

قصد نمونه:

کاتلین

fun dialPhoneNumber(phoneNumber: String) {
    val intent = Intent(Intent.ACTION_DIAL).apply {
        data = Uri.parse("tel:$phoneNumber")
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

جاوا

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

• «search for cat videos on 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

رشته جستجو.

قصد نمونه:

کاتلین

fun searchWeb(query: String) {
    val intent = Intent(Intent.ACTION_WEB_SEARCH).apply {
        putExtra(SearchManager.QUERY, query)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

جاوا

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

هیچ‌کدام

قصد نمونه:

کاتلین

fun openWifiSettings() {
    val intent = Intent(Settings.ACTION_WIFI_SETTINGS)
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

جاوا

public void openWifiSettings() {
    Intent intent = new Intent(Settings.ACTION_WIFI_SETTINGS);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

پیامک زدن

نوشتن پیامک/فراپیام با پیوست، کنشی رایج برای برنامه‌های پیام‌رسانی نوشتاری است. بااستفاده از اطلاعات بخش زیر، فیلتر قصدی ایجاد کنید تا توانایی برنامه‌تان را برای انجام این کنش تبلیغ کنید.

نوشتن پیامک/فراپیام با پیوست

برای شروع پیامک یا فراپیام، از یکی از کنش‌های هدف زیر استفاده کنید و جزئیات پیام مانند شماره تلفن، موضوع، و متن پیام را بااستفاده از کلیدهای اضافی زیر مشخص کنید.

کنش

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 است که به تصاویر یا ویدیوها برای پیوست کردن اشاره می‌کند.

قصد نمونه:

کاتلین

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

جاوا

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:" را همان‌طور که در مثال زیر نشان داده شده است، اضافه کنید:

کاتلین

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

جاوا

public void composeMmsMessage(String message, Uri attachment) {
    Intent intent = new Intent(Intent.ACTION_SEND);
    intent.setData(Uri.parse("smsto:"));  // Only SMS apps respond to this.
    intent.putExtra("sms_body", message);
    intent.putExtra(Intent.EXTRA_STREAM, attachment);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

نمونه فیلتر قصد:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <data android:type="text/plain" />
        <data android:type="image/*" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

توجه: اگر درحال توسعه برنامه پیام‌رسانی پیامک/فراپیام هستید، باید فیلترهای قصد را برای چندین کنش اضافی پیاده‌سازی کنید تا به‌عنوان برنامه پیش‌فرض پیامک در Android نسخه ۴.۴ و بالاتر دردسترس باشد. برای اطلاعات بیشتر، به مستندات در Telephony مراجعه کنید.

مرورگر وب

بار کردن نشانی وب کنشی رایج برای برنامه‌های مرورگر وب است. بااستفاده از اطلاعات بخش زیر، فیلتر قصدی ایجاد کنید تا توانایی برنامه‌تان را برای انجام این کنش تبلیغ کنید.

بار کردن نشانی وب

کنش‌های گفتاری Google

• «open example.com» (example.com را باز کن)

برای باز کردن صفحه وب، از کنش ACTION_VIEW استفاده کنید و نشانی وب را در داده‌های هدف مشخص کنید.

کنش

ACTION_VIEW

طرح‌واره URI داده

http:<URL>
https:<URL>

نوع MIME

"text/plain"

"text/html"

"application/xhtml+xml"

"application/vnd.wap.xhtml+xml"

قصد نمونه:

کاتلین

fun openWebPage(url: String) {
    val webpage: Uri = Uri.parse(url)
    val intent = Intent(Intent.ACTION_VIEW, webpage)
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

جاوا

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 شما عملکردی مشابه با وب‌سایتتان ارائه می‌دهد، فیلتر قصدی برای نشانی‌های وبی که به وب‌سایتتان اشاره می‌کنند اضافه کنید. سپس، اگر کاربران برنامه‌تان را نصب کرده باشند، پیوندهای موجود در ایمیل‌ها یا دیگر صفحه‌های وب که به وب‌سایت شما اشاره می‌کنند به‌جای صفحه وب شما، برنامه Android شما را باز می‌کنند. در مدیریت پیوندهای برنامه Android بیشتر بدانید.

از Android نسخه ۱۲ (سطح میانای برنامه‌سازی کاربردی ۳۱)، هدف وب عمومی فقط درصورتی به فعالیتی در برنامه شما تبدیل می‌شود که برنامه شما برای دامنه خاص موجود در آن هدف وب تأیید شده باشد. اگر برنامه شما برای دامنه تأیید نشده باشد، قصد وب به‌جای آن به برنامه مرورگر پیش‌فرض کاربر حل می‌شود.

درستی‌سنجی کردن هدف‌ها با 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. اگر فیلترهای قصد لازم را تعریف می‌کنید، قصد را مدیریت کنید.

برای اطلاعات بیشتر، به صدور فرمان‌های پوسته مراجعه کنید.