שינוי אנשי קשר באמצעות כוונות

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

השימוש ב-Intent כדי להוסיף או לעדכן איש קשר יחיד הוא הדרך המועדפת לשינוי של ספק אנשי הקשר, מהסיבות הבאות:

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

הוספת איש קשר חדש לפי כוונת רכישה

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

הוספת איש קשר באמצעות אפליקציית 'אנשי קשר' מוסיפה איש קשר גולמי חדש לאנשי הקשר טבלת ContactsContract.RawContacts של הספק. אם יש צורך, באפליקציית אנשי הקשר יוצג למשתמש חלון עם בקשה לבחור את סוג החשבון ואת החשבון שבו רוצים להשתמש בזמן יצירת איש הקשר הגולמי. אפליקציית 'אנשי קשר' גם מודיעה למשתמשים אם איש הקשר הגולמי כבר קיים. לאחר מכן יש למשתמשים אפשרות של ביטול ההוספה, ובמקרה כזה לא ייווצר איש קשר. למידע נוסף על אנשי קשר בפורמט גולמי, אפשר לעיין במדריך API של Contacts Provider.

יצירת Intent

כדי להתחיל, צריך ליצור אובייקט Intent חדש עם הפעולה Intents.Insert.ACTION. מגדירים את סוג ה-MIME כRawContacts.CONTENT_TYPE. לדוגמה:

...
// Creates a new Intent to insert a contact
val intent = Intent(ContactsContract.Intents.Insert.ACTION).apply {
    // Sets the MIME type to match the Contacts Provider
    type = ContactsContract.RawContacts.CONTENT_TYPE
}

...
// Creates a new Intent to insert a contact
Intent intent = new Intent(ContactsContract.Intents.Insert.ACTION);
// Sets the MIME type to match the Contacts Provider
intent.setType(ContactsContract.RawContacts.CONTENT_TYPE);

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

private var emailAddress: EditText? = null
private var phoneNumber: EditText? = null
...
/* Assumes EditText fields in your UI contain an email address
 * and a phone number.
 *
 */
emailAddress = findViewById(R.id.email)
phoneNumber = findViewById(R.id.phone)
...
/*
 * Inserts new data into the Intent. This data is passed to the
 * contacts app's Insert screen
 */
intent.apply {
    // Inserts an email address
    putExtra(ContactsContract.Intents.Insert.EMAIL, emailAddress?.text)
    /*
     * In this example, sets the email type to be a work email.
     * You can set other email types as necessary.
     */
    putExtra(
            ContactsContract.Intents.Insert.EMAIL_TYPE,
            ContactsContract.CommonDataKinds.Email.TYPE_WORK
    )
    // Inserts a phone number
    putExtra(ContactsContract.Intents.Insert.PHONE, phoneNumber?.text)
    /*
     * In this example, sets the phone type to be a work phone.
     * You can set other phone types as necessary.
     */
    putExtra(
            ContactsContract.Intents.Insert.PHONE_TYPE,
            ContactsContract.CommonDataKinds.Phone.TYPE_WORK
    )
}

private EditText emailAddress = null;
private EditText phoneNumber = null;
...
/* Assumes EditText fields in your UI contain an email address
 * and a phone number.
 *
 */
emailAddress = (EditText) findViewById(R.id.email);
phoneNumber = (EditText) findViewById(R.id.phone);
...
/*
 * Inserts new data into the Intent. This data is passed to the
 * contacts app's Insert screen
 */
// Inserts an email address
intent.putExtra(ContactsContract.Intents.Insert.EMAIL, emailAddress.getText())
/*
 * In this example, sets the email type to be a work email.
 * You can set other email types as necessary.
 */
      .putExtra(ContactsContract.Intents.Insert.EMAIL_TYPE,
            ContactsContract.CommonDataKinds.Email.TYPE_WORK)
// Inserts a phone number
      .putExtra(ContactsContract.Intents.Insert.PHONE, phoneNumber.getText())
/*
 * In this example, sets the phone type to be a work phone.
 * You can set other phone types as necessary.
 */
      .putExtra(ContactsContract.Intents.Insert.PHONE_TYPE,
            ContactsContract.CommonDataKinds.Phone.TYPE_WORK);

