מתן הרשאה לאפליקציות אחרות להתחיל את הפעילות

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

לדוגמה, אם אתם מפתחים אפליקציה חברתית שמאפשרת לשתף הודעות או תמונות עם חברים של המשתמש, אתם צריכים לתמוך ב-intent‏ ACTION_SEND. לאחר מכן, כשמשתמשים יפעילו פעולת שיתוף מאפליקציה אחרת, האפליקציה שלכם תופיע כאפשרות בתיבת הדו-שיח לבחירה (שנקראת גם תיבת דו-שיח להסרת דו-משמעות), כמו שמוצג באיור 1.

איור 1. תיבת הדו-שיח לבחירה.

כדי לאפשר לאפליקציות אחרות להתחיל את הפעילות שלכם בדרך הזו, צריך להוסיף רכיב <intent-filter> לקובץ המניפסט שלכם עבור רכיב <activity> המתאים.

כשהאפליקציה מותקנת במכשיר, המערכת מזהה את מסנני הכוונות ומוסיפה את המידע לקטלוג פנימי של כוונות שנתמכות על ידי כל האפליקציות המותקנות. כשאפליקציה מתקשרת אל startActivity() או אל startActivityForResult() עם אובייקט Intent מרומז, המערכת בודקת אם יש Activity שיכולות להגיב ל-Intent.

הוספת מסנן Intent

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

יכול להיות שהמערכת תשלח Intent ל-Activity מסוים אם ל-Activity הזו יש מסנן Intent שעומד בקריטריונים הבאים של אובייקט Intent:

פעולה

מחרוזת שכוללת את שם הפעולה לביצוע. בדרך כלל אחד מהערכים שמוגדרים בפלטפורמה, כמו ACTION_SEND או ACTION_VIEW.

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

נתונים

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

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

הערה: אם אתם לא צריכים להצהיר על פרטים ספציפיים לגבי הנתונים Uri, כמו מקרים שבהם הפעילות מטפלת בסוג אחר של נתונים מסוג 'extra' במקום ב-URI, אתם יכולים לציין רק את המאפיין android:mimeType כדי להצהיר על סוג הנתונים שהפעילות מטפלת בהם, כמו text/plain או image/jpeg.

קטגוריה

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

מציינים את זה במסנן ה-Intent באמצעות הרכיב <category>.

במסנן ה-Intent, אפשר להצהיר אילו קריטריונים הפעילות מקבלת. כדי לעשות זאת, צריך להצהיר על כל אחד מהם באמצעות רכיבי XML תואמים שמוטמעים ברכיב <intent-filter>.

לדוגמה, הנה פעילות עם מסנן Intent שמטפל ב-Intent ‏ACTION_SEND כשסוג הנתונים הוא טקסט או תמונה:

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

הערה: אם רוצים שהסמל בתיבת הדו-שיח לבחירת פעילות יהיה שונה מסמל ברירת המחדל של הפעילות, מוסיפים את android:icon לרכיב <intent-filter>.

כל כוונת כניסה מציינת רק פעולה אחת וסוג נתונים אחד, אבל אפשר להצהיר על כמה מופעים של הרכיבים <action>, <category> ו-<data> בכל <intent-filter>.

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

לדוגמה, נניח שהפעילות מטפלת בטקסט ובתמונות גם עבור כוונות ACTION_SEND וגם עבור כוונות ACTION_SENDTO. במקרה כזה, צריך להגדיר שני מסנני כוונות נפרדים לשתי הפעולות, כי כוונת ACTION_SENDTO חייבת להשתמש בנתונים Uri כדי לציין את כתובת הנמען באמצעות סכימת ה-URI‏ send או sendto. כך זה נראה בדוגמה הבאה:

<activity android:name="ShareActivity">
    <!-- Filter for sending text; accepts SENDTO action with sms URI schemes -->
    <intent-filter>
        <action android:name="android.intent.action.SENDTO"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:scheme="sms" />
        <data android:scheme="smsto" />
    </intent-filter>
    <!-- Filter for sending text or images; accepts SEND action and text or image data -->
    <intent-filter>
        <action android:name="android.intent.action.SEND"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:mimeType="image/*"/>
        <data android:mimeType="text/plain"/>
    </intent-filter>
</activity>

הערה: כדי לקבל Intents משתמעים, צריך לכלול את הקטגוריה CATEGORY_DEFAULT במסנן ה-Intent. השיטות startActivity() ו-startActivityForResult() מתייחסות לכל הכוונות כאילו הן הוגדרו בקטגוריה CATEGORY_DEFAULT. אם לא מצהירים על כך במסנן ה-Intent, לא ניתן לפתור אף Intent משתמע לפעילות.

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

טיפול בכוונת המשתמש בפעילות

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

כשמתחילה הפעילות, מתבצעת קריאה ל-getIntent() כדי לאחזר את Intent שהתחיל את הפעילות. אפשר לעשות את זה בכל שלב במהלך מחזור החיים של הפעילות, אבל בדרך כלל עושים את זה במהלך קריאות חוזרות מוקדמות, כמו onCreate() או onStart().

כך זה נראה בדוגמה הבאה:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    setContentView(R.layout.main)

    val data: Uri? = intent?.data

    // Figure out what to do based on the intent type
    if (intent?.type?.startsWith("image/") == true) {
        // Handle intents with image data
    } else if (intent?.type == "text/plain") {
        // Handle intents with text
    }
}

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    setContentView(R.layout.main);

    // Get the intent that started this activity
    Intent intent = getIntent();
    Uri data = intent.getData();

    // Figure out what to do based on the intent type
    if (intent.getType().indexOf("image/") != -1) {
        // Handle intents with image data
    } else if (intent.getType().equals("text/plain")) {
        // Handle intents with text
    }
}

החזרת תוצאה

אם רוצים להחזיר תוצאה לפעילות שהפעילה את הפעילות הנוכחית, קוראים ל-setResult() כדי לציין את קוד התוצאה ואת התוצאה Intent. כשסיימתם את הפעולה והמשתמש חוזר לפעילות המקורית, צריך להתקשר אל finish() כדי לסגור את הפעילות ולהרוס אותה. כך זה נראה בדוגמה הבאה:

// Create intent to deliver some kind of result data
Intent("com.example.RESULT_ACTION", Uri.parse("content://result_uri")).also { result ->
    setResult(Activity.RESULT_OK, result)
}
finish()

// Create intent to deliver some kind of result data
Intent result = new Intent("com.example.RESULT_ACTION", Uri.parse("content://result_uri"));
setResult(Activity.RESULT_OK, result);
finish();

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

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

אם אתם רק צריכים להחזיר מספר שלם שמציין אחת מכמה אפשרויות תוצאה, אתם יכולים להגדיר את קוד התוצאה לכל ערך שגבוה מ-0. אם אתם משתמשים בקוד התוצאה כדי להעביר מספר שלם ולא צריך לכלול את Intent, אתם יכולים לקרוא ל-setResult() ולהעביר רק קוד תוצאה:

setResult(RESULT_COLOR_RED)
finish()

setResult(RESULT_COLOR_RED);
finish();

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

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