כוונות נפוצות

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

• "take a picture"

כדי לפתוח אפליקציית מצלמה במצב תמונה סטילס, משתמשים בפעולה INTENT_ACTION_STILL_IMAGE_CAMERA.

פעולה

INTENT_ACTION_STILL_IMAGE_CAMERA

סכימת URI לנתונים

ללא

סוג MIME

ללא

Extras

ללא

דוגמה לכוונת רכישה:

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

ללא

Extras

ללא

דוגמה לכוונת רכישה:

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>

אפליקציית 'אנשי קשר'

אלה פעולות נפוצות באפליקציות לניהול אנשי קשר, כולל המידע הדרוש כדי ליצור מסנן כוונה (intent) כדי לפרסם את היכולת של האפליקציה לבצע כל פעולה.

בחירת איש קשר

כדי לאפשר למשתמש לבחור איש קשר ולתת לאפליקציה גישה לכל הפרטים שלו, צריך להשתמש בפעולה ACTION_PICK ולציין את סוג ה-MIME כ-Contacts.CONTENT_TYPE.

התוצאה Intent שמועברת להודעת החזרה (call back) onActivityResult() מכילה את ה-URI‏ content: שמצביע על איש הקשר שנבחר. התגובה מעניקה לאפליקציה הרשאות זמניות לקרוא את איש הקשר הזה באמצעות ה-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, כפי שמוצג בקטע הקודם. התוצאה מספקת גישה ישירה לנתונים הרצויים, בלי שתצטרכו לבצע שאילתה מורכבת יותר ל-Contacts Provider.

התוצאה Intent שמועברת להודעת החזרה (callback) של onActivityResult() מכילה את מזהה ה-URI‏ content: שמצביע על פרטי הקשר שנבחרו. התגובה מעניקה לאפליקציה הרשאות זמניות לקרוא את נתוני אנשי הקשר האלה, גם אם האפליקציה לא כוללת את ההרשאה READ_CONTACTS.

פעולה

ACTION_PICK

סכימת URI לנתונים

ללא

סוג MIME

CommonDataKinds.Phone.CONTENT_TYPE

בוחרים מאנשי הקשר עם מספר טלפון.

CommonDataKinds.Email.CONTENT_TYPE

בוחרים מאנשי הקשר שיש להם כתובת אימייל.

CommonDataKinds.StructuredPostal.CONTENT_TYPE

בוחרים מאנשי הקשר שיש להם כתובת.

או אחד מהערכים הרבים האחרים של CONTENT_TYPE בקטע ContactsContract.

דוגמה לכוונת רכישה:

const val REQUEST_SELECT_PHONE_NUMBER = 1

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

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

static final int REQUEST_SELECT_PHONE_NUMBER = 1;

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

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

הצגת איש קשר

כדי להציג את הפרטים של איש קשר ידוע, משתמשים בפעולה ACTION_VIEW ומציינים את איש הקשר באמצעות מזהה URI של content: כנתוני הכוונה.

יש שתי דרכים עיקריות לאחזר את ה-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 של איש הקשר.

Extras

אחד או יותר מהפרטים הנוספים שהוגדרו ב-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

Extras

אחד או יותר מהפריטים הנוספים שהוגדרו ב-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"

"*/*"

Extras

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>

אחסון קבצים

בהמשך מפורטות פעולות נפוצות באפליקציות לאחסון קבצים, כולל המידע הדרוש כדי ליצור מסנן כוונות (intent) כדי לפרסם את היכולת של האפליקציה לבצע כל פעולה.

אחזור של קובץ מסוג ספציפי

כדי לבקש מהמשתמש לבחור קובץ, כמו מסמך או תמונה, ולהחזיר הפניה לאפליקציה, משתמשים בפעולה ACTION_GET_CONTENT ומציינים את סוג ה-MIME הרצוי. ההפניה לקובץ שמוחזרת לאפליקציה היא זמנית במחזור החיים הנוכחי של הפעילות, כך שאם רוצים לגשת אליה מאוחר יותר, צריך לייבא עותק שאפשר יהיה לקרוא מאוחר יותר.

הכוונה הזו גם מאפשרת למשתמש ליצור קובץ חדש בתהליך. לדוגמה, במקום לבחור תמונה קיימת, המשתמש יכול לצלם תמונה חדשה עם המצלמה.

