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

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>

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

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

<activity ...>
    <intent-filter>
        <action android:name="android.media.action.IMAGE_CAPTURE" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

כשמטפלים ב-intent הזה, הפעילות צריכה לבדוק את התוסף EXTRA_OUTPUT ב-intent הנכנס Intent, ואז לשמור את התמונה או הסרטון שצולמו במיקום שצוין בתוסף הזה, ולהתקשר אל setResult() עם Intent שכולל תמונה ממוזערת דחוסה בתוסף בשם "data".

הפעלת אפליקציית מצלמה במצב תמונת סטילס

פעולות קוליות ב-Google Voice

• ‫"take a picture" (צלם תמונה)

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

פעולה

INTENT_ACTION_STILL_IMAGE_CAMERA

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

ללא

סוג MIME

ללא

תוספות

ללא

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

private fun dispatchTakePictureIntent() {
    val takePictureIntent = Intent(MediaStore.ACTION_IMAGE_CAPTURE)
    try {
        startActivityForResult(takePictureIntent, REQUEST_IMAGE_CAPTURE)
    } catch (e: ActivityNotFoundException) {
        // Display error state to the user.
    }
}

public void capturePhoto(String targetFilename) {
    Intent intent = new Intent(MediaStore.ACTION_IMAGE_CAPTURE);
    intent.putExtra(MediaStore.EXTRA_OUTPUT,
            Uri.withAppendedPath(locationForPhotos, targetFilename));
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_CAPTURE);
    }
}

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

<activity ...>
    <intent-filter>
        <action android:name="android.media.action.STILL_IMAGE_CAMERA" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

הפעלת אפליקציית מצלמה במצב וידאו

פעולות קוליות ב-Google Voice

• ‫"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() מכילה את כתובת ה-URI‏ content: שמפנה לאיש הקשר שנבחר. התגובה מעניקה לאפליקציה הרשאות זמניות לקרוא את איש הקשר הזה באמצעות Contacts Provider API, גם אם האפליקציה לא כוללת את ההרשאה READ_CONTACTS.

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

פעולה

ACTION_PICK

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

ללא

סוג MIME

Contacts.CONTENT_TYPE

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

const val REQUEST_SELECT_CONTACT = 1

fun selectContact() {
    val intent = Intent(Intent.ACTION_PICK).apply {
        type = ContactsContract.Contacts.CONTENT_TYPE
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivityForResult(intent, REQUEST_SELECT_CONTACT)
    }
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    if (requestCode == REQUEST_SELECT_CONTACT && resultCode == RESULT_OK) {
        val contactUri: Uri = data.data
        // Do something with the selected contact at contactUri.
        //...
    }
}

static final int REQUEST_SELECT_CONTACT = 1;

public void selectContact() {
    Intent intent = new Intent(Intent.ACTION_PICK);
    intent.setType(ContactsContract.Contacts.CONTENT_TYPE);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_SELECT_CONTACT);
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_SELECT_CONTACT && resultCode == RESULT_OK) {
        Uri contactUri = data.getData();
        // Do something with the selected contact at contactUri.
        ...
    }
}

כדי לקבל מידע על אחזור פרטים ליצירת קשר אחרי שיש לכם את ה-URI של איש הקשר, אפשר לקרוא את המאמר אחזור פרטים של איש קשר.

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

בחירת נתונים ספציפיים ליצירת קשר

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

הערה: במקרים רבים, האפליקציה צריכה את ההרשאה READ_CONTACTS כדי להציג מידע ספציפי על איש קשר מסוים.

אם אתם צריכים לאחזר רק סוג אחד של נתונים מאנשי קשר, השיטה הזו עם המחלקות CONTENT_TYPE from ContactsContract.CommonDataKinds יעילה יותר משימוש ב-Contacts.CONTENT_TYPE, כמו שמוצג בקטע הקודם. התוצאה מספקת לכם גישה ישירה לנתונים הרצויים בלי שתצטרכו להריץ שאילתה מורכבת יותר אל ספק אנשי הקשר.