אחרי שיוצרים את Intent, שולחים אותו באמצעות קריאה ל-startActivity().

    /* Sends the Intent
     */
    startActivity(intent)

    /* Sends the Intent
     */
    startActivity(intent);

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

עריכת איש קשר קיים באמצעות כוונה

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

כדי לערוך איש קשר קיים באמצעות כוונה, צריך לבצע תהליך דומה להוספת איש קשר. יוצרים כוונה כפי שמתואר בקטע הוספת איש קשר חדש באמצעות כוונה, אבל מוסיפים לכוונה את הערך של Contacts.CONTENT_LOOKUP_URI של איש הקשר ואת סוג ה-MIME Contacts.CONTENT_ITEM_TYPE. אם רוצים לערוך את איש הקשר עם פרטים שכבר קיימים, אפשר להוסיף אותם לנתונים המורחבים של הכוונה. שימו לב שחלק לא ניתן לערוך עמודות שמות באמצעות Intent. העמודות האלה מפורטות הקטע בהפניית ה-API של המחלקה ContactsContract.Contacts תחת הכותרת Update (עדכון).

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

יצירת הכוונה

כדי לערוך איש קשר, צריך להתקשר למספר Intent(action) למספר יוצרים Intent עם הפעולה ACTION_EDIT. קוראים ל-setDataAndType() כדי להגדיר את ערך הנתונים של הכוונה ל-Contacts.CONTENT_LOOKUP_URI של איש הקשר ואת סוג ה-MIME לסוג ה-MIME של Contacts.CONTENT_ITEM_TYPE. קריאה ל-setType() מחליפה את ערך הנתונים הנוכחי של Intent, לכן צריך להגדיר את הנתונים ואת סוג ה-MIME בו-זמנית.

כדי לקבל את הערך של Contacts.CONTENT_LOOKUP_URI של איש קשר, צריך להפעיל את Contacts.getLookupUri(id, lookupkey) עם הערכים של Contacts._ID ו-Contacts.LOOKUP_KEY של איש הקשר כארגומנטים.

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

בקטע הקוד הבא מוסבר איך ליצור Intent:

    // The Cursor that contains the Contact row
    var mCursor: Cursor? = null
    // The index of the lookup key column in the cursor
    var lookupKeyIndex: Int = 0
    // The index of the contact's _ID value
    var idIndex: Int = 0
    // The lookup key from the Cursor
    var currentLookupKey: String? = null
    // The _ID value from the Cursor
    var currentId: Long = 0
    // A content URI pointing to the contact
    var selectedContactUri: Uri? = null
    ...
    /*
     * Once the user has selected a contact to edit,
     * this gets the contact's lookup key and _ID values from the
     * cursor and creates the necessary URI.
     */
    mCursor?.apply {
        // Gets the lookup key column index
        lookupKeyIndex = getColumnIndex(ContactsContract.Contacts.LOOKUP_KEY)
        // Gets the lookup key value
        currentLookupKey = getString(lookupKeyIndex)
        // Gets the _ID column index
        idIndex = getColumnIndex(ContactsContract.Contacts._ID)
        currentId = getLong(idIndex)
        selectedContactUri = ContactsContract.Contacts.getLookupUri(currentId, mCurrentLookupKey)
    }

    // Creates a new Intent to edit a contact
    val editIntent = Intent(Intent.ACTION_EDIT).apply {
        /*
         * Sets the contact URI to edit, and the data type that the
         * Intent must match
         */
        setDataAndType(selectedContactUri, ContactsContract.Contacts.CONTENT_ITEM_TYPE)
    }

    // The Cursor that contains the Contact row
    public Cursor mCursor;
    // The index of the lookup key column in the cursor
    public int lookupKeyIndex;
    // The index of the contact's _ID value
    public int idIndex;
    // The lookup key from the Cursor
    public String currentLookupKey;
    // The _ID value from the Cursor
    public long currentId;
    // A content URI pointing to the contact
    Uri selectedContactUri;
    ...
    /*
     * Once the user has selected a contact to edit,
     * this gets the contact's lookup key and _ID values from the
     * cursor and creates the necessary URI.
     */
    // Gets the lookup key column index
    lookupKeyIndex = mCursor.getColumnIndex(ContactsContract.Contacts.LOOKUP_KEY);
    // Gets the lookup key value
    currentLookupKey = mCursor.getString(lookupKeyIndex);
    // Gets the _ID column index
    idIndex = mCursor.getColumnIndex(ContactsContract.Contacts._ID);
    currentId = mCursor.getLong(idIndex);
    selectedContactUri =
            Contacts.getLookupUri(currentId, mCurrentLookupKey);
    ...
    // Creates a new Intent to edit a contact
    Intent editIntent = new Intent(Intent.ACTION_EDIT);
    /*
     * Sets the contact URI to edit, and the data type that the
     * Intent must match
     */
    editIntent.setDataAndType(selectedContactUri, ContactsContract.Contacts.CONTENT_ITEM_TYPE);