כוונת התוצאה שמועברת ל-method‏ onActivityResult() כוללת נתונים עם URI שמפנה לקובץ. ה-URI יכול להיות כל דבר, למשל URI מסוג http:, URI מסוג file: או URI מסוג content:. עם זאת, אם רוצים להגביל את הקבצים שאפשר לבחור רק לאלה שזמינים מספק תוכן (URI של content:) וזמינים כסטרימינג של קבצים באמצעות openFileDescriptor(), צריך להוסיף את הקטגוריה CATEGORY_OPENABLE לכוונה.

ב-Android מגרסה 4.3 ואילך (רמת API 18 ואילך), אפשר גם לאפשר למשתמש לבחור כמה קבצים על ידי הוספת EXTRA_ALLOW_MULTIPLE ל-intent, שמוגדרת כ-true. לאחר מכן תוכלו לגשת לכל אחד מהקבצים שנבחרו באובייקט ClipData שמוחזר על ידי getClipData().

פעולה

ACTION_GET_CONTENT

סכימת URI לנתונים

ללא

סוג MIME

סוג ה-MIME התואם לסוג הקובץ שהמשתמש צריך לבחור.

Extras

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 מאפשרת למשתמשים לבחור איפה הם רוצים ליצור מסמך חדש, למשל באפליקציה אחרת שמנהלת את האחסון של המסמך. לאחר מכן, האפליקציה מקבלת את מיקום ה-URI שבו היא יכולה לכתוב את המסמך החדש.

בעוד שהכוונה (intent) שמועברת לשיטה onActivityResult() מהפעולה ACTION_GET_CONTENT עשויה להחזיר URI מכל סוג, הכוונה (intent) של התוצאה מ-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 אחד על ידי הוספת מערך של סוגי MIME באמצעות התוסף EXTRA_MIME_TYPES. אם עושים זאת, צריך להגדיר את סוג ה-MIME הראשי ב-setType() כ-"*/*".

פעולה

ACTION_OPEN_DOCUMENT או
ACTION_CREATE_DOCUMENT

סכימת URI לנתונים

ללא

סוג MIME

סוג ה-MIME התואם לסוג הקובץ שהמשתמש צריך לבחור.

Extras

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>

במאמר פתיחת קבצים באמצעות framework של גישה לאחסון מוסבר איך לאפשר פתיחה של קבצים שמנוהלים על ידי האפליקציה שלכם מאפליקציות אחרות.

פעולות מקומיות

הזמנת מונית היא פעולה מקומית נפוצה. יוצרים מסנן כוונה כדי לפרסם את היכולת של האפליקציה לבצע את הפעולה הזו, לפי המידע שמפורט בקטע הבא.

הזמנת מונית

פעולות קוליות של Google

• "get me a taxi"
• "call me a car"

(Wear OS בלבד)

כדי להזמין מונית, משתמשים בפעולה ACTION_RESERVE_TAXI_RESERVATION.

הערה: אפליקציות חייבות לבקש מהמשתמש אישור לפני שהן מבצעות את הפעולה הזו.

פעולה

ACTION_RESERVE_TAXI_RESERVATION

Data URI

ללא

סוג MIME

ללא

Extras

ללא

דוגמה לכוונת רכישה:

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>

מפות

הצגת מיקום במפה היא פעולה נפוצה באפליקציות מפה. יוצרים מסנן כוונה כדי לפרסם את היכולת של האפליקציה לבצע את הפעולה הזו, לפי המידע שמפורט בקטע הבא.

הצגת מיקום במפה

כדי לפתוח מפה, משתמשים בפעולה ACTION_VIEW ומציינים את פרטי המיקום בנתוני הכוונה באמצעות אחת מהסכמות הבאות.

פעולה

ACTION_VIEW

סכימת URI לנתונים

geo:latitude,longitude

הצגת המפה לפי קו האורך וקו הרוחב שצוינו.

דוגמה: "geo:47.6,-122.3"

geo:latitude,longitude?z=zoom

הצגת המפה בקווי האורך והרוחב שצוינו ברמת זום מסוימת. ברמת זום של 1 מוצגת כל כדור הארץ, עם מרכז ב-lat,‏lng שצוינו. רמת הזום הגבוהה ביותר (הקרוב ביותר) היא 23.