התוצאה Intent שמועברת לקריאה החוזרת 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 של איש הקשר.

תוספות

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

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

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

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

פעולה

ACTION_GET_CONTENT

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

ללא

סוג MIME

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

תוספות

EXTRA_ALLOW_MULTIPLE

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

EXTRA_LOCAL_ONLY

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

קטגוריה (אופציונלי)

CATEGORY_OPENABLE

‫

כדי להחזיר רק קבצים שאפשר לפתוח ושניתן לייצג כזרם קבצים עם openFileDescriptor().

דוגמה לכוונת משתמש לקבל תמונה:

const val REQUEST_IMAGE_GET = 1

fun selectImage() {
    val intent = Intent(Intent.ACTION_GET_CONTENT).apply {
        type = "image/*"
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_GET)
    }
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    if (requestCode == REQUEST_IMAGE_GET && resultCode == Activity.RESULT_OK) {
        val thumbnail: Bitmap = data.getParcelableExtra("data")
        val fullPhotoUri: Uri = data.data
        // Do work with photo saved at fullPhotoUri.
        ...
    }
}

static final int REQUEST_IMAGE_GET = 1;

public void selectImage() {
    Intent intent = new Intent(Intent.ACTION_GET_CONTENT);
    intent.setType("image/*");
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_GET);
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_IMAGE_GET && resultCode == RESULT_OK) {
        Bitmap thumbnail = data.getParcelable("data");
        Uri fullPhotoUri = data.getData();
        // Do work with photo saved at fullPhotoUri.
        ...
    }
}

דוגמה למסנן כוונות להחזרת תמונה:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.GET_CONTENT" />
        <data android:type="image/*" />
        <category android:name="android.intent.category.DEFAULT" />
        <!-- The OPENABLE category declares that the returned file is accessible
             from a content provider that supports OpenableColumns
             and ContentResolver.openFileDescriptor(). -->
        <category android:name="android.intent.category.OPENABLE" />
    </intent-filter>
</activity>

פתיחה של סוג מסוים של קובץ

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

לדוגמה, במקום לבחור מתוך מסמכי PDF קיימים, הכוונה ACTION_CREATE_DOCUMENT מאפשרת למשתמשים לבחור איפה הם רוצים ליצור מסמך חדש, למשל באפליקציה אחרת שמנהלת את האחסון של המסמך. האפליקציה מקבלת את מיקום ה-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 ל-Intent, שמוגדר ל-true. אם המשתמש בוחר רק פריט אחד, אפשר לאחזר את הפריט מ-getData(). אם המשתמש בוחר יותר מפריט אחד, הפונקציה getData() מחזירה null, ובמקום זאת צריך לאחזר כל פריט מאובייקט ClipData שמוחזר על ידי getClipData().

הערה: בכוונת השימוש חובה לציין סוג MIME וחובה להצהיר על הקטגוריה CATEGORY_OPENABLE. אם צריך, אפשר לציין יותר מסוג MIME אחד על ידי הוספת מערך של סוגי MIME עם EXTRA_MIME_TYPES extra. אם עושים זאת, צריך להגדיר את סוג ה-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 ולכלול מסנן Intent עבור 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 Voice

• ‫"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>

מפות

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

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

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

פעולה

ACTION_VIEW

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

geo:latitude,longitude

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

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

geo:latitude,longitude?z=zoom

‫

Show the map at the given longitude and latitude at a certain zoom level. רמת זום של 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 Voice