הוספת דגל הניווט

בגרסה Android 4.0 (גרסת API 14) ואילך, בעיה באפליקציית 'אנשי קשר' גורמת לבעיה ניווט. כשהאפליקציה שולחת כוונה לעריכה לאפליקציית אנשי הקשר, והמשתמשים עורכים ומשמרים איש קשר, כשהם לוחצים על הקודם הם רואים את המסך של רשימת אנשי הקשר. כדי לחזור לאפליקציה, הם צריכים ללחוץ על Recents (מהזמן האחרון) ולבחור את האפליקציה.

כדי לעקוף את הבעיה הזו ב-Android 4.0.3 (גרסת API 15) ואילך, מוסיפים את מפתח הנתונים המורחב finishActivityOnSaveCompleted ל-intent, עם הערך true. גרסאות Android שקדמו ל-Android 4.0 מקבלות את המפתח הזה, אבל אין לו השפעה. כדי להגדיר את לנתונים מורחבים:

    // Sets the special extended data for navigation
    editIntent.putExtra("finishActivityOnSaveCompleted", true)

    // Sets the special extended data for navigation
    editIntent.putExtra("finishActivityOnSaveCompleted", true);

הוספה של עוד נתונים מורחבים

כדי להוסיף עוד נתונים מורחבים ל-Intent, צריך להתקשר putExtra() לפי הצורך. כדי להוסיף נתונים מורחבים עבור שדות נפוצים של אנשי קשר, אפשר להשתמש בערכי המפתח שמצוינים ב Intents.Insert חשוב לזכור שאי אפשר לשנות חלק מהעמודות בטבלה ContactsContract.Contacts. העמודות האלה מפורטות בקטע הסיכום בהפניית ה-API לכיתה ContactsContract.Contacts מתחת לכותרת 'עדכון'.

שליחת הכוונה

לסיום, שולחים את הכוונה שיצרתם. לדוגמה:

    // Sends the Intent
    startActivity(editIntent)

    // Sends the Intent
    startActivity(editIntent);

לאפשר למשתמשים לבחור אם להוסיף או לערוך באמצעות כוונה

כדי לאפשר למשתמשים לבחור אם להוסיף איש קשר או לערוך איש קשר קיים, שולחים Intent עם הפעולה ACTION_INSERT_OR_EDIT. לדוגמה, אפליקציה של תוכנת אימייל יכולה לאפשר למשתמשים להוסיף כתובת אימייל נכנסת לאיש קשר חדש, או להוסיף אותה ככתובת נוספת הכתובת של איש קשר קיים. צריך להגדיר את סוג ה-MIME של ה-Intent הזה בתור Contacts.CONTENT_ITEM_TYPE, אבל לא להגדיר את ה-URI של הנתונים.

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

    // Creates a new Intent to insert or edit a contact
    val intentInsertEdit = Intent(Intent.ACTION_INSERT_OR_EDIT).apply {
        // Sets the MIME type
        type = ContactsContract.Contacts.CONTENT_ITEM_TYPE
    }
    // Add code here to insert extended data, if desired

    // Sends the Intent with an request ID
    startActivity(intentInsertEdit)

    // Creates a new Intent to insert or edit a contact
    Intent intentInsertEdit = new Intent(Intent.ACTION_INSERT_OR_EDIT);
    // Sets the MIME type
    intentInsertEdit.setType(ContactsContract.Contacts.CONTENT_ITEM_TYPE);
    // Add code here to insert extended data, if desired
    ...
    // Sends the Intent with an request ID
    startActivity(intentInsertEdit);