דוגמה: "geo:47.6,-122.3?z=11"

geo:0,0?q=lat,lng(label)

הצגת המפה בקווי האורך והרוחב שצוינו עם תווית מחרוזת.

דוגמה: "geo:0,0?q=34.99,-106.61(Treasure)"

geo:0,0?q=my+street+address

הצגת המיקום של 'כתובת הרחוב שלי', שיכולה להיות כתובת ספציפית או שאילתה לגבי מיקום.

דוגמה: "geo:0,0?q=1600+Amphitheatre+Parkway%2C+CA"

הערה: כל המחרוזות שמועברות ב-URI של geo חייבות להיות מקודדות. לדוגמה, המחרוזת 1st & Pike, Seattle הופכת ל-1st%20%26%20Pike%2C%20Seattle. רווחים במחרוזת מקודדים באמצעות %20 או מוחלפים בסימן הפלוס (+).

סוג MIME

ללא

דוגמה לכוונת רכישה:

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

• "play michael jackson billie jean"

כדי להפעיל מוזיקה על סמך שאילתת חיפוש, משתמשים בכוונה INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH. אפליקציה עשויה להפעיל את הכוונה הזו בתגובה לפקודה הקולית של המשתמש להפעיל מוזיקה. האפליקציה המקבלת של הכוונה הזו מבצעת חיפוש במלאי שטחי הפרסום שלה כדי להתאים תוכן קיים לשאילתה הנתונה, ומתחילה להפעיל את התוכן הזה.

בכוונה הזו, צריך לכלול את המחרוזת הנוספת EXTRA_MEDIA_FOCUS, שמציינת את מצב החיפוש המיועד. לדוגמה, מצב החיפוש יכול לציין אם החיפוש הוא של שם אומן או של שם שיר.

פעולה

INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH

סכימת URI לנתונים

ללא

סוג MIME

ללא

Extras

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 ‏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

"*/*"

Extras

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

• "call 555-5555"
• "call bob"
• "call voicemail"

כדי לבצע שיחת טלפון ישירות, משתמשים בפעולה 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

במרכז החיוג של אפליקציית 'טלפון' יש יכולת טובה לתקן תבניות, כמו מספרי טלפון. לכן, הסכימה המתוארת לא נדרשת באופן מוחלט ב-method‏ 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);
    }
}

חיפוש

בהמשך מפורטות פעולות נפוצות באפליקציות חיפוש, כולל המידע הדרוש כדי ליצור מסנן כוונה (intent) כדי לפרסם את היכולת של האפליקציה לבצע כל פעולה.

חיפוש באמצעות אפליקציה ספציפית

פעולות קוליות של Google

• "search for cat videos on myvideoapp"

כדי לתמוך בחיפוש בהקשר של האפליקציה, צריך להצהיר על מסנן Intent באפליקציה עם הפעולה SEARCH_ACTION, כפי שמתואר בדוגמה הבאה של מסנן Intent.

הערה: לא מומלץ להשתמש ב-SEARCH_ACTION לחיפוש אפליקציות. במקום זאת, כדאי להטמיע את הפעולה GET_THING כדי להשתמש בתמיכה המובנית של Google Assistant בחיפוש בתוך האפליקציה. מידע נוסף זמין במסמכי העזרה בנושא פעולות באפליקציות ב-Google Assistant.

פעולה

"com.google.android.gms.actions.SEARCH_ACTION"

תמיכה בשאילתות חיפוש מ-Google Voice Actions.

Extras

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

ללא

Extras

SearchManager.QUERY

מחרוזת החיפוש.

דוגמה לכוונת רכישה:

Kotlin

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

Java

public void searchWeb(String query) {
    Intent intent = new Intent(Intent.ACTION_WEB_SEARCH);
    intent.putExtra(SearchManager.QUERY, query);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

הגדרות

כדי לפתוח מסך באפליקציית ההגדרות של המערכת כשהאפליקציה מחייבת את המשתמש לשנות משהו, צריך להשתמש באחת מפעולות הכוונה הבאות:

פעולה

ACTION_SETTINGS
ACTION_WIRELESS_SETTINGS
ACTION_AIRPLANE_MODE_SETTINGS
ACTION_WIFI_SETTINGS
ACTION_APN_SETTINGS
ACTION_BLUETOOTH_SETTINGS
ACTION_DATE_SETTINGS
ACTION_LOCALE_SETTINGS
ACTION_INPUT_METHOD_SETTINGS
ACTION_DISPLAY_SETTINGS
ACTION_SECURITY_SETTINGS
ACTION_LOCATION_SOURCE_SETTINGS
ACTION_INTERNAL_STORAGE_SETTINGS
ACTION_MEMORY_CARD_SETTINGS

במסמכי העזרה של Settings מפורטות מסכי הגדרות נוספים שזמינים .

סכימת URI לנתונים

ללא

סוג MIME

ללא

דוגמה לכוונת רכישה:

Kotlin

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

Java

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

העברת הודעות טקסט

כתיבת הודעה מסוג SMS או MMS עם קובץ מצורף היא פעולה נפוצה באפליקציות לשליחת הודעות טקסט. יוצרים מסנן כוונה כדי לפרסם את היכולת של האפליקציה לבצע את הפעולה הזו, לפי המידע שמפורט בקטע הבא.

כתיבת הודעת SMS/MMS עם קובץ מצורף

כדי לשלוח הודעת טקסט מסוג SMS או MMS, משתמשים באחת מפעולות הכוונה הבאות ומציינים את פרטי ההודעה, כמו מספר הטלפון, הנושא וגוף ההודעה, באמצעות המקשים הנוספים הבאים.

פעולה

ACTION_SENDTO או
ACTION_SEND או
ACTION_SEND_MULTIPLE

סכימת URI לנתונים

sms:<phone_number>

smsto:<phone_number>

mms:<phone_number>

mmsto:<phone_number>

כל התוכניות האלה מטופלות באותו אופן.

סוג MIME

"text/plain"

"image/*"

"video/*"

Extras

"subject"

מחרוזת לנושא ההודעה (בדרך כלל ל-MMS בלבד).

"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/MMS, עליכם להטמיע מסנני כוונה לכמה פעולות נוספות כדי שהאפליקציה תהיה זמינה כאפליקציית ברירת המחדל ל-SMS ב-Android 4.4 ואילך. מידע נוסף זמין במסמכי העזרה בנושא Telephony.

דפדפן אינטרנט

טעינת כתובת URL של אתר היא פעולה נפוצה באפליקציות של דפדפני אינטרנט. יוצרים מסנן כוונה כדי לפרסם את היכולת של האפליקציה לבצע את הפעולה הזו, לפי המידע שמפורט בקטע הבא.

טעינת כתובת URL של אתר

פעולות קוליות של Google

• "open example.com"

כדי לפתוח דף אינטרנט, משתמשים בפעולה ACTION_VIEW ומציינים את כתובת ה-URL של האתר בנתוני הכוונה.

פעולה

ACTION_VIEW

סכימת URI לנתונים

http:<URL>
https:<URL>

סוג MIME

"text/plain"

"text/html"

"application/xhtml+xml"

"application/vnd.wap.xhtml+xml"

דוגמה לכוונת רכישה:

Kotlin

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

Java

public void openWebPage(String url) {
    Uri webpage = Uri.parse(url);
    Intent intent = new Intent(Intent.ACTION_VIEW, webpage);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

דוגמה למסנן כוונה:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <!-- Include the host attribute if you want your app to respond
             only to URLs with your app's domain. -->
        <data android:scheme="http" android:host="www.example.com" />
        <category android:name="android.intent.category.DEFAULT" />
        <!-- The BROWSABLE category is required to get links from web pages. -->
        <category android:name="android.intent.category.BROWSABLE" />
    </intent-filter>
</activity>

טיפ: אם אפליקציית Android מספקת פונקציונליות דומה לאתר שלכם, כדאי לכלול מסנן Intent לכתובות URL שמפניות לאתר שלכם. לאחר מכן, אם המשתמשים התקינו את האפליקציה, קישורים מאימיילים או מדפי אינטרנט אחרים שמפנים לאתר שלכם ייפתחו באפליקציה ל-Android במקום בדף האינטרנט. מידע נוסף זמין במאמר טיפול בקישורים לאפליקציות ל-Android.

החל מ-Android 12 (רמת API 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. אם מגדירים את מסנני הכוונה הנדרשים, מטפלים בכוונה.

מידע נוסף זמין במאמר הרצת פקודות מעטפת.