• ‫"play michael jackson billie jean" ‏(הפעלת השיר Billie Jean של מייקל ג'קסון)

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

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

פעולה

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 (חובה): מחרוזת שמכילה שילוב כלשהו של האומן או הז'אנר. התוספת הזו תמיד מסופקת לצורך תאימות לאחור. אפליקציות קיימות שלא תומכות במצבי חיפוש יכולות לעבד את הכוונה הזו כחיפוש לא מובנה.

‫Album - 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 extra בנתונים הנכנסים Intent כדי לקבוע את מצב החיפוש. אחרי שהפעילות מזהה את מצב החיפוש, היא קוראת את הערכים של התוספים הנוספים עבור מצב החיפוש הספציפי הזה. בעזרת המידע הזה, האפליקציה יכולה לבצע את החיפוש במלאי שלה כדי להפעיל את התוכן שתואם לשאילתת החיפוש. הדוגמה הבאה ממחישה את זה.

override fun onCreate(savedInstanceState: Bundle?) {
    ...
    if (intent.action.compareTo(MediaStore.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH) == 0) {

        val mediaFocus: String? = intent.getStringExtra(MediaStore.EXTRA_MEDIA_FOCUS)
        val query: String? = intent.getStringExtra(SearchManager.QUERY)

        // Some of these extras might not be available depending on the search mode.
        val album: String? = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ALBUM)
        val artist: String? = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ARTIST)
        val genre: String? = intent.getStringExtra("android.intent.extra.genre")
        val playlist: String? = intent.getStringExtra("android.intent.extra.playlist")
        val title: String? = intent.getStringExtra(MediaStore.EXTRA_MEDIA_TITLE)

        // Determine the search mode and use the corresponding extras.
        when {
            mediaFocus == null -> {
                // 'Unstructured' search mode (backward compatible)
                playUnstructuredSearch(query)
            }
            mediaFocus.compareTo("vnd.android.cursor.item/*") == 0 -> {
                if (query?.isNotEmpty() == true) {
                    // 'Unstructured' search mode.
                    playUnstructuredSearch(query)
                } else {
                    // 'Any' search mode.
                    playResumeLastPlaylist()
                }
            }
            mediaFocus.compareTo(MediaStore.Audio.Genres.ENTRY_CONTENT_TYPE) == 0 -> {
                // 'Genre' search mode.
                playGenre(genre)
            }
            mediaFocus.compareTo(MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE) == 0 -> {
                // 'Artist' search mode.
                playArtist(artist, genre)
            }
            mediaFocus.compareTo(MediaStore.Audio.Albums.ENTRY_CONTENT_TYPE) == 0 -> {
                // 'Album' search mode.
                playAlbum(album, artist)
            }
            mediaFocus.compareTo("vnd.android.cursor.item/audio") == 0 -> {
                // 'Song' search mode.
                playSong(album, artist, genre, title)
            }
            mediaFocus.compareTo(MediaStore.Audio.Playlists.ENTRY_CONTENT_TYPE) == 0 -> {
                // 'Playlist' search mode.
                playPlaylist(album, artist, genre, playlist, title)
            }
        }
    }
}

protected void onCreate(Bundle savedInstanceState) {
    //...
    Intent intent = this.getIntent();
    if (intent.getAction().compareTo(MediaStore.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH) == 0) {

        String mediaFocus = intent.getStringExtra(MediaStore.EXTRA_MEDIA_FOCUS);
        String query = intent.getStringExtra(SearchManager.QUERY);

        // Some of these extras might not be available depending on the search mode.
        String album = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ALBUM);
        String artist = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ARTIST);
        String genre = intent.getStringExtra("android.intent.extra.genre");
        String playlist = intent.getStringExtra("android.intent.extra.playlist");
        String title = intent.getStringExtra(MediaStore.EXTRA_MEDIA_TITLE);

        // Determine the search mode and use the corresponding extras.
        if (mediaFocus == null) {
            // 'Unstructured' search mode (backward compatible).
            playUnstructuredSearch(query);

        } else if (mediaFocus.compareTo("vnd.android.cursor.item/*") == 0) {
            if (query.isEmpty()) {
                // 'Any' search mode.
                playResumeLastPlaylist();
            } else {
                // 'Unstructured' search mode.
                playUnstructuredSearch(query);
            }

        } else if (mediaFocus.compareTo(MediaStore.Audio.Genres.ENTRY_CONTENT_TYPE) == 0) {
            // 'Genre' search mode.
            playGenre(genre);

        } else if (mediaFocus.compareTo(MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE) == 0) {
            // 'Artist' search mode.
            playArtist(artist, genre);

        } else if (mediaFocus.compareTo(MediaStore.Audio.Albums.ENTRY_CONTENT_TYPE) == 0) {
            // 'Album' search mode.
            playAlbum(album, artist);

        } else if (mediaFocus.compareTo("vnd.android.cursor.item/audio") == 0) {
            // 'Song' search mode.
            playSong(album, artist, genre, title);

        } else if (mediaFocus.compareTo(MediaStore.Audio.Playlists.ENTRY_CONTENT_TYPE) == 0) {
            // 'Playlist' search mode.
            playPlaylist(album, artist, genre, playlist, title);
        }
    }
}

הערה חדשה

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

יצירת הערה

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

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

פעולה

ACTION_CREATE_NOTE

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

ללא

סוג MIME

PLAIN_TEXT_TYPE

"*/*"

תוספות

EXTRA_NAME

מחרוזת שמציינת את הכותרת או הנושא של ההערה.

EXTRA_TEXT

מחרוזת שמציינת את הטקסט של ההערה.

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

Kotlin

fun createNote(subject: String, text: String) {
    val intent = Intent(NoteIntents.ACTION_CREATE_NOTE).apply {
        putExtra(NoteIntents.EXTRA_NAME, subject)
        putExtra(NoteIntents.EXTRA_TEXT, text)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

Java

public void createNote(String subject, String text) {
    Intent intent = new Intent(NoteIntents.ACTION_CREATE_NOTE)
            .putExtra(NoteIntents.EXTRA_NAME, subject)
            .putExtra(NoteIntents.EXTRA_TEXT, text);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

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

<activity ...>
    <intent-filter>
        <action android:name="com.google.android.gms.actions.CREATE_NOTE" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="*/*" />
    </intent-filter>
</activity>

טלפון

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

איך מתקשרים

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

פעולות קוליות ב-Google Voice

• ‫"call 555-5555" (להתקשר למספר 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

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

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

Kotlin

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

Java

public void dialPhoneNumber(String phoneNumber) {
    Intent intent = new Intent(Intent.ACTION_DIAL);
    intent.setData(Uri.parse("tel:" + phoneNumber));
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

חיפוש

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

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

פעולות קוליות ב-Google Voice

• ‫"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.

תוספות

QUERY

מחרוזת שמכילה את שאילתת החיפוש.

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

<activity android:name=".SearchActivity">
    <intent-filter>
        <action android:name="com.google.android.gms.actions.SEARCH_ACTION"/>
        <category android:name="android.intent.category.DEFAULT"/>
    </intent-filter>
</activity>

חיפוש באינטרנט

כדי להתחיל חיפוש באינטרנט, משתמשים בפעולה ACTION_WEB_SEARCH ומציינים את מחרוזת החיפוש בתוספת SearchManager.QUERY.

פעולה

ACTION_WEB_SEARCH

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

ללא

סוג MIME

ללא

תוספות

SearchManager.QUERY

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

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

Kotlin

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

Java

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

הגדרות

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

פעולה

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

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

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

ללא

סוג MIME

ללא

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

Kotlin

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

Java

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

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

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

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

כדי ליזום הודעת טקסט SMS או MMS, משתמשים באחת מפעולות ה-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"

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

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

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

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

פעולות קוליות ב-Google Voice

• ‫"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‏ (ADB‏)

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

1. מגדירים מכשיר Android לפיתוח או משתמשים במכשיר וירטואלי.
2. מתקינים גרסה של האפליקציה שמטפלת ב-Intents שרוצים לתמוך בהם.
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. אם מגדירים את מסנני הכוונה הנדרשים, מטפלים בכוונה.